> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR CapabilityStatement and terminology metadata

> Discover supported FHIR terminology operations, served code systems, and the active OMOP vocabulary release via the CapabilityStatement endpoint.

## Overview

Returns a FHIR `CapabilityStatement` describing what operations and resources OMOPHub exposes at a given FHIR version endpoint. This is the first endpoint every conformant FHIR client hits - HAPI FHIR, Firely, Postman collections, and the inspectors built into most FHIR tooling all probe `GET /metadata` before making any other call.

## Request

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/metadata" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Version variants

| Path                     | FHIR version   |
| ------------------------ | -------------- |
| `GET /fhir/metadata`     | defaults to R4 |
| `GET /fhir/r4/metadata`  | R4 (4.0.1)     |
| `GET /fhir/r4b/metadata` | R4B (4.3.0)    |
| `GET /fhir/r5/metadata`  | R5 (5.0.0)     |
| `GET /fhir/r6/metadata`  | R6 (6.0.0)     |

The response shape is version-adapted - field names follow the conventions of the requested FHIR version.

## Response

```json theme={null}
{
  "resourceType": "CapabilityStatement",
  "status": "active",
  "kind": "instance",
  "fhirVersion": "4.0.1",
  "format": ["application/fhir+json", "application/fhir+xml"],
  "date": "2026-04-13",
  "publisher": "OMOPHub",
  "software": {
    "name": "OMOPHub FHIR Terminology Service",
    "version": "1.0.0"
  },
  "implementation": {
    "description": "OMOPHub FHIR Terminology Service - OMOP Standardized Vocabularies",
    "url": "https://fhir.omophub.com/fhir/r4"
  },
  "rest": [
    {
      "mode": "server",
      "resource": [
        {
          "type": "CodeSystem",
          "interaction": [
            { "code": "read" },
            { "code": "search-type" }
          ],
          "operation": [
            { "name": "lookup",        "definition": "http://hl7.org/fhir/OperationDefinition/CodeSystem-lookup" },
            { "name": "validate-code", "definition": "http://hl7.org/fhir/OperationDefinition/CodeSystem-validate-code" },
            { "name": "subsumes",      "definition": "http://hl7.org/fhir/OperationDefinition/CodeSystem-subsumes" },
            { "name": "find-matches",  "definition": "http://hl7.org/fhir/OperationDefinition/CodeSystem-find-matches" }
          ]
        },
        {
          "type": "ValueSet",
          "interaction": [
            { "code": "search-type" }
          ],
          "operation": [
            { "name": "expand",        "definition": "http://hl7.org/fhir/OperationDefinition/ValueSet-expand" },
            { "name": "validate-code", "definition": "http://hl7.org/fhir/OperationDefinition/ValueSet-validate-code" }
          ]
        },
        {
          "type": "ConceptMap",
          "operation": [
            { "name": "translate", "definition": "http://hl7.org/fhir/OperationDefinition/ConceptMap-translate" },
            { "name": "closure",   "definition": "http://hl7.org/fhir/OperationDefinition/ConceptMap-closure" }
          ]
        }
      ]
    }
  ]
}
```

The advertised `format` array includes `application/fhir+xml` because the server accepts XML requests via content negotiation. Most operations return clean XML; the three Bundle-shaped endpoints (CodeSystem search, ValueSet search, batch) are best-effort in XML and should be called with JSON in practice. See the [XML support matrix](/api-reference/fhir-terminology/overview#xml-support-matrix) in the overview for the per-endpoint breakdown.

## Response headers

Every response from the FHIR Terminology Service - `/metadata` included - carries two OMOPHub-specific headers that tell you which OMOP vocabulary release served the request:

| Header                   | Example  | Meaning                                                        |
| ------------------------ | -------- | -------------------------------------------------------------- |
| `X-Vocab-Release`        | `2025.2` | Human-friendly release identifier                              |
| `X-Vocab-Release-Status` | `active` | Lifecycle status (`ready`, `active`, `deprecated`, `archived`) |

Use these headers to confirm which release your client is actually hitting, especially when pinning a specific version via the `X-Vocab-Release` request header or `vocab_release` query parameter. See [Vocabulary Versions](/vocabulary-versions) for the full release history.

## Content negotiation

`GET /metadata` respects the same `Accept` header rules as every other FHIR endpoint - JSON is returned by default; XML is served only when the client strictly prefers it. See the [Content Type](/api-reference/fhir-terminology/overview#content-type) section of the overview for the q-value semantics.

## Errors

| HTTP | Issue Code | Cause                      |
| ---- | ---------- | -------------------------- |
| 401  | `login`    | Missing or invalid API key |

## See Also

* [Overview](/api-reference/fhir-terminology/overview) - full list of operations, supported vocabularies, and extension properties
* [CodeSystem search](/api-reference/fhir-terminology/codesystem-search) - discovery for the supported system URIs advertised in this CapabilityStatement