Breeder API

Managing your listings — API reference

How to list, create, update, and delete your Herpify listings using the Breeder API.

What it does

The listings endpoints give you full control over your marketplace listings: read them all in one go, create new ones without opening the website, update a price or status with a single call, or remove a listing you no longer need.

Who can access it

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

List your listings — GET /api/breeder/listings

Returns a paginated list of your listings, newest first.

Parameter	Type	Required	Description
status	string	Optional	Filter by listing status: DRAFT, ACTIVE, SOLD, EXPIRED, or ARCHIVED. Leave blank to get all statuses.
limit	number	Optional	How many results to return per request. Between 1 and 100. Default is 20.
cursor	string	Optional	Pagination cursor. Copy the `nextCursor` value from the previous response's `meta` object.

Create a listing — POST /api/breeder/listings

Creates a new listing. New listings always start in **DRAFT** status — they're not visible to buyers until you publish them. To publish, send a PATCH request with `{ "status": "ACTIVE" }`.

Parameter	Type	Required	Description
title	string	Required	The listing headline. Maximum 200 characters.
description	string	Optional	Full description of the animal, including care notes, feeding history, temperament. Supports plain text.
species	string	Required	Scientific or common name. E.g. "Python regius" or "Ball Python".
price	number	Required	Price in AUD cents. E.g. 85000 for $850.00. Maximum is 5,000,000 (AUD $50,000).
sex	string	Optional	MALE, FEMALE, or UNKNOWN.
quantity	number	Optional	Number of animals in this listing. Default is 1.
location	string	Optional	City or region where the animal is located. E.g. "Brisbane, QLD".
tags	string[]	Optional	Array of trait or morph tags. E.g. ["pastel", "het-clown", "cb2025"].

Important note

Listings automatically expire 180 days after creation. You can renew from the dashboard or by patching a new `expiresAt`.

Update a listing — PATCH /api/breeder/listings/:id

Update any field on an existing listing. Send only the fields you want to change — everything else stays the same.

Parameter	Type	Required	Description
title	string	Optional	New listing title.
description	string	Optional	Updated description.
price	number	Optional	New price in AUD cents.
status	string	Optional	New status: DRAFT, ACTIVE, SOLD, EXPIRED, or ARCHIVED.
sex	string	Optional	MALE, FEMALE, or UNKNOWN.
quantity	number	Optional	Updated quantity.
tags	string[]	Optional	Replaces the entire tag list.

Delete a listing — DELETE /api/breeder/listings/:id

Soft-deletes the listing and sets its status to ARCHIVED. The listing is removed from public view immediately. This cannot be undone via the API — if you need to recover it, contact support.

Example responses

Create listing response (201)

{
  "data": {
    "id": "clxb1c2d3e4f5g6h7",
    "title": "Piebald Ball Python — High White",
    "slug": "piebald-ball-python-high-white-ghi789",
    "status": "DRAFT",
    "price": 85000,
    "expiresAt": "2026-09-17T08:00:00.000Z",
    "createdAt": "2026-03-21T08:00:00.000Z"
  }
}

Real-world example

You breed Blue-Tongue Skinks and keep a spreadsheet of your hatchlings. When a new hatchling is ready to sell, a script reads the row from your sheet (species, DOH, price, sex) and calls POST /api/breeder/listings to create a draft. You then review the draft in Herpify, add photos using the Media API, and publish. The whole process takes seconds instead of minutes.

Was this article helpful?