generated: '2026-08-14' method: searched source: https://developer.healthgorilla.com/reference/api-reference description: >- Cross-cutting request/response semantics for the Health Gorilla FHIR API, captured from the provider's own reference pages. Health Gorilla documents a genuine idempotency contract with a named header and defined conflict behaviour, cursor pagination on every search and $everything response, a three-header request-correlation scheme, and a FHIR OperationOutcome error envelope. Version selection is by URL path rather than content negotiation. authentication: style: OAuth 2.0 bearer token in the Authorization header header: 'Authorization: Bearer ' transport: TLS 1.2 or higher; plain HTTP requests are rejected detail: authentication/health-gorilla-authentication.yml idempotency: supported: true header: HG-Idempotency-Key value_format: UUID v4 example: 'HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125' applies_to: POST requests retention_window: typically up to 1 hour replay_behavior: >- A duplicate payload sent with the same key inside the idempotency window returns the original response. conflict_behavior: >- Reusing an existing key with a different request payload returns 409 Conflict with an empty body (Content-Length: 0) and an X-HG-Request-Id header. The server compares payload content, not just the key. in_flight_behavior: >- If the original request is still being processed, a subsequent request with the same key may receive 202 Accepted. api_versions: [R4, STU3] guidance: - Use an idempotency key on every POST that creates or triggers processing of a resource. - Generate a new UUID for each unique payload. - Store the UUID with the original request so retries are safe. docs: https://developer.healthgorilla.com/reference/idempotent-requests pagination: style: cursor (primary), offset (discouraged) container: FHIR Bundle with type searchset and link[] navigation entries next_link: link.relation = "next" carrying an absolute URL parameters: - {name: _count, description: 'Resources returned per page; default varies by resource type'} - {name: _cursor, description: 'Opaque server-generated pointer to the next page; must be used as-is and cannot be constructed by the client'} - {name: _offset, description: 'Numeric index for offset paging; discouraged for large datasets and long-lived sequences'} total_field: Bundle.total termination: absence of a link with relation "next" indicates the final page applies_to: - all FHIR search requests - '$everything responses' - other operations returning a FHIR Bundle guidance: - Prefer _cursor taken from Bundle.link.next. - Avoid excessively large page sizes such as _count=1000. - Do not rely on _offset for long-lived pagination; results may shift if data changes. docs: https://developer.healthgorilla.com/reference/pagination request_tracing: supported: true response_headers: - {header: X-HG-Request-Id, description: Unique ID generated by Health Gorilla for the request} - {header: X-Request-Id, description: Client-provided ID echoed back when supplied on the request} - {header: X-Correlation-Id, description: Links the client request ID to the Health Gorilla request ID} guidance: - Send X-Request-Id on every request. - Log X-HG-Request-Id and X-Correlation-Id in application logs. - Provide both IDs when contacting Health Gorilla support. docs: https://developer.healthgorilla.com/reference/request-ids-correlation versioning: style: uri-path current: R4 paths: R4: /fhir/R4/{ResourceType} STU3: /fhir/3.0/{ResourceType} discovery: GET /fhir/R4/metadata returns the CapabilityStatement token_bound_version: parameter: hg_rest_api_version issued_at: token issuance response_field: hg_rest_api_version error: 400 with error=unsupported_api_version note: >- FHIR version is selected through the API path, not negotiated during OAuth token issuance. A separate legacy REST API version may be pinned to the token. docs: https://developer.healthgorilla.com/reference/fhir-versions content_negotiation: request_content_type: application/fhir+json response_content_types: [application/fhir+json, application/fhir+xml] additional_formats: [json, xml] error_content_type: application/fhir+json error_envelope: format: FHIR OperationOutcome media_type: application/fhir+json rfc9457: false shape: resourceType: OperationOutcome issue: - {field: severity, values: [fatal, error, warning, information]} - {field: code, description: 'coded classification (invalid, required, forbidden, not-found, duplicate, conflict, structure, processing)'} - {field: diagnostics, description: human-readable explanation} - {field: location, description: FHIR path or JSONPath to the offending field} - {field: details.text, description: optional short description} detail: errors/health-gorilla-problem-types.yml docs: https://developer.healthgorilla.com/reference/fhir-operationoutcome-format search_and_filtering: style: FHIR RESTful search modifiers_and_prefixes: FHIR standard date prefixes and search modifiers incremental_sync: _lastUpdated for retrieving resources changed since a timestamp docs: - https://developer.healthgorilla.com/reference/searching-filtering - https://developer.healthgorilla.com/reference/date-filtering async_operations: supported: true pattern: 202 Accepted with status polling examples: ['$p360-retrieve', '$export'] note: >- Long-running federated record retrievals are accepted asynchronously rather than held open on a synchronous connection. docs: https://developer.healthgorilla.com/reference/async-job-handling rate_limit_signaling: documented_headers: none throttle_status: 429 note: >- Health Gorilla documents no X-RateLimit-*/RateLimit-* response headers and publishes no per-second request ceiling. The published quantitative limits are the active-subscription cap and the webhook retry schedule. detail: rate-limits/health-gorilla-rate-limits.yml field_expansion: supported: FHIR standard parameters: [_include, _revinclude, _elements, _summary] note: >- Declared per-resource in the live CapabilityStatement rather than in a dedicated docs page; not separately documented by Health Gorilla. metadata: mechanism: FHIR meta element — meta.tag, meta.security, meta.lastUpdated, meta.profile docs: https://developer.healthgorilla.com/reference/meta-tags-security-labels extensions: https://developer.healthgorilla.com/reference/fhir-extensions related: - errors/health-gorilla-problem-types.yml - authentication/health-gorilla-authentication.yml - lifecycle/health-gorilla-lifecycle.yml - rate-limits/health-gorilla-rate-limits.yml - asyncapi/health-gorilla-webhooks.yml - fhir/health-gorilla-fhir.yml x-evidence: - {url: 'https://developer.healthgorilla.com/reference/idempotent-requests.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/pagination.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/request-ids-correlation.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/fhir-versions.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/fhir-operationoutcome-format.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/async-job-handling.md', http_status: 200, fetched: '2026-08-14'}