Polling and caching
There are no webhooks. How to keep your copy in sync with updatedSince, ETags and 304s, and what the caching headers mean.
The Developer API has no webhooks. An integration learns about changes made in Medos (a receptionist editing a patient, a cancelled appointment) by asking. These mechanisms make that cheap.
Patients: updatedSince
GET /v1/patients takes
updatedSince, an instant with an offset. Keep the newest updatedAt you have
seen, and poll from it:
curl -s "https://api.medos.one/v1/patients?updatedSince=2026-11-13T04:30:00Z&size=100" \
-H "x-api-key: $MEDOS_API_KEY"Page through the result until a page comes back short.
Upsert each patient locally by id. The comparison is inclusive, so the
record at exactly your watermark comes back again. De-duplicate rather than
skipping it.
Move your watermark to the newest updatedAt you received, and wait for
the next poll.
Paging is offset-based. If records change while you are paging, a row can move between pages. Over a set of changes that is unlikely, and the inclusive watermark means the next poll catches anything that moved. It is not impossible, though, so do not treat one pass as a snapshot.
Appointments: a date window
Appointment search has no change
filter, and updatedSince there is a 400 rather than a silent no-op. Poll the
window you care about instead, for example today and the next seven days, and
narrow it with statuses. Each appointment's updatedAt tells you which rows
changed since you last looked.
ETags and 304 Not Modified
Every read answers with a weak ETag. Send it back as If-None-Match, and if
nothing changed you get 304 with no body:
GET /v1/appointments/search (or any read)
If-None-Match: W/"1f3-8Jk2…"
HTTP/1.1 304 Not ModifiedThis is the cheapest way to poll often: an unchanged page costs a round trip and
no payload. The ETag is computed per response body, so store it per request (URL
plus body), not per route. A 304 still counts against your
rate limits.
Cache-Control
| Routes | Header | Meaning |
|---|---|---|
| Everything that carries patient data (twelve routes) | Cache-Control: no-store | Do not keep the response in any HTTP cache: not a proxy, not a CDN, not a client library's disk cache. |
GET /v1/addresses, GET /v1/doctors | Cache-Control: private, max-age=300, must-revalidate and Vary: x-api-key | Your own client may reuse it for five minutes, then must revalidate. |
no-store and a working ETag are not in conflict. no-store is about HTTP
caches holding records at rest; your application storing a record it synced
is the whole point of the integration. The ETag lets your code ask "has this
changed?", and that request still reaches us, where your key is checked again.
Do not put a shared cache in front of this API
Every clinic calls GET /v1/patients at the same URL and is told apart only by
its key header. A caching proxy that ignores no-store and keys on the URL
would serve one clinic's patients to another. Honour the headers.
Polling frequency
A minute between polls is plenty for most integrations. With updatedSince and
If-None-Match, a quiet minute costs a few small requests. Spread batch work out
rather than bursting it; see Rate limits.
When a route is withdrawn
A route scheduled for removal starts carrying three headers at least 90 days before it stops answering:
Deprecation: @1798761600
Sunset: Fri, 01 Jan 2027 00:00:00 GMT
Link: <https://docs.medos.one/…>; rel="deprecation"Deprecation (RFC 9745) is when it was deprecated, Sunset (RFC 8594) when it
will stop answering, and the link points at the page describing the replacement.
Log any response carrying Deprecation. No route is deprecated today.