Search appointments
The filtered appointment list — and, until webhooks exist, how you notice changes you did not make.
POST /v1/appointments/searchThe filter is medos's own appointment filter and passes through unchanged, so any
field the dashboard can filter on works here. The workspace is not part of it —
it is taken from your key, and a workspaceId in the body is ignored.
API-key only (a widget session is refused) and entitlement-gated on devapi_appointments_search.
This is also how you poll for changes
There are no outbound webhooks yet. A cancellation made by clinic staff in the medos dashboard reaches you when you next search — so if your integration needs to react to changes it did not make, poll this on a schedule rather than waiting for a callback.
Body
| Name | Required | Description |
|---|---|---|
addressId | No | — |
doctorId | No | — |
startDate | No | YYYY-MM-DD |
endDate | No | YYYY-MM-DD |
statuses | No | JSON array. medos's own appointment filter passes through, so anything the dashboard can filter on works here. |
page | No | — |
size | No | — |
Try it
/v1/appointments/searchAPI key onlydevapi_appointments_searchAnswers 200, not 201 — it is a read with a body. Poll this to see changes made in the dashboard.
Body
POST /v1/appointments/search{
"statuses": [
"BOOKED",
"COMPLETED"
],
"page": "0",
"size": "20"
}https://api.medos.oneUse a dedicated test key, and put your browser's address on its allowlist
A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.
Request
curl -s -X POST "https://api.medos.one/v1/appointments/search" \
-H "x-api-key: $MEDOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"statuses": [
"BOOKED",
"COMPLETED"
],
"page": 0,
"size": 20
}'It answers 200, not 201: this is a read, and a POST only because the
filter travels in the body.
Common failures
| Status | Cause |
|---|---|
403 with requiredFeature | Not entitled to this operation. |
403 "only available to Developer API keys" | A widget session token was used. Send x-api-key. |