Endpoints

Each route below has its own page: what it is for, every parameter, what comes back, and the mistakes that produce a 400.

What every request needs

x-api-key: mk_…
x-end-user-id: <patient id>      # OTP and 🔒 routes only

The API key is the credential — there is nothing to sign — so it belongs on your server and nowhere else. Requests are refused unless they come from an address on the key's IP allowlist. OTP and 🔒 routes also need x-end-user-id, naming the patient the request is for; see OTP-gated routes.

Two things are decided for you and cannot be sent:

• workspaceId comes from the key. Every route is scoped to the workspace the key is registered against, so a workspaceId in a query string or body is either ignored or overwritten.
• The admin identity. The gateway calls the Medos core as your workspace's admin, which is why routes that read a patient's own records are scoped server-side rather than by anything you send.

🔒 marks a route that additionally needs an OTP-verified phone, and the same x-end-user-id that verification was made under.

Appointments

Booking without OTP

There is no separate set of paths for this. The 🔒 booking routes above skip the one-time code when you call them with an API key instead of a widget session — see Booking without OTP.

QMS (queue)

Session packs

Patients

Workspace

Public profiles

Staff

OTP

Other

Back office (HMS)

For a hospital or clinic system keeping its own records in step with medos. Every route here is API-key only — a widget session is refused — and gated on your plan, one entitlement per operation. See Entitlements, and Acting user for the header every write needs.

Each page carries its own runnable request, so you can try an endpoint on the page that documents it.

Appointment and queue read-back

Patients

Clinical records

Locations and configuration

Not exposed, by decision

The service and price list (/v1/offerings) is deliberately absent. Upstream filters it by the user who created each offering rather than by workspace, so served through an API key it would return an arbitrary subset of the clinic's catalogue — a silently incomplete price list is worse than none. It needs a change on the medos side first.

Document upload is a multipart endpoint and needs its own size and streaming policy; listing and deleting ship first. Consultation sessions (notes and audio) are not exposed either: consultation audio is the most sensitive payload in medos, and it deserves a deliberate decision rather than arriving as part of a batch.

There are no outbound webhooks. A cancellation made by clinic staff in the medos dashboard reaches you when you next search, so poll on a schedule rather than waiting for a callback.

Conventions used on every page