Breeder API

Breeder API overview

An introduction to the Herpify Breeder API — what it is, how authentication works, and how to get started.

What is the Breeder API?

The Breeder API lets you read and write your Herpify data from external tools — spreadsheets, scripts, inventory systems, or your own website. Instead of logging in and clicking through the interface, you can automate repetitive tasks or pull your data into whatever software you already use.

  • Pull your active listings into a stock spreadsheet
  • Sync sold animals and update listing statuses automatically
  • Read your analytics and reviews from a dashboard you build
  • Manage pairings and waitlists from your own breeding software
  • Upload photos directly from a script or desktop app

Who can use it?

API access is exclusive to the Breeder subscription tier. Your subscription must be active or in a trial period. If you're on a Starter or Trader plan and want API access, upgrade at Account Settings → Subscription.

Base URL

All API endpoints live under this base URL:

https://herpify.com/api/breeder

Authentication

Every request needs an API key in the `Authorization` header. Generate keys in Account Settings → API Keys. Your key starts with `hm_live_` and is shown only once when created — store it securely straight away.

Example request with authentication

curl https://herpify.com/api/breeder/profile \
  -H "Authorization: Bearer hm_live_your_key_here"

Important note

Never put your API key in client-side code, public repositories, or browser URLs. Treat it like a password.

Rate limits

You can make 1,000 requests per hour per key. If you exceed this, you'll receive a `429 Too Many Requests` response. Every response includes three headers so you can track your usage:

  • `X-RateLimit-Limit` — your total limit (1000)
  • `X-RateLimit-Remaining` — requests left in the current window
  • `X-RateLimit-Reset` — Unix timestamp when the window resets

Response format

All successful responses use this envelope format. List responses include a `meta` object for pagination.

Successful response

{
  "data": { ... },
  "meta": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "clx1a2b3c4d5e6f7g"
  }
}

Error response

{
  "error": "A human-readable description of what went wrong",
  "code": "MACHINE_READABLE_CODE",
  "details": [...]
}

Was this article helpful?