Query a FHIR CapabilityStatement to determine supported US Core profiles and plan API interactions accordingly
domain: hl7.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
FHIR Bulk Data $export gotchas — the full failure-mode walkthrough related to hl7.org, checked against official docs, with linked verified routes.
Steps
Fetch the CapabilityStatement from GET [base]/metadata and inspect rest[0].resource[*].supportedProfile for each resource type; supportedProfile lists canonical URLs of declared profile conformance
Identify which US Core version is supported by matching supportedProfile URLs against known US Core canonical base URLs (e.g., http://hl7.org/fhir/us/core/StructureDefinition/)
For each resource type the app needs, check whether the server declares the corresponding US Core profile; if absent, the server may not enforce or populate US Core must-support fields
Use the searchParam list per resource type to determine which US Core-required search parameters are available (e.g., Patient: name, birthdate, identifier; Observation: patient, category, code, date)
Check the interaction list for each resource type to confirm whether create, update, or delete is supported if the app needs to write resources
Note any extensions on the CapabilityStatement (e.g., supported-system-interactions, US Core capabilitystatement-expectation extensions) that further define SHALL vs SHOULD compliance levels
Known gotchas
A server may declare a US Core profile in supportedProfile but not enforce all must-support elements at write time; validate returned data against the profile rather than trusting declaration alone
US Core search parameter combinations (e.g., Observation?patient=&category=&date=) may have SHALL requirements; check the US Core IG searchParam combination tables, not just the CapabilityStatement list
The CapabilityStatement is often cached and may not reflect recent server updates; refetch it at application startup rather than hardcoding assumptions from a prior fetch
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?