Arch-Pet Open the app
← Arch-Pet for vet clinics

Clinic API guide

Version 1. Last updated: November 9, 2026

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

  1. The owner links a pet to the clinic (QR code, link, code or email invite). That creates a link, with a linkId.
  2. Your software lists the links and stores your own patient id on each one, once (external-id).
  3. 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.

kindNeeds the owner to allowpayloadIn the owner's app
appointmentappointmentstitle (required), at (required), timeSet (default true), leadMinutes (1 to 2880), placeName, placeAddress, noteA reminder in the Agenda, with the time and place
vaccinerecordsname (required), givenAt (required, not in the future), nextDue, vet, batch, noteOn the vaccine card, plus a reminder for the next dose
documentrecordstitle, category, docDate, note, and file next to payload (below)In the pet's vet records
instructionsrecordsmedicine, 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" }.

StatuserrorMeaning
400bad-kind, bad-date, no-title, no-name, empty-instructions, bad-file-type, no-file, too-largeFix the request
401unauthenticatedMissing, wrong or revoked key, or the clinic isn't verified
403not-sharedThe owner didn't allow this kind (records or appointments)
404no-linkNo active link with that id, or the owner unlinked
429daily-limitThe 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.