> ## 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 CodeSystem search and URI resolution

> Discover which FHIR CodeSystems OMOPHub serves and resolve canonical system URIs to instance IDs for SNOMED, LOINC, RxNorm, and ICD-10.

## Overview

Search-type query on `CodeSystem`. This is the discovery call every FHIR client makes before invoking operations against a specific code system. HAPI FHIR's `RemoteTerminologyServiceValidationSupport.fetchCodeSystem()` runs `GET /CodeSystem?url=http://loinc.org` to decide whether to route code validation through OMOPHub - if the response Bundle is non-empty, HAPI proceeds; if it's empty, HAPI skips OMOPHub for that system.

OMOPHub exposes per-vocabulary CodeSystem stubs with `content: "not-present"`. The stubs are metadata-only; concept data is served via the `$lookup`, `$validate-code`, `$expand`, and `$translate` operations.

## Modes

### 1. Search by canonical system URI

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/CodeSystem?url=http://loinc.org" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns a `searchset` Bundle with one entry - the LOINC stub.

### 2. Search by the unified OMOP URL

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/CodeSystem?\
url=https://fhir-terminology.ohdsi.org" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns a `searchset` Bundle with one entry - the full OMOP omnibus CodeSystem (with all property definitions and the current vocabulary release metadata).

### 3. List all supported CodeSystems

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

Returns a `searchset` Bundle with 21 entries - 20 per-vocabulary stubs plus the unified OMOP CodeSystem. Useful for building UI pickers and for one-shot capability discovery.

### 4. Search by unknown URI

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/CodeSystem?url=http://example.com/unknown" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns an empty Bundle (`total: 0`), not a 404. This is the FHIR search convention - "no matches found", not "endpoint not found".

## Parameters

| Parameter | Type | Required | Description                                                              |
| --------- | ---- | -------- | ------------------------------------------------------------------------ |
| `url`     | uri  | No       | Canonical system URI to resolve. Omit to list all supported CodeSystems. |

## Response (per-vocabulary stub)

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://fhir.omophub.com/fhir/r4/CodeSystem/loinc",
      "resource": {
        "resourceType": "CodeSystem",
        "id": "loinc",
        "url": "http://loinc.org",
        "name": "LOINC",
        "title": "Logical Observation Identifiers Names and Codes",
        "status": "active",
        "experimental": false,
        "publisher": "Regenstrief Institute",
        "description": "Logical Observation Identifiers Names and Codes - served by OMOPHub. Use $lookup and $validate-code operations to query concepts; the full concept list is not served inline (content: not-present).",
        "content": "not-present"
      }
    }
  ]
}
```

The stub carries metadata only. `content: "not-present"` is the standard FHIR value for terminology servers that expose concepts via operations rather than inline enumeration. Clients should follow up with [$lookup](/api-reference/fhir-terminology/lookup), [$validate-code](/api-reference/fhir-terminology/validate-code), or [\$subsumes](/api-reference/fhir-terminology/subsumes) using the same canonical URI (`http://loinc.org`) - the operation handlers dispatch on the FHIR system URI and route to the underlying OMOP vocabulary.

## Response (list-all mode)

Same Bundle shape as above, with 21 entries. Each stub has a distinct `id` (the short slug - `loinc`, `snomed`, `rxnorm`, etc.) and `url` (the canonical FHIR system URI). The final entry is the unified OMOP CodeSystem (`https://fhir-terminology.ohdsi.org`) with the release-specific id (e.g. `omop-v20250827`) and full property definitions.

## Stub-to-URI map

See the [Supported Vocabularies](/api-reference/fhir-terminology/overview#supported-vocabularies) table in the overview for the authoritative list of `id` ↔ `url` pairs.

## Errors

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

Unknown URIs return an empty Bundle, not an error.

## See Also

* [CodeSystem instance read](/api-reference/fhir-terminology/codesystem-read) - `GET /CodeSystem/{id}` for follow-up reads after discovery
* [\$lookup](/api-reference/fhir-terminology/lookup) - fetch concept details for a code in a discovered system
* [HAPI FHIR Integration](/guides/integration/hapi-fhir) - how HAPI's validator uses this endpoint