> ## Documentation Index > Fetch the complete documentation index at: https://docs.valiancehealth.com/llms.txt > Use this file to discover all available pages before exploring further. # Search OMOP concepts (API) > Searches OMOP concepts across multiple medical vocabularies (ICD10, SNOMED, CPT4, etc.) with optional domain filtering. Returns matching concepts with metadata about the search. **Supports both JWT (Authorization: Bearer) and API key (X-API-Key) authentication.** Supported vocabularies: ICD10, ICD10CM, ICD10PCS, ICD9CM, ICD9Proc, SNOMED, CPT4, HCPCS, RxNorm, RxNorm Extension, OPCS4, DRG. A search with no `vocabularies` filter scans ICD10, ICD10CM, ICD10PCS, ICD9CM, ICD9Proc, SNOMED, CPT4, HCPCS, RxNorm, RxNorm Extension. DRG, OPCS4 are supported but must be requested by name. Supported domains: Condition, Procedure, Drug, Measurement, Observation, Device, Specimen. ## OpenAPI ````yaml /api/openapi-commercial.yaml post /api/v1/search/ openapi: 3.0.3 info: title: Healthproximate API version: 1.0.0 description: >- DRG classification, OMOP vocabulary services and a PHI-safe LLM gateway. Generated by `manage.py export_commercial_openapi` from an explicit operation allowlist (`app/openapi_commercial.py`). An endpoint appears here because someone published it, never because it exists. contact: email: admin@valiancehealth.ai servers: - url: https://api.v2.healthproximate.com security: [] tags: - name: DRG description: MS-DRG classification from coded input, free clinical text, or FHIR. - name: Vocabulary description: OMOP concept search, coding, translation and hierarchy resolution. - name: Gateway description: >- PHI-safe LLM access. Text is redacted before any model sees it and re-hydrated in the answer, and every response carries a receipt. paths: /api/v1/search/: post: tags: - Vocabulary summary: Search OMOP concepts (API) description: >- Searches OMOP concepts across multiple medical vocabularies (ICD10, SNOMED, CPT4, etc.) with optional domain filtering. Returns matching concepts with metadata about the search. **Supports both JWT (Authorization: Bearer) and API key (X-API-Key) authentication.** Supported vocabularies: ICD10, ICD10CM, ICD10PCS, ICD9CM, ICD9Proc, SNOMED, CPT4, HCPCS, RxNorm, RxNorm Extension, OPCS4, DRG. A search with no `vocabularies` filter scans ICD10, ICD10CM, ICD10PCS, ICD9CM, ICD9Proc, SNOMED, CPT4, HCPCS, RxNorm, RxNorm Extension. DRG, OPCS4 are supported but must be requested by name. Supported domains: Condition, Procedure, Drug, Measurement, Observation, Device, Specimen. operationId: v1_search_create parameters: - in: query name: profile schema: type: string enum: - explore - hybrid - mapping description: >- Profile preset that bundles sensible defaults for a use case. `mapping` — find equivalent codes in the requested vocabularies (2-hop graph traversal, vocab-filtered, no bridges). `explore` — show the full graph neighborhood (3-hop, includes SNOMED bridge concepts, no vocab filter, no quality gate). `hybrid` — plain text search, no graph. Individual params in the request body override profile defaults. - in: query name: q schema: type: string description: >- Search query string (e.g. 'diabetes', 'appendectomy'). Can also be supplied in the request body as `query` (one of `q` or `query` is required). - in: query name: response_format schema: type: string enum: - json - llm default: json description: >- Response format. 'json' (default) returns structured JSON. 'llm' returns compact markdown tables (text/markdown) optimized for LLM consumption. When 'llm', the response body is markdown text rather than the JSON schema shown below. - in: query name: search_mode schema: type: string enum: - graph - hybrid default: hybrid description: >- Search strategy. `hybrid` uses RRF+reranking (dense + sparse fusion); `graph` uses OMOP graph traversal for cross-vocabulary and hierarchical expansion. Overridden by the `profile` preset when both are set. requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchOMOPConceptRequestRequest' examples: HybridSearch(default): value: query: diabetes top_k: 5 summary: Hybrid search (default) description: Plain hybrid search across all supported vocabularies. GraphSearchWithVocabularyFilter: value: query: appendectomy vocabularies: - ICD10CM - ICD10PCS top_k: 10 include_bridges: false filter_to_input_vocab: true summary: Graph search with vocabulary filter description: >- Graph-native search restricted to ICD10CM/ICD10PCS. Cross-vocab anchor fallback (via SNOMED) and 2-hop Maps-to translation let queries like 'appendectomy' find ICD10PCS/CM equivalents even when the literal term isn't in the target vocabulary. MappingProfile(cross-vocabEquivalents): value: query: type 2 diabetes mellitus vocabularies: - SNOMED - ICD10CM top_k: 5 summary: Mapping profile (cross-vocab equivalents) description: >- Use the `mapping` profile to find equivalent codes across vocabularies. Pass `?profile=mapping` as a query-string param alongside this body. Query-string-only(q+Profile): value: {} summary: Query-string-only (q + profile) description: >- Minimal request using only query-string params. The body can be empty when `q` is supplied. Equivalent to the `mapping` example above but without a body. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SearchOMOPConceptRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/SearchOMOPConceptRequestRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchOMOPVocabularyResponse' description: Search results with metadata '400': description: >- Invalid request parameters (missing query, invalid search_mode, invalid vocabularies, invalid domain, or top_k out of range) '401': description: >- Invalid or missing authentication. Provide either Authorization header (Bearer token) or X-API-Key header. '500': description: Internal server error during search security: - api_key_auth: [] - jwt_auth: [] components: schemas: SearchOMOPConceptRequestRequest: type: object properties: query: type: string minLength: 1 description: Search query (e.g., 'diabetes', 'appendectomy') vocabularies: type: array items: type: string minLength: 1 description: >- List of vocabularies to search (e.g., ['ICD10', 'SNOMED']). If not provided, searches all. domain_id: type: string minLength: 1 description: Filter by domain (e.g., 'Condition', 'Procedure') top_k: type: integer maximum: 100 minimum: 1 default: 10 description: Number of results to return (1-100) find_relationship: type: boolean default: false description: >- If true, fetch 'Is a' relationships (parent concepts) for each result relationship_filters: type: object additionalProperties: {} description: >- Additional filters for ConceptRelationship query. Allowed keys: concept_id_2__concept_class_id, concept_id_2__concept_class_id__in, concept_id_2__vocabulary_id, concept_id_2__vocabulary_id__in, concept_id_2__domain_id, concept_id_2__domain_id__in search_type: allOf: - $ref: '#/components/schemas/SearchTypeEnum' default: websearch description: >- FTS search type: plain (simple word match), phrase (exact phrase), raw (tsquery syntax), websearch (web-style with +/-) * `plain` - plain * `phrase` - phrase * `raw` - raw * `websearch` - websearch language: type: string minLength: 1 default: english description: >- PostgreSQL text search configuration (e.g., 'english', 'simple', 'french') use_search_rank: type: boolean default: true description: Use SearchRank for ordering FTS results by relevance rank_normalization: type: integer default: 0 description: >- SearchRank normalization flags (0-31). See PostgreSQL docs for details. min_relevance: type: number format: double nullable: true default: -2 description: >- Cross-encoder logit threshold. Results scoring below this are dropped before being returned. ms-marco-MiniLM-L-6-v2 produces logits roughly in [-15, +15]; ~0 is the irrelevant/relevant boundary. Default -2.0 is permissive but blocks the 'no good match anywhere' case. Pass null to disable filtering and always return up to top_k results regardless of quality. include_bridges: type: boolean default: false description: >- Graph mode only. When True, surface the SNOMED-style standard 'bridge' concepts used for 2-hop Maps-to traversal (each marked `is_bridge: true` in the response). Useful for showing the user *why* a non-standard code was suggested. Default False. filter_to_input_vocab: type: boolean default: true description: >- Graph mode only. When True (default), restrict results to the vocabularies in the `vocabularies` filter. Set False to allow cross-vocab graph neighbors (e.g. for an LLM-agent profile). required: - query SearchOMOPVocabularyResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/OMOPConcept' metadata: $ref: '#/components/schemas/SearchMetadata' required: - metadata - results SearchTypeEnum: enum: - plain - phrase - raw - websearch type: string description: |- * `plain` - plain * `phrase` - phrase * `raw` - raw * `websearch` - websearch OMOPConcept: type: object properties: concept_id: type: integer concept_name: type: string concept_code: type: string vocabulary_id: type: string concept_class_id: type: string nullable: true similarity: type: number format: double nullable: true description: Final relevance score from cross-encoder reranking (both modes). graph_score: type: number format: double nullable: true description: >- Normalised graph-proximity score in [0, 1]. Present only when search_mode=graph. combined_score: type: number format: double nullable: true description: >- Deprecated alias of `graph_score` — the two are always equal. Kept so existing graph-mode callers do not break. This field once documented a weighted graph/text blend that the code never computed; read `graph_score` for the graph signal and `score` for the cross-encoder relevance. Present only when search_mode=graph. score: type: number format: double nullable: true description: >- Alias for similarity after rerank. Present only when search_mode=graph. is_bridge: type: boolean description: >- Present and True when this concept is a 2-hop Maps-to bridge (typically a SNOMED standard concept) surfaced via include_bridges=True. Absent on direct matches and translated in-vocab equivalents. parents: type: array items: $ref: '#/components/schemas/ParentConcept' nullable: true required: - concept_class_id - concept_code - concept_id - concept_name - vocabulary_id SearchMetadata: type: object properties: query: type: string description: The query string that was searched. vocabularies_searched: type: array items: type: string description: Vocabularies actually searched (normalized to DB casing). domain_id: type: string nullable: true description: Domain filter applied, or null if no domain filter. total_results: type: integer description: Number of results returned in this response. find_relationship: type: boolean description: Whether 'Is a' parent relationships were fetched. search_mode: allOf: - $ref: '#/components/schemas/SearchModeEnum' description: >- Effective search mode used. May differ from `requested_search_mode` when graph mode fell back to hybrid — see `fallback_reason`. * `hybrid` - hybrid * `graph` - graph requested_search_mode: allOf: - $ref: '#/components/schemas/SearchModeEnum' description: |- Search mode the caller asked for (before any fallback). * `hybrid` - hybrid * `graph` - graph profile: type: string nullable: true description: Profile preset applied, or null if no profile was requested. include_bridges: type: boolean description: Whether SNOMED bridge concepts were surfaced (graph mode). filter_to_input_vocab: type: boolean description: >- Whether results were post-filtered to the requested vocabularies (graph mode). fts_options: allOf: - $ref: '#/components/schemas/SearchFTSOptionsMetadata' description: Full-text-search options that were applied. fallback_reason: type: string description: >- Present only when `search_mode != requested_search_mode`. Explains why graph mode fell back to hybrid (e.g., no anchors, low-quality rerank, empty graph expansion). required: - domain_id - filter_to_input_vocab - find_relationship - fts_options - include_bridges - profile - query - requested_search_mode - search_mode - total_results - vocabularies_searched ParentConcept: type: object properties: parent_concept_id: type: integer parent_concept_code: type: string parent_concept_name: type: string required: - parent_concept_code - parent_concept_id - parent_concept_name SearchModeEnum: enum: - hybrid - graph type: string description: |- * `hybrid` - hybrid * `graph` - graph SearchFTSOptionsMetadata: type: object properties: search_type: type: string description: 'FTS search type used: ''plain'', ''phrase'', ''raw'', or ''websearch''.' language: type: string description: PostgreSQL text search configuration used (e.g., 'english'). use_search_rank: type: boolean description: Whether SearchRank ordering was applied. rank_normalization: type: integer description: SearchRank normalization flags used (0-31). required: - language - rank_normalization - search_type - use_search_rank securitySchemes: api_key_auth: type: apiKey in: header name: X-API-Key description: >- API key for organization authentication. Obtain from the organization settings or API key management endpoint. jwt_auth: type: http scheme: bearer bearerFormat: JWT description: JWT access token obtained from /login/ endpoint ````