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

# Known Limitations

> What OMOPHub does not do - explicit product boundaries around write operations, custom vocabularies, and PHI so you can plan your integration safely.

OMOPHub covers a lot of ground, but knowing what it *doesn't* do is just as important for planning your integration. This page documents explicit boundaries so there are no surprises in production.

## 1. Vocabulary Coverage

**CPT4 is excluded.** The AMA requires a commercial license to distribute CPT4 codes. OMOPHub does not include CPT4 content. Queries against `http://www.ama-assn.org/go/cpt` return a 403 `OperationOutcome` on the FHIR Terminology Service and a `forbidden` error on the REST API. If your workflow requires CPT4, license it separately from the AMA and manage it in local vocabulary tables.

**MedDRA is excluded.** MedDRA licensing restrictions apply similarly. MedDRA concepts are not available through the API.

**UMLS-restricted vocabularies.** Some vocabularies in ATHENA require a UMLS license for download. OMOPHub serves the subset of ATHENA vocabularies that can be distributed without per-user UMLS licensing. If your workflow needs vocabularies that require UMLS access, check the OHDSI ATHENA download page for the specific license requirements.

<Note>
  SNOMED CT is available through OMOPHub. SNOMED International member countries - including the US, UK, EU member states, Australia, and many others - have national licenses that cover the use of SNOMED CT content. If you're in a non-member country, check your local SNOMED licensing requirements before deploying.
</Note>

## 2. FHIR Terminology Service

**Not a full FHIR server.** OMOPHub implements FHIR terminology operations (`$lookup`, `$translate`, `$validate-code`, `$expand`, `$subsumes`, `$find-matches`, `$closure`) plus the FHIR Concept Resolver and the OMOP-custom `$diff` operation. It does **not** implement FHIR clinical resources (`Patient`, `Observation`, `Condition`, etc.), FHIR REST interactions (create, update, delete, history, patch), or the full FHIR search specification. It is a terminology service, not an EHR backend.

**Implicit ValueSets only.** OMOPHub supports implicit ValueSets derived from OMOP vocabulary structure - e.g. `http://snomed.info/sct?fhir_vs` for all SNOMED concepts or `http://snomed.info/sct?fhir_vs=isa/73211009` for descendants of a specific concept. User-defined extensional ValueSets (upload and store a custom value set by `id`) are **not currently supported**. This is on the roadmap.

**XML is best-effort for Bundle-shaped responses.** Content negotiation serves `application/fhir+xml` when the client strictly prefers it, and the serializer produces clean FHIR XML for `Parameters`, `OperationOutcome`, `ConceptMap`, `ValueSet`, and bare `CodeSystem` resources. **Bundle-shaped responses** - `GET /CodeSystem?url=...`, `GET /ValueSet?url=...`, and batch Bundles - return malformed XML for nested resources; request JSON for those endpoints. See the [XML support matrix](/api-reference/fhir-terminology/overview#xml-support-matrix) for the per-endpoint breakdown.

**Pre-auth errors come back as JSON.** When a FHIR request fails authentication (401) or exhausts the monthly quota (429) before reaching the content-type middleware, the error response is an `OperationOutcome` but serialized as JSON regardless of the `Accept` header. Handler-emitted errors (404, 400, 403, 5xx from inside an operation) do honor the Accept header. See the [Content Type](/api-reference/fhir-terminology/overview#content-type) section of the FHIR overview for the full rules.

## 3. API Behavior

**Read-only.** OMOPHub is a vocabulary lookup service. You cannot write, update, or delete concepts, relationships, or mappings through the API. All vocabulary content comes from OHDSI ATHENA releases.

**No custom mapping storage.** You cannot upload your own source-to-concept mappings to OMOPHub. The [Collaborative Mapping guide](/guides/use-cases/collaborative-mapping) shows how to build and export `source_to_concept_map` files locally using OMOPHub lookups, but the mappings themselves are stored on your side.

**Rate limits apply.** The default rate limit is **2 requests per second** per API key. Monthly quotas vary by plan. See [Rate Limits](/api-reference/rate-limit) for the headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) and the contact path for requesting higher limits.

**Batch endpoints count as one call.** Batch and bulk endpoints (`/v1/concepts/batch`, `/v1/search/bulk`, `/v1/search/semantic-bulk`, `/v1/concepts/map/batch`, `/v1/concepts/hierarchy/batch`, `/v1/concepts/relationships/batch`, `/v1/fhir/resolve/batch`) count as a single API call regardless of the number of items in the request. Use them - see [Batch & Performance](/guides/production/batch-performance).

**No real-time vocabulary updates.** Vocabulary content is updated when OHDSI publishes a new ATHENA release (typically every 2–3 months). There is no live feed of vocabulary changes. See [Vocabulary Releases](/vocabulary-versions) for the current release and update cadence, and [Vocabulary Lifecycle Management](/guides/use-cases/vocabulary-lifecycle-management) for the detection pattern.

## 4. Infrastructure

**SaaS only.** OMOPHub is a hosted service. There is no on-premise or self-hosted deployment option. All API calls go to `https://api.omophub.com` and `https://fhir.omophub.com`. If your security requirements prohibit sending vocabulary queries to an external service, OMOPHub may not be a fit - though note that vocabulary queries contain medical terminology codes, not patient data. See [Security & Data Handling](/guides/production/security-data-handling) for what does and doesn't flow through the API.

**No offline mode.** The API requires an internet connection. For air-gapped production environments, the [Lean ETL Mapping Cache](/guides/use-cases/lean-etl-mapping-cache) guide shows a hybrid approach: build and validate mappings with OMOPHub during development, apply them offline during production.

## 5. What's on the Roadmap

Some of the limitations above are temporary. Here's what's planned:

* **User-defined ValueSets** - upload and expand custom value sets by canonical URL
* **JavaScript SDK** - npm-distributed SDK for browser and Node.js (MCP Server ships on npm today, but that's a different surface)
* **Expanded FHIR XML support** - proper nested-resource serialization for Bundle responses

<Info>
  Have a limitation that's blocking your adoption? Reach out via [omophub.com/contact](https://omophub.com/contact) - real-world use cases drive the roadmap.
</Info>