canonical: https://jentic.com/apis/omophub.com/omophub # OMOPHub Healthcare Vocabulary API The OMOPHub Healthcare Vocabulary API looks up, searches, and maps medical concepts across the OHDSI standardized vocabularies, including SNOMED, ICD-10, LOINC, and RxNorm. It resolves a concept by id or by vocabulary-specific code, walks ancestors, descendants, hierarchy paths, and typed relationships, and maps concepts between vocabularies with mapping coverage, quality, and validation checks. Search runs as basic, advanced, autocomplete, faceted, semantic, and bulk queries, and FHIR resolve routes translate a FHIR Coding or CodeableConcept into a source concept, standard concept, and target CDM table. CPT4 access requires the key owner to complete annual UMLS validation in the OMOPHub Dashboard, and every lookup can be pinned to a vocabulary release. ## For AI agents Search and resolve OMOP medical concepts, map codes between SNOMED, ICD-10, LOINC, and RxNorm, walk concept hierarchies, and translate FHIR codings into standard OMOP concepts. ## Scope Does not store patient records, run an EHR, or make clinical coding decisions on its own. Use for looking up, searching, and mapping OMOP medical vocabulary concepts only. ## Capabilities - Resolve a concept by its vocabulary-specific code, such as an ICD10CM or LOINC code, and return its OMOP concept with synonyms and relationships - Map concepts to a target_vocabulary with a mapping_type of direct, equivalent, broader, or narrower, singly or in batch - Translate a FHIR Coding system and code, or a CodeableConcept, into a source concept, standard concept, and target CDM table - Walk a concept's ancestors, descendants, hierarchy, and the path between two concepts with max_levels and include_distance - Find concepts by meaning with semantic search, so a query like heart attack returns Myocardial infarction - Check mapping coverage and quality between a source and target vocabulary and validate mappings before loading them - Pin any lookup to a vocab_release and list the available vocabulary releases ## Use cases ### Clinical coding assistant agent A data engineer's agent maps messy source codes into the OMOP Common Data Model. Through Jentic it searches for 'map a medical code to an OMOP standard concept', loads the OMOPHub concept-by-code operation, and resolves each source code, then maps it to the standard vocabulary, with the bearer key attached at call time. Semantic search results are treated as suggestions for review, as the spec states, not automatic clinical coding decisions. Example prompt: Call GET `/concepts/by-code/{vocabularyId}/{conceptCode}` with vocabularyId 'ICD10CM' and conceptCode 'E11.9', then POST `/concepts/map` with target_vocabulary 'SNOMED' and source_concepts set to the returned concept id ### FHIR to OMOP ETL An ETL pipeline receiving FHIR resources needs each coding resolved to the right standard concept and CDM table. POST `/fhir/resolve` takes a FHIR Coding system and code with an optional resource_type such as Condition or Observation and returns the source concept, standard concept, target CDM table, and an optional mapping quality signal. POST `/fhir/resolve/batch` handles many codings in one call, and POST `/fhir/resolve/codeable-concept` resolves a CodeableConcept with its text. Example prompt: POST `/fhir/resolve/batch` with codings from a FHIR Bundle, resource_type 'Condition', and include_quality true, then record the standard concept and CDM table for each ### Cohort definition by concept hierarchy Researchers building a cohort need every concept under a parent condition or drug class. GET `/concepts/{conceptId}/descendants` returns the concepts below a parent with max_levels and include_distance, filtered by vocabulary_ids and domain_ids, and GET `/concepts/{conceptId}/ancestors` walks the other way. POST `/concepts/hierarchy/batch` runs several hierarchy queries at once for a concept set. Example prompt: Call GET `/concepts/{conceptId}/descendants` for the Type 2 diabetes mellitus concept with domain_ids 'Condition' and include_distance true, and return the concept set ### Mapping quality review Before loading a source_to_concept_map, a team checks how well its source vocabulary maps. GET `/mappings/coverage` reports coverage between a source_vocabulary and target_vocabulary, GET `/mappings/quality/{sourceVocab}/{targetVocab}` returns quality figures for the pair, and POST `/mappings/validate` verifies a set of mappings so errors are caught before they reach the CDM. Example prompt: Call GET `/mappings/coverage` with source_vocabulary 'ICD10CM' and target_vocabulary 'SNOMED', then POST `/mappings/validate` with the team's draft mappings ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/concepts/by-code/{vocabularyId}/{conceptCode}` | Get a concept by vocabulary code | | GET | `/concepts/{conceptId}` | Get a concept by id | | POST | `/concepts/map` | Map concepts between vocabularies | | GET | `/concepts/{conceptId}/descendants` | Get concept descendants | | GET | `/search/concepts` | Search concepts | | GET | `/search/semantic` | Search concepts by meaning | | POST | `/fhir/resolve` | Resolve a FHIR Coding | | GET | `/vocabularies` | List vocabularies | ## Key resources - **Concepts** — Concepts by id or code, with hierarchy, relationships, mappings, related and recommended concepts, and batch lookups - **Search** — Basic, advanced, autocomplete, faceted, semantic, similar, and bulk concept search - **Mappings** — Concept mapping between vocabularies, coverage and quality reports, and mapping validation - **FHIR resolve** — Translation of FHIR Codings and CodeableConcepts into OMOP source and standard concepts - **Vocabularies and domains** — Vocabulary details, statistics, releases, domains, and concept classes ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 66 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 80 / 100 - Developer Experience & Jentic Compatibility: 70 / 100 - AI-Readiness & Agent Experience: 45 / 100 - Agent Usability: 93 / 100 - Security: 60 / 100 - AI Discoverability: 85 / 100 - **View full report:** https://jentic.com/apis/omophub.com/omophub/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring OMOPHub by hand means sending a bearer key, choosing among many search and mapping routes, pinning a vocab_release, and handling CPT4 licensing errors. Through Jentic you install once, import OMOPHub from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** OMOPHub puts the concept id and vocabulary id in the URL path, such as `/concepts/{conceptId}` and `/vocabularies/{vocabularyId}`, so a rule can pin your agent to one vocabulary or concept and the operations you pick. Every operation reads or computes over vocabularies, so the choice is about which lookups the agent may run. - **Credential handling:** Your OMOPHub API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'map an ICD-10 code to SNOMED' or 'resolve a FHIR coding', and Jentic returns the matching OMOPHub operation with its input schema, including vocabularyId, conceptCode, and target_vocabulary, so the agent calls it correctly. ## Related APIs - **RxNorm API** — NLM's normalized drug names and codes - **IntelliLynx ICD-10** — ICD-10 code lookup and search - **NIH Clinical Table Search Service** — NLM autocomplete search over clinical tables ## FAQ ### What authentication does the OMOPHub API use? Per its OpenAPI spec, the OMOPHub API uses HTTP bearer authentication with your API key in the Authorization header. Two routes are open without a key: the API information root and /health. CPT4 concepts additionally need the key owner to complete annual UMLS validation in the OMOPHub Dashboard. Through Jentic the key is stored by your own instance and attached at call time. ### Can I map ICD-10-CM codes to SNOMED with the OMOPHub API? Yes. Resolve the source code with GET `/concepts/by-code/{vocabularyId}/{conceptCode}`, then call POST `/concepts/map` with target_vocabulary set to SNOMED, the concept ids in source_concepts or raw codes in source_codes, and an optional mapping_type of direct, equivalent, broader, or narrower. POST `/concepts/map/batch` handles many mapping_requests in one call. ### What are the rate limits for the OMOPHub API? The OpenAPI spec does not specify rate limits. Check the OMOPHub documentation at https://omophub.com for current limits on your plan. ### Is there an OMOPHub MCP server? You don't need an MCP server to give your agent OMOPHub. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the concept, search, and mapping operations it needs on demand without loading another server's tool definitions into its context. ### How do I resolve a FHIR coding through Jentic? Search Jentic for 'resolve a FHIR coding to an OMOP concept', load the OMOPHub FHIR resolve operation, and execute it with the coding's system and code plus an optional resource_type such as Condition. The response carries the source concept, standard concept, and target CDM table. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Which vocabularies are restricted on OMOPHub? Per the spec, CPT4 needs annual UMLS validation and the validation expires each January 30 UTC. Unlicensed direct or CPT4-only requests return 403 vocabulary_restricted, while mixed search filters leave out CPT4 and return the accessible vocabularies. GPI and MedDRA are not available. ### Can I limit what my agent is allowed to do with the OMOPHub API? Yes. Write a rule that allows only the concept-by-code lookup and GET `/concepts/{conceptId}/mappings`, and the agent can resolve source codes and read their mappings but cannot run bulk or semantic search, and every call it makes is logged.