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

36 endpoints across 12 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

3 endpoints
GET/activitiesList activities
POST/activitiesRecord an activity
GET/activity-typesList activity types

Breeding

2 endpoints
GET/breeding/clutchesList clutches
GET/breeding/recordsList breeding records

Medical

1 endpoint
GET/medical/conditionsList diagnosed conditions

Environment

3 endpoints
GET/environment/environmentsList environments
GET/environment/metricsList available metrics
GET/environment/readingsQuery sensor readings

Documents

1 endpoint
GET/documentsList documents

Customers

2 endpoints
GET/contactsList contacts
GET/sales/invoicesList invoices

Reference

1 endpoint
GET/speciesList species reference data

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

10 endpoints
POST/sensors/claim/startStart pairing a headless device
GET/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.