Saved searches — API reference
How to manage your saved marketplace searches and email alert settings using the Herpify Breeder API.
What it does
Saved searches let you bookmark specific marketplace queries so you can re-run them anytime, and optionally receive email alerts when new listings match your criteria. The API lets you create, list, update, and delete saved searches programmatically.
Who can access it
Breeder plan subscribers only. Authenticate with your API key in the `Authorization: Bearer` header.
List saved searches — GET /api/breeder/saved-searches
Returns all your saved searches with their current alert settings.
Create a saved search — POST /api/breeder/saved-searches
Creates a new saved search. Names must be unique — if you try to create one with a name that already exists, you'll get a `409 Conflict` error.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Required | A label for this search so you can identify it. Must be unique across your saved searches. Maximum 100 characters. |
| filters | object | Required | The search criteria as a JSON object. Use the same filter keys available in the marketplace search. |
| alertFrequency | string | Optional | How often to email you about new matches: INSTANT (as soon as a match is listed), DAILY (once per day digest), or WEEKLY (once per week digest). Leave blank for no alerts. |
Update a saved search — PATCH /api/breeder/saved-searches/:id
Update the name, filters, or alert frequency for a saved search.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Optional | New name. Must be unique. |
| filters | object | Optional | Replacement filters object. The entire filters object is replaced, not merged. |
| alertFrequency | string | Optional | INSTANT, DAILY, WEEKLY, or null to disable alerts. |
Delete a saved search — DELETE /api/breeder/saved-searches/:id
Permanently deletes the saved search. Email alerts for this search stop immediately.
Example — create a saved search
Request body
{
"name": "Female Piebald BP under $3k",
"filters": {
"species": "Python regius",
"traits": ["piebald"],
"sex": "FEMALE",
"maxPrice": 300000
},
"alertFrequency": "DAILY"
}Response
{
"data": {
"id": "clxh8i9j0k1l2m3n4",
"name": "Female Piebald BP under $3k",
"filters": {
"species": "Python regius",
"traits": ["piebald"],
"sex": "FEMALE",
"maxPrice": 300000
},
"alertFrequency": "DAILY",
"createdAt": "2026-03-21T10:00:00.000Z"
}
}Real-world example
You're on the hunt for a female Pastel Leopard Gecko to add to your breeding group. Rather than checking the marketplace every day, you create a saved search via the API with INSTANT alerts. The moment a matching listing goes live, you get an email — giving you first shot at new stock.
Was this article helpful?
