Breeder API

Pairing records — API reference

How to create and manage breeding pair records on Herpify using the Breeder API.

What it does

The pairings endpoints let you manage your breeding records directly from external tools. You can record which animals you've paired, when, and what you expect from the clutch or birth, set whether a waitlist is open for that pairing, and keep your Herpify pairing records in sync with your own breeding software.

Who can access it

Breeder plan subscribers only. Authenticate with your API key in the `Authorization: Bearer` header.

List pairings — GET /api/breeder/pairings

Returns a paginated list of your pairing records, newest first.

Parameter	Type	Required	Description
limit	number	Optional	How many records per page. Between 1 and 100. Default is 20.
cursor	string	Optional	Pagination cursor from `meta.nextCursor` in the previous response.

Create a pairing — POST /api/breeder/pairings

Records a new breeding pairing.

Parameter	Type	Required	Description
sireSpecies	string	Required	Scientific or common name of the sire's species. E.g. "Python regius".
sireName	string	Optional	Your name for the sire. E.g. "Thunderstruck".
sireTraits	string	Optional	Morph or trait description for the sire. E.g. "Banana Pastel".
dameSpecies	string	Required	Scientific or common name of the dame's species.
dameName	string	Optional	Your name for the dame. E.g. "Luna".
dameTraits	string	Optional	Morph or trait description for the dame. E.g. "Het Clown Het Ghost".
pairingDate	string	Optional	Date of the pairing in ISO 8601 format (YYYY-MM-DD).
expectedDate	string	Optional	Expected clutch or birth date in ISO 8601 format (YYYY-MM-DD).
waitlistOpen	boolean	Optional	Set to true if you want to accept waitlist enquiries for this clutch. Default is false.

Update a pairing — PATCH /api/breeder/pairings/:id

Update any field on a pairing record. Send only the fields you want to change.

Delete a pairing — DELETE /api/breeder/pairings/:id

Permanently deletes the pairing record. This is a hard delete and cannot be undone.

Important note

Unlike listings, pairing deletions are permanent. Double-check before deleting.

Example response

Pairing record

{
  "data": {
    "id": "clxf6g7h8i9j0k1l2",
    "slug": "banana-pastel-x-het-clown-ball-python-2026",
    "sireSpecies": "Python regius",
    "sireName": "Thunderstruck",
    "sireTraits": "Banana Pastel",
    "dameSpecies": "Python regius",
    "dameName": "Luna",
    "dameTraits": "Het Clown Het Ghost",
    "pairingDate": "2026-02-14T00:00:00.000Z",
    "expectedDate": "2026-06-01T00:00:00.000Z",
    "waitlistOpen": true,
    "createdAt": "2026-02-14T10:00:00.000Z"
  }
}

Real-world example

You use dedicated breeding software to track all your Ball Python pairings. When you record a new pair in your software, a webhook fires a POST request to the Herpify pairings endpoint, syncing the record automatically. When your expected date changes after a second pairing attempt, the same software sends a PATCH with the updated date. Your Herpify profile stays current without any manual data entry.

Was this article helpful?