Base64-encode the clinical document (CDA XML, PDF, or other format) and POST it as a Binary resource with the correct contentType (e.g., application/pdf, application/xml, text/xml) to [base]/Binary; record the Binary resource id returned by the server.
Create a DocumentReference resource with status (current), type (using an appropriate LOINC code for the document type — verify against the LOINC document ontology), category, subject (patient reference), date, and author.
Set DocumentReference.content to an array containing at least one element with attachment.contentType matching the Binary's content type, attachment.url pointing to [base]/Binary/[id], and optionally attachment.hash and attachment.size for integrity checking.
Set DocumentReference.context to capture the relevant clinical context such as the Encounter, period of service, and practice setting code.
POST the DocumentReference to [base]/DocumentReference and retain the assigned id for future reference or association with other resources.
Optionally, wrap the Binary POST and DocumentReference POST in a FHIR transaction Bundle to create both atomically and avoid a dangling Binary if the DocumentReference creation fails.
Known gotchas
FHIR servers may enforce access control on Binary resources independently from DocumentReference — confirm that the Binary URL is accessible to systems that will retrieve documents via the DocumentReference.
Using a non-standard or incorrect LOINC code for DocumentReference.type may cause the document to be excluded from clinical document queries that filter by type.
Binary resources can be large; confirm the server's maximum request body size and consider chunked upload or pre-signed URL patterns for very large documents.
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