Overview
Get an API key
v1 · REST · JSON

Husbandry.Pro API

Read and write everything in your account — animals, activities, breeding, medical, customers, environment, documents — from your own software. Scoped keys, cursor-paginated lists, webhooks when something changes, and an ingest path for any sensor. The OpenAPI description is generated from the same code that serves the requests.

Make your first request

From a fresh key to a recorded feeding in about five minutes.

Base URL
All requests go to https://next.husbandry.pro/api/v1. The host is https://next.husbandry.pro; paths in these docs are relative to /api/v1 on that host. The classic husbandry.pro domain is a separate, older system and does not serve this API.
  1. 1

    Create a key

    Open your profile, choose the API tab, create a key, and tick the permissions it needs. Copy it — it is shown once.

    Open your API settings →
  2. 2

    Check it works

    GET /me returns the account behind the key, the scopes it holds, and your rate limits — so you know what you can reach without probing for 403s.

  3. 3

    Read your data

    GET /animals, filtered however you like. Every list is cursor-paginated: follow next_cursor until has_more is false.

  4. 4

    Write something

    POST /activities records a feeding, weight, or shed. Send an Idempotency-Key so a retry can never double-write.

Full curl examples and responses are in the guide.

Everything in the API

84 endpoints across 14 areas. This list is generated from the running code; click any row for its parameters, body fields, response, and errors.

Account

1 endpoint
GET/meGet the current account

Animals

6 endpoints
GET/animal-typesList species in this account
GET/animalsList animals
POST/animalsCreate an animal
DELETE/animals/{id}Delete an animal
GET/animals/{id}Get an animal
PATCH/animals/{id}Update an animal

Activities

6 endpoints
GET/activitiesList activities
POST/activitiesRecord an activity
DELETE/activities/{id}Delete an activity
GET/activities/{id}Get an activity
PATCH/activities/{id}Update an activity
GET/activity-typesList activity types

Breeding

10 endpoints
GET/breeding/clutchesList clutches
POST/breeding/clutchesCreate a clutch
DELETE/breeding/clutches/{id}Delete a clutch
GET/breeding/clutches/{id}Get a clutch
PATCH/breeding/clutches/{id}Update a clutch
GET/breeding/recordsList breeding records
POST/breeding/recordsCreate a breeding record
DELETE/breeding/records/{id}Delete a breeding record
GET/breeding/records/{id}Get a breeding record
PATCH/breeding/records/{id}Update a breeding record

Medical

5 endpoints
GET/medical/conditionsList diagnosed conditions
POST/medical/conditionsRecord a diagnosed condition
DELETE/medical/conditions/{id}Delete a condition
GET/medical/conditions/{id}Get a diagnosed condition
PATCH/medical/conditions/{id}Update or resolve a condition

Environment

7 endpoints
GET/environment/environmentsList environments
POST/environment/environmentsCreate an environment
DELETE/environment/environments/{id}Delete an environment
GET/environment/environments/{id}Get an environment
PATCH/environment/environments/{id}Update an environment
GET/environment/metricsList available metrics
GET/environment/readingsQuery sensor readings

Documents

5 endpoints
GET/documentsList documents
POST/documentsUpload a document
DELETE/documents/{id}Delete a document
GET/documents/{id}Get a document's metadata
PATCH/documents/{id}Retitle or refile a document

Customers

11 endpoints
GET/contactsList contacts
POST/contactsCreate a contact
DELETE/contacts/{id}Delete a contact
GET/contacts/{id}Get a contact
PATCH/contacts/{id}Update a contact
GET/sales/invoicesList invoices
POST/sales/invoicesCreate an invoice
DELETE/sales/invoices/{id}Delete an invoice
GET/sales/invoices/{id}Get an invoice with its lines and payments
PATCH/sales/invoices/{id}Update or void an invoice
POST/sales/invoices/{id}/paymentsRecord a payment

Reference

1 endpoint
GET/speciesList species reference data

Isopods

9 endpoints
GET/isopod/availabilityList sellable isopod availability
GET/isopod/culturesList isopod cultures
GET/isopod/cultures/{id}Get an isopod culture
GET/isopod/cultures/{id}/observationsList observations for a culture
POST/isopod/cultures/{id}/observationsRecord an observation
GET/isopod/issuesList isopod issues
GET/isopod/lotsList isopod sale lots
GET/isopod/salesList isopod sales
GET/isopod/sales/{id}Get an isopod sale

Feeder Farm

6 endpoints
GET/feeder-farm/culturesList feeder cultures
GET/feeder-farm/cultures/{id}Get a feeder culture
POST/feeder-farm/cultures/{id}/careRecord a care event
GET/feeder-farm/planGet the 14-day plan
GET/feeder-farm/salesList feeder orders
GET/feeder-farm/stockList linked feeder stock

Webhooks

5 endpoints
GET/webhooks/endpointsList webhook endpoints
POST/webhooks/endpointsCreate a webhook endpoint
DELETE/webhooks/endpoints/{id}Delete a webhook endpoint
GET/webhooks/endpoints/{id}Get a webhook endpoint
PATCH/webhooks/endpoints/{id}Update a webhook endpoint

Sensors

11 endpoints
POST/sensors/claim/startStart pairing a headless device
GET/sensors/claim/statusPoll for a pairing result (deprecated query-string form)
POST/sensors/claim/statusPoll for a pairing result
GET/sensors/devicesList sensor devices
POST/sensors/devicesRegister a sensor device
DELETE/sensors/devices/{id}Delete a device
GET/sensors/devices/{id}Get a device and its channel configuration
PATCH/sensors/devices/{id}Update a device
GET/sensors/pingSubmit readings from constrained firmware
POST/sensors/pingSubmit readings from constrained firmware
POST/sensors/readingsSubmit sensor readings

Platform

1 endpoint
GET/statusAPI status

Conventions at a glance

Seven things that hold for every endpoint. Each links to the guide that covers it.

Connecting a sensor

Any device that can make an HTTPS request can push readings, using a device key that can do nothing else. Three guides cover it.

  • — From nothing to a stored temperature in about five minutes.
  • — A complete ESP32 sketch, plus the fallbacks for constrained firmware.
  • — Why devices report channels rather than places, and what that buys you.