Server-side API

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 Modified

This 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

RoutesHeaderMeaning
Everything that carries patient data (twelve routes)Cache-Control: no-storeDo 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/doctorsCache-Control: private, max-age=300, must-revalidate and Vary: x-api-keyYour 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.

On this page