Initiate a system-level export: GET [base]/$export with headers Accept: application/fhir+json and Prefer: respond-async; optionally add _type=[ResourceType1,ResourceType2] to limit exported resource types.
The server responds with HTTP 202 Accepted and a Content-Location header containing a polling URL for the export job status.
Poll the Content-Location URL; while the job is running the server returns 202 with an optional X-Progress header; when complete it returns 200 with a JSON body containing output[] array.
Each output[] element has type (FHIR resource type) and url (URL to download an NDJSON file); each line in the NDJSON file is a complete FHIR resource JSON object.
Download each NDJSON file with the same bearer token; process line by line rather than loading entire files into memory, as files may contain millions of records.
Check the error[] array in the completed export manifest for any resource types that failed to export; handle partial export failures gracefully.
Known gotchas
Bulk exports can run for minutes to hours on large datasets; implement a polling loop with reasonable intervals (30-60 seconds) and a maximum wait time with alerting.
NDJSON files may be deleted from the server after a short retention window (e.g., 24 hours); download and persist them promptly after the export completes.
Patient-level export ($export at the group or patient level) requires a specific Group ID or patient list; system-level export (/$export) requires system/* scopes and is typically restricted to backend service clients.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp