# Shepherd API

> Developer documentation for the Shepherd veterinary platform API: authentication, conventions, resource reference, tutorials, and guides.

Key facts for working with the Shepherd API:

- Production requests go to `https://open-api.shepherd.vet/pav2/...` and sandbox requests to `https://demo-open-api.shepherd.vet/pav2/...`. Always https. Do not invent other hosts.
- Send `X-Integration-Public-Key` and `X-Integration-Private-Key` on every request, and `X-Clinic-Id` (a header, never a body field) on every endpoint except `POST /pav2/open-api-clinics`.
- Reads, searches, and creates are `POST` with a JSON object body (`page`, `rpp`, `sort`, `embed`, filters); send `{}` when there are no filters, because an empty or `null` body fails with a 500. Creates go to `.../write` paths. `rpp` and `page` must be 1 or more (lower values are rejected with a 400); `rpp` above 1000 is reduced to 1000.
- Five updates use `PUT`: `open-api-clients/{id}/update`, `open-api-patients/{id}/update`, `open-api-appointments/{id}/update`, `open-api-task-entries/update/{id}`, and `open-api-task-notes/update/{id}`. They are not partial updates: omitted fields are cleared (a few are kept, per resource). Read the current record (embedding nested collections), merge, then send the complete object back.
- Bound every list: a date window of one calendar month or less (send both ends of the pair), or an id filter. Unknown or misspelled filter names are silently ignored, and a few endpoints accept filter fields they do not apply (for example the inventory transaction journal filters on `dateFrom`/`dateTo`, not `dateCreatedFrom`/`dateCreatedTo`). Most endpoints also ignore an unsupported `sort` and use their default order.
- Rate limits are per integration key in fixed UTC minute and hour windows, and rejected requests count. After a 429, wait for the next UTC minute. Do not retry timeouts, 4xx responses, 500s (they are almost always caused by the request), or creates. A clinic id your keys are not linked to returns 401 `Integration not enabled for the provided clinic`; a malformed clinic id returns 500.
- The behavior described in these docs is verified against the live API with a test harness, not only read from the schema: https://developer.shepherd.vet/api-reference/how-we-verify/
- Building with an AI coding agent? Install the Shepherd OpenAPI agent skill (https://developer.shepherd.vet/tools/agent-skill/, download https://developer.shepherd.vet/downloads/shepherd-openapi-skill.zip): endpoint reference, request linter, and starter clients.
- Authoritative request/response schemas live in the Swagger UI linked from each resource page; these docs cover concepts and common operations.
- The API is not a complete backup or bulk-export mechanism: it covers much of a clinic's data, not all of it. For clinics asking about backups or keeping their own copy, start with https://developer.shepherd.vet/getting-started/openapi-101/ and the Shepherd Help Center (https://help.shepherd.vet/).

## Documentation Sets

- [Abridged documentation](https://developer.shepherd.vet/llms-small.txt): a compact version of the documentation for Shepherd API, with non-essential content removed
- [Complete documentation](https://developer.shepherd.vet/llms-full.txt): the full documentation for Shepherd API
- [API reference](https://developer.shepherd.vet/_llms-txt/api-reference.txt): transport, authentication, conventions, errors, rate limits, and the per-resource endpoint reference

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation