Clinic API guide
The Clinic API lets practice management software send what the clinic already records (appointments, vaccines, documents and visit instructions) to the pet owner's Arch-Pet app. It's the automatic version of the Send button in the clinic portal.
The owner stays in control: you can only send to pets linked to the clinic, only what the owner allowed (records or appointments), and each item waits for the owner's OK unless they chose to add items automatically.
Keys
A clinic admin creates a key in the portal: Integrations, Create an API key. The key is shown once; keep it in your software's settings, never in a browser or a public place. Revoke it in the same screen. Only verified clinics' keys work.
Authorization: Bearer apk_...
Base URL: https://arch-pet.com/api/clinic/v1. Requests and responses are JSON (Content-Type: application/json), up to 10 MB per request.
How it fits together
- The owner links a pet to the clinic (QR code, link, code or email invite). That creates a link, with a
linkId. - Your software lists the links and stores your own patient id on each one, once (
external-id). - From then on, send items by your patient id. You don't need to keep Arch-Pet ids.
Endpoints
List linked pets
GET /links
200 {
"links": [
{
"linkId": "c1_p8Kd2",
"petName": "Brisa",
"species": "dog",
"ownerName": "Ana",
"externalId": null,
"scopes": { "records": true, "appointments": true, "shareProfile": false },
"createdAt": 1762700000000
}
]
}
Set your patient id on a link
PUT /links/{linkId}/external-id
{ "externalId": "PAT-10442" }
200 { "linkId": "c1_p8Kd2", "externalId": "PAT-10442" }
An empty externalId removes it. Up to 80 characters.
Send an item
POST /patients/{externalId}/items (by your patient id)
POST /links/{linkId}/items (by link)
{ "kind": "...", "payload": { ... } }
200 { "itemId": "x7Hq...", "applied": false }
by patient id: { "results": [ { "itemId": "...", "applied": false } ] }
applied is true when the owner chose to add items automatically; otherwise the item waits in the owner's app.
Item kinds
Dates are milliseconds since 1970 (UTC) or ISO 8601 strings, from ten years ago to five years ahead.
| kind | Needs the owner to allow | payload | In the owner's app |
|---|---|---|---|
appointment | appointments | title (required), at (required), timeSet (default true), leadMinutes (1 to 2880), placeName, placeAddress, note | A reminder in the Agenda, with the time and place |
vaccine | records | name (required), givenAt (required, not in the future), nextDue, vet, batch, note | On the vaccine card, plus a reminder for the next dose |
document | records | title, category, docDate, note, and file next to payload (below) | In the pet's vet records |
instructions | records | medicine, dosage, times (minutes after midnight, up to 4), days (1 to 365), startDate, text (home care notes). Needs medicine or text. | A medicine with its schedule, and the notes in the visit history |
Documents
{
"kind": "document",
"payload": { "title": "Complete blood count", "docDate": "2026-11-08" },
"file": { "name": "cbc.pdf", "contentType": "application/pdf", "base64": "JVBERi0x..." }
}
PDF, JPEG or PNG, up to 7 MB (base64 adds a third).
Examples
curl -X POST https://arch-pet.com/api/clinic/v1/patients/PAT-10442/items \
-H "Authorization: Bearer $ARCHPET_KEY" -H "Content-Type: application/json" \
-d '{"kind":"appointment","payload":{"title":"Vaccine booster","at":"2026-11-18T14:30:00-03:00","placeName":"Sunny Vet Clinic"}}'
curl -X POST https://arch-pet.com/api/clinic/v1/patients/PAT-10442/items \
-H "Authorization: Bearer $ARCHPET_KEY" -H "Content-Type: application/json" \
-d '{"kind":"instructions","payload":{"medicine":"Carprofen 25 mg","dosage":"1 tablet","times":[480,1200],"days":7}}'
Errors
Errors come as { "error": "code" }.
| Status | error | Meaning |
|---|---|---|
| 400 | bad-kind, bad-date, no-title, no-name, empty-instructions, bad-file-type, no-file, too-large | Fix the request |
| 401 | unauthenticated | Missing, wrong or revoked key, or the clinic isn't verified |
| 403 | not-shared | The owner didn't allow this kind (records or appointments) |
| 404 | no-link | No active link with that id, or the owner unlinked |
| 429 | daily-limit | The clinic sent 500 items today; try tomorrow |
Don't retry 4xx errors unchanged. Retry 5xx errors later. A 404 usually means the owner unlinked: stop sending to that patient.
Rules
- Send only what belongs to the linked pet and helps its owner care for it. No advertising.
- Keep keys secret and revoke any that may have leaked. One key per system makes that easy.
- The partner terms apply. Questions or a vendor integration: support@arch-pet.com.