API Overview

The complete FHIR and authorisation surface lives in the OpenAPI Explorer — every path, parameter, request body, response and worked example. That document is generated from the server's own CapabilityStatement, so it cannot describe an endpoint the server does not have.

This page covers only what the generated reference does not: where things live, how to get a token, and the conventions that apply everywhere.

Base URLs

Authentication

Every FHIR route needs a SMART on FHIR JWT:

Authorization: Bearer <jwt-token>

Getting one takes two calls, both documented in the explorer under Authorisation:

1. POST /authenticate with email, password and client_id. If the account belongs to more than one organisation this returns a short-lived selection token plus the list to choose from.
2. POST /select-staff-organization with the chosen org_id and that token, which returns the organisation-scoped session token.

Patients follow a parallel path — POST /authenticate-patient then POST /select-organization — which never touches the staff tables.

The token is what selects the tenant. It carries the organisation, and no request parameter can widen, narrow or change it. A user who works at several organisations holds a separate token for each.

Pagination and sorting

These apply to every FHIR search. All four claims below were verified against the running server rather than taken from the source:

_summary=count is not implemented. It is accepted without error and then ignored, so a request for it returns a full page of entries rather than a bare count — check Bundle.total instead.

Per-resource search parameters are listed on each operation in the explorer. Note that the server implements more parameters than its CapabilityStatement declares; only the declared ones are documented, because those are the ones that have been verified end-to-end.

Errors

Every error is a FHIR OperationOutcome. The explorer shows the exact shape and a worked example per status code on each operation. Statuses in use: 200, 201, 204, 400, 401, 403, 404, 405, 409, 412, 415, 422, 500. There is no 410 — a deleted resource answers 404.

CORS

All services return CORS headers and handle preflight OPTIONS automatically.

Public endpoints

These need no token: