> ## 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.

# OMOPHub REST API and FHIR terminology introduction

> Base URLs, authentication, core capabilities, and quick-start examples for the OMOPHub REST API and FHIR R4/R5/R6 terminology service.

Understand the base URLs, authentication, response formats, and the full scope of the OMOPHub API.

## Base URLs

OMOPHub exposes two surfaces, both served over HTTPS:

**REST API**

```
https://api.omophub.com/v1
```

**FHIR Terminology Service** (R4 by default; `r4b`, `r5`, and `r6` available via path prefix)

```
https://fhir.omophub.com/fhir/r4
```

Both endpoints enforce HTTPS - plain HTTP requests are rejected.

## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer oh_xxxxxxxxx
```

<Info>
  Get your API key from the [OMOPHub Dashboard](https://dashboard.omophub.com/api-keys).
</Info>

The same API key works for both the REST API and the FHIR Terminology Service. Rate limits and metering are shared across both endpoints. The FHIR Terminology Service additionally accepts RFC 6749 `client_credentials` via `POST /oauth2/token` for Spring Security OAuth2 clients - see the [FHIR Terminology Service overview](/api-reference/fhir-terminology/overview#authentication) for details.

## Core Capabilities

**Search & Discovery**

* Full-text search across 100+ medical vocabularies (SNOMED CT, ICD-10, LOINC, RxNorm, NDC, HCPCS, ATC, and more)
* Semantic search powered by neural embeddings - match by clinical meaning, not just keywords
* Autocomplete, fuzzy matching, phonetic search, and faceted filtering

**FHIR Terminology Service**

* Standard FHIR operations: `$lookup`, `$validate-code`, `$translate`, `$expand`, `$subsumes`, `$find-matches`, `$closure`
* OMOP-specific operation: `$diff` for comparing concepts between vocabulary releases
* CodeSystem and ValueSet search-type queries for client discovery (HAPI, EHRbase)
* FHIR batch Bundles, per-vocabulary CodeSystem stubs, and R4 / R4B / R5 / R6 wire formats on the same endpoint

**FHIR Concept Resolver**

* One-call resolution: FHIR `Coding` or `CodeableConcept` → OMOP standard concept + domain + CDM target table
* `Maps to` traversal for non-standard codes, semantic fallback for display-text-only inputs
* Single, batch (up to 100 codings), and `CodeableConcept` variants with OHDSI vocabulary preference ranking

**Vocabulary Mapping**

* Cross-vocabulary mapping between any OMOP vocabulary pair
* Mapping quality scores and coverage analysis
* Batch mapping: up to 100 concepts per request

**Concept Navigation**

* Traverse ancestor / descendant hierarchies with configurable depth and relationship-type filters
* Explore non-hierarchical relationships (`Maps to`, `Has ingredient`, `RxNorm has dose form`, etc.)
* Phoebe-powered concept recommendations for phenotype development

**Batch & Bulk Operations**

* Batch concept retrieval, relationship queries, hierarchy queries, and mappings (up to 100 per request)
* Bulk search and bulk semantic search for large ETL workloads
* Each batch / bulk request counts as one API call against your quota

**OHDSI Compliance**

* Synced with OHDSI ATHENA releases
* Version-specific API routing via `X-Vocab-Release` header or `vocab_release` query parameter

## API Structure

**RESTful design**

* Resource-based endpoints (`/concepts`, `/vocabularies`, `/search`, `/mappings`, `/fhir/resolve`)
* Standard HTTP methods (GET, POST)
* Consistent JSON response envelope

**Field naming**

* `snake_case` for all fields (`concept_id`, `vocabulary_id`, `domain_id`, `target_concept_code`)
* Consistent naming across REST API, SDK responses, and FHIR property codes

**Pagination**

* Page-based: `page` (1-indexed) and `page_size` (default 20, max 1000) query parameters
* Response `meta.pagination` includes `total_items`, `total_pages`, `page`, `page_size`, `has_next`, `has_previous`

## API Categories

<CardGroup cols={2}>
  <Card title="Search" icon="magnifying-glass" href="/api-reference/search/basic-search">
    Text search, semantic search, autocomplete, facets, bulk search, and similarity.
  </Card>

  <Card title="Concepts" icon="cube" href="/api-reference/concepts/get-concept">
    Look up by ID or code, get recommendations, traverse relationships, batch retrieval.
  </Card>

  <Card title="Concept Hierarchy" icon="sitemap" href="/api-reference/hierarchy/get-concept-hierarchy">
    Ancestors, descendants, and full hierarchy trees with relationship-type filters.
  </Card>

  <Card title="Relationships" icon="diagram-project" href="/api-reference/relationships/get-relationship-types">
    Relationship types and per-concept relationship queries.
  </Card>

  <Card title="Mappings" icon="arrows-rotate" href="/api-reference/mappings/map-concepts">
    Cross-vocabulary mapping, batch mapping, coverage analysis, and validation.
  </Card>

  <Card title="Vocabularies" icon="book" href="/api-reference/vocabularies/list-vocabularies">
    List, search, and inspect vocabulary metadata, statistics, and releases.
  </Card>

  <Card title="Domains & Classifications" icon="tags" href="/api-reference/domains/get-domains">
    OMOP domains, concept classes, and per-domain statistics.
  </Card>

  <Card title="FHIR Resolver" icon="arrows-rotate" href="/api-reference/fhir/resolve">
    `Coding` and `CodeableConcept` → OMOP standard concept, CDM target table, in one call.
  </Card>

  <Card title="FHIR Terminology Service" icon="fire" href="/api-reference/fhir-terminology/overview">
    `$lookup`, `$translate`, `$validate-code`, `$expand`, `$subsumes`, and the full spec-conformant surface.
  </Card>
</CardGroup>

## Quick Start Examples

### Search for Concepts

```bash theme={null}
curl "https://api.omophub.com/v1/search/concepts?query=diabetes&vocabulary_ids=SNOMED&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Semantic Search

Match by clinical meaning, not just keyword overlap. Uses neural embeddings.

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/semantic-search?query=chest+pain+that+gets+worse+when+breathing&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get Concept Details

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/201826" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Map Between Vocabularies

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/201826/mappings?target_vocabularies=ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Resolve a FHIR Code to OMOP

One call: FHIR system URI + code in, OMOP standard concept + CDM target table out.

```bash theme={null}
curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "http://snomed.info/sct",
    "code": "44054006",
    "resource_type": "Condition"
  }'
```

### FHIR `$lookup`

Spec-conformant FHIR operation for clients that speak FHIR natively (HAPI, EHRbase, Firely).

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?system=http://snomed.info/sct&code=44054006" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response Format

All REST API responses follow a consistent envelope:

```json theme={null}
{
  "success": true,
  "data": {
    // Response payload
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-14T10:30:00Z",
    "vocab_release": "2025.2"
  }
}
```

FHIR Terminology Service responses use standard FHIR resource formats (`Parameters`, `Bundle`, `OperationOutcome`, `CodeSystem`, `ValueSet`, `ConceptMap`) with `Content-Type: application/fhir+json`. XML is served via content negotiation - see the [FHIR Terminology Service content type](/api-reference/fhir-terminology/overview#content-type) for the negotiation rules and XML support matrix.

## Response Codes

OMOPHub uses standard HTTP status codes to signal success or failure. `2xx` codes indicate success, `4xx` are client errors, `5xx` are server errors.

| Status | Description                                                     |
| ------ | --------------------------------------------------------------- |
| `200`  | Request succeeded.                                              |
| `400`  | Invalid parameters - check request body or query string.        |
| `401`  | Missing or invalid API key.                                     |
| `403`  | Forbidden - insufficient permissions, or restricted vocabulary. |
| `404`  | Resource not found.                                             |
| `429`  | Rate limit exceeded - check the `Retry-After` header.           |
| `5xx`  | Server error - retry with exponential backoff.                  |

REST API errors return a `{"success": false, "error": {...}}` envelope. FHIR Terminology Service errors on `/fhir/*` paths return a FHIR `OperationOutcome` resource instead.

<Info>
  See [Errors](/api-reference/errors) for the complete error code reference and troubleshooting guide.
</Info>

## Rate Limits

Default free-tier limit: **2 requests per second**, monthly call quota per plan. Batch and bulk endpoints process up to 100 items per request and count as one API call against your quota. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.

See [Rate Limits](/api-reference/rate-limit) for plan-specific limits and header semantics.

## Next Steps

<CardGroup cols={2}>
  <Card title="FHIR Terminology Service" icon="fire" href="/api-reference/fhir-terminology/overview">
    `$lookup`, `$translate`, `$validate-code`, `$expand`, `$subsumes`, and OMOP-specific operations.
  </Card>

  <Card title="FHIR Integration" icon="arrows-rotate" href="/guides/integration/fhir-integration">
    End-to-end workflow from FHIR-coded data to OMOP CDM placement.
  </Card>

  <Card title="Search Endpoints" icon="magnifying-glass" href="/api-reference/search/basic-search">
    Text search, semantic search, autocomplete, and facets.
  </Card>

  <Card title="AI & MCP Server" icon="robot" href="/ai/onboarding">
    Connect Claude, Cursor, or VS Code to medical vocabularies via the MCP Server.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python/overview">
    Typed responses, async support, batch helpers.
  </Card>

  <Card title="R SDK" icon="r-project" href="/sdks/r/overview">
    R6 client for vocabulary access in R workflows.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Complete error code reference and troubleshooting.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/rate-limit">
    Per-plan limits, batch metering, and the rate-limit response headers.
  </Card>
</CardGroup>