{ "openapi": "3.1.0", "info": { "title": "healthcare.dev API", "version": "0.0.0", "description": "US healthcare reference data. Reference data only, not clinical advice. Never send PHI." }, "servers": [ { "url": "https://api.healthcare.dev" } ], "components": { "schemas": { "Code": { "type": "object", "properties": { "system": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ] }, "code": { "type": "string" }, "display": { "type": "string", "description": "Short description" }, "description": { "type": [ "string", "null" ], "description": "Long description" }, "billable": { "type": "boolean", "description": "Valid for billing (leaf / header flag)" }, "parent": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "System-specific attributes, e.g. HCPCS coverage and BETOS codes" }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "system", "code", "display", "description", "billable", "parent", "status", "effective_start", "effective_end" ] }, "Meta": { "type": "object", "properties": { "source": { "type": "string", "description": "Upstream source id, e.g. `nppes`, `cms-icd10cm`" }, "data_version": { "type": "string", "description": "Published dataset version the response was served from" }, "retrieved_at": { "type": "string", "format": "date-time", "description": "When the response was generated" }, "license": { "type": "string", "description": "License or attribution terms for the data" }, "source_url": { "type": "string", "format": "uri", "description": "Upstream page the data is published on, to verify or cite the source" }, "as_of": { "type": "string", "format": "date", "description": "Present when the record was resolved as of a past date" } }, "required": [ "source", "data_version", "retrieved_at", "license" ] }, "Links": { "type": "object", "properties": { "self": { "type": "string" }, "next": { "type": [ "string", "null" ] } } }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI identifying the problem type" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] }, "description": "Field-level validation errors" }, "hint": { "type": "string", "description": "How to fix the request, in one sentence" }, "upgrade": { "type": "string", "format": "uri", "description": "Where to get an API key or a plan that allows this request (keyless callers)" }, "example": { "type": "string", "description": "A corrected request (method and path) to try instead, when one can be inferred" }, "did_you_mean": { "type": "array", "items": { "type": "string" }, "description": "Close matches for an unknown code or identifier, best first" } }, "required": [ "type", "title", "status" ] }, "CodeSearchResult": { "type": "object", "properties": { "system": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ] }, "code": { "type": "string" }, "display": { "type": "string", "description": "Short description" }, "description": { "type": [ "string", "null" ], "description": "Long description" }, "billable": { "type": "boolean", "description": "Valid for billing (leaf / header flag)" }, "parent": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "System-specific attributes, e.g. HCPCS coverage and BETOS codes" }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] }, "match_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "How well this result matches the query: 1 exact code or id, 0.9 code prefix, 0.5 to 0.9 every query word in the text (higher is closer), under 0.5 a fuzzy (typo-tolerant) match. Below 0.5, check the result before relying on it." } }, "required": [ "system", "code", "display", "description", "billable", "parent", "status", "effective_start", "effective_end", "match_score" ] }, "CodeBatchResult": { "type": "object", "properties": { "code": { "type": "string" }, "found": { "type": "boolean" }, "record": { "allOf": [ { "$ref": "#/components/schemas/Code" }, { "type": [ "object", "null" ] } ] } }, "required": [ "code", "found", "record" ] }, "NdcProduct": { "type": "object", "properties": { "product_ndc": { "type": "string" }, "spl_document_ids": { "type": "array", "items": { "type": "string" }, "description": "SPL documents listing this product (FDA PRODUCTID suffixes)" }, "brand_name": { "type": [ "string", "null" ] }, "generic_name": { "type": [ "string", "null" ] }, "labeler": { "type": "string" }, "dosage_form": { "type": [ "string", "null" ] }, "route": { "type": "array", "items": { "type": "string" } }, "active_ingredients": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": [ "string", "null" ] } }, "required": [ "name", "strength" ] } }, "product_type": { "type": "string" }, "marketing_category": { "type": [ "string", "null" ] }, "application_number": { "type": [ "string", "null" ] }, "pharm_classes": { "type": "array", "items": { "type": "string" } }, "dea_schedule": { "type": [ "string", "null" ] }, "listing_certified_through": { "type": [ "string", "null" ], "format": "date" }, "rxcuis": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Linked RxNorm concepts (filled at query time)" }, "rxnorm": { "type": "array", "items": { "type": "object", "properties": { "rxcui": { "type": "string" }, "name": { "type": "string" }, "tty": { "type": "string" } }, "required": [ "rxcui", "name", "tty" ] }, "default": [], "description": "Linked RxNorm concepts with names and term types (filled at query time)" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/NdcPackage" } }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "product_ndc", "spl_document_ids", "brand_name", "generic_name", "labeler", "dosage_form", "route", "active_ingredients", "product_type", "marketing_category", "application_number", "pharm_classes", "dea_schedule", "listing_certified_through", "packages", "status", "effective_start", "effective_end" ] }, "NdcPackage": { "type": "object", "properties": { "ndc": { "type": "string", "description": "Package NDC as labeled (e.g. 0002-1433-80)" }, "ndc11": { "type": "string", "pattern": "^\\d{11}$", "description": "Normalized 5-4-2 NDC without hyphens" }, "description": { "type": "string" }, "marketing_start": { "type": [ "string", "null" ], "format": "date" }, "marketing_end": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "ndc", "ndc11", "description", "marketing_start", "marketing_end" ] }, "RxNormConcept": { "type": "object", "properties": { "rxcui": { "type": "string", "pattern": "^\\d+$" }, "name": { "type": "string" }, "tty": { "type": "string", "description": "RxNorm term type, e.g. SCD, SBD, IN" }, "prescribable_name": { "type": [ "string", "null" ], "description": "RxNorm PSN, when one exists" }, "synonyms": { "type": "array", "items": { "type": "string" } }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "rxcui": { "type": "string" }, "name": { "type": "string" } }, "required": [ "rxcui", "name" ] } }, "related": { "type": "array", "items": { "type": "object", "properties": { "rxcui": { "type": "string" }, "name": { "type": "string" }, "tty": { "type": "string" }, "rela": { "type": "string" } }, "required": [ "rxcui", "name", "tty", "rela" ] } }, "ndcs": { "type": "array", "items": { "type": "string", "pattern": "^\\d{11}$" }, "description": "NDC-11s linked by RxNorm" }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "rxcui", "name", "tty", "prescribable_name", "synonyms", "ingredients", "related", "ndcs", "status", "effective_start", "effective_end" ] }, "RxNormSearchResult": { "type": "object", "properties": { "rxcui": { "type": "string", "pattern": "^\\d+$" }, "name": { "type": "string" }, "tty": { "type": "string", "description": "RxNorm term type, e.g. SCD, SBD, IN" }, "prescribable_name": { "type": [ "string", "null" ], "description": "RxNorm PSN, when one exists" }, "synonyms": { "type": "array", "items": { "type": "string" } }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "rxcui": { "type": "string" }, "name": { "type": "string" } }, "required": [ "rxcui", "name" ] } }, "related": { "type": "array", "items": { "type": "object", "properties": { "rxcui": { "type": "string" }, "name": { "type": "string" }, "tty": { "type": "string" }, "rela": { "type": "string" } }, "required": [ "rxcui", "name", "tty", "rela" ] } }, "ndcs": { "type": "array", "items": { "type": "string", "pattern": "^\\d{11}$" }, "description": "NDC-11s linked by RxNorm" }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] }, "match_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "How well this result matches the query: 1 exact code or id, 0.9 code prefix, 0.5 to 0.9 every query word in the text (higher is closer), under 0.5 a fuzzy (typo-tolerant) match. Below 0.5, check the result before relying on it." } }, "required": [ "rxcui", "name", "tty", "prescribable_name", "synonyms", "ingredients", "related", "ndcs", "status", "effective_start", "effective_end", "match_score" ] }, "DrugSearchHit": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "rxnorm", "ndc" ] }, "id": { "type": "string", "description": "RxCUI or product NDC" }, "name": { "type": "string" }, "tty": { "type": [ "string", "null" ], "description": "RxNorm term type (rxnorm hits)" }, "labeler": { "type": [ "string", "null" ], "description": "Labeler (ndc hits)" }, "match_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "How well this result matches the query: 1 exact code or id, 0.9 code prefix, 0.5 to 0.9 every query word in the text (higher is closer), under 0.5 a fuzzy (typo-tolerant) match. Below 0.5, check the result before relying on it." } }, "required": [ "type", "id", "name", "tty", "labeler", "match_score" ] }, "Taxonomy": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Z]{9}X$" }, "grouping": { "type": "string" }, "classification": { "type": "string" }, "specialization": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "definition": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "section": { "type": "string", "enum": [ "individual", "non-individual" ] }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "code", "grouping", "classification", "specialization", "display_name", "definition", "notes", "section", "status", "effective_start", "effective_end" ] }, "TaxonomySearchResult": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Z]{9}X$" }, "grouping": { "type": "string" }, "classification": { "type": "string" }, "specialization": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "definition": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "section": { "type": "string", "enum": [ "individual", "non-individual" ] }, "status": { "type": "string", "enum": [ "active", "retired", "replaced" ] }, "effective_start": { "type": "string", "format": "date" }, "effective_end": { "type": [ "string", "null" ], "format": "date" }, "replaced_by": { "type": "array", "items": { "type": "string" }, "default": [] }, "match_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "How well this result matches the query: 1 exact code or id, 0.9 code prefix, 0.5 to 0.9 every query word in the text (higher is closer), under 0.5 a fuzzy (typo-tolerant) match. Below 0.5, check the result before relying on it." } }, "required": [ "code", "grouping", "classification", "specialization", "display_name", "definition", "notes", "section", "status", "effective_start", "effective_end", "match_score" ] }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "description": "Dataset id, e.g. `nppes`, `icd10cm`" }, "name": { "type": "string" }, "source": { "type": "string" }, "license": { "type": "string" }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "Upstream page the data is published on" }, "current_version": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "expected_cadence_days": { "type": "integer", "exclusiveMinimum": 0 }, "fresh": { "type": "boolean", "description": "False when older than 1.5x the expected cadence" } }, "required": [ "id", "name", "source", "license", "source_url", "current_version", "published_at", "expected_cadence_days", "fresh" ] }, "Change": { "type": "object", "properties": { "dataset": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "added", "changed", "retired" ] }, "data_version": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "dataset", "key", "kind", "data_version", "published_at" ] } }, "parameters": {} }, "paths": { "/healthz": { "get": { "x-dataset-class": "free", "summary": "Process liveness", "description": "Returns 200 while the process is up. Does not check dependencies.", "tags": [ "Meta" ], "responses": { "200": { "description": "Process is alive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" } }, "required": [ "status", "version" ] } } } } } } }, "/readyz": { "get": { "x-dataset-class": "free", "summary": "Dependency readiness", "description": "Returns 200 when the database and cache are reachable, 503 otherwise.", "tags": [ "Meta" ], "responses": { "200": { "description": "Ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "checks": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "ok", "fail" ] } } }, "required": [ "status", "checks" ] } } } }, "503": { "description": "A dependency is unreachable" } } } }, "/v1/codes/{system}/{code}": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Codes" ], "summary": "Look up a code", "description": "Returns one ICD-10-CM, ICD-10-PCS or HCPCS Level II code with its description, billable flag, parent and lifecycle (`status`, `effective_start`, `effective_end`). Retired codes stay available. Pass `as_of` to get the code as it was on a past date.", "parameters": [ { "schema": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ], "description": "Code system", "example": "icd10cm" }, "required": true, "description": "Code system", "name": "system", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 10, "description": "Code, with or without the dot", "example": "E11.9" }, "required": true, "description": "Code, with or without the dot", "name": "code", "in": "path" }, { "schema": { "type": "string", "format": "date", "description": "Return the record as it was on this date (YYYY-MM-DD)", "example": "2025-01-01" }, "required": false, "description": "Return the record as it was on this date (YYYY-MM-DD)", "name": "as_of", "in": "query" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "The code", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Code" }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/codes/{system}": { "get": { "x-dataset-class": "core_search", "tags": [ "Codes" ], "summary": "Search codes", "description": "Search by description or code prefix. Exact code matches rank first, then code prefixes, then descriptions containing every word of the query (stemmed, any order) by relevance, then close matches for typos. Retired codes are excluded unless `include_retired=true`.", "parameters": [ { "schema": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ], "description": "Code system", "example": "icd10cm" }, "required": true, "description": "Code system", "name": "system", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search text (fuzzy)", "example": "diabetes" }, "required": true, "description": "Search text (fuzzy)", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Page size (max 100)" }, "required": false, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from `links.next`" }, "required": false, "description": "Opaque cursor from `links.next`", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Only billable (true) or header (false) codes" }, "required": false, "description": "Only billable (true) or header (false) codes", "name": "billable", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Also return retired codes (default false)" }, "required": false, "description": "Also return retired codes (default false)", "name": "include_retired", "in": "query" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Matching codes, best first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CodeSearchResult" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/codes/{system}/{code}/children": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Codes" ], "summary": "Child codes", "description": "Direct children of a code in the hierarchy (active codes only).", "parameters": [ { "schema": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ], "description": "Code system", "example": "icd10cm" }, "required": true, "description": "Code system", "name": "system", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 10, "description": "Code, with or without the dot", "example": "E11.9" }, "required": true, "description": "Code, with or without the dot", "name": "code", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Children", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/codes/{system}/{code}/parents": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Codes" ], "summary": "Ancestor codes", "description": "Ancestors of a code from the root down to its immediate parent.", "parameters": [ { "schema": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ], "description": "Code system", "example": "icd10cm" }, "required": true, "description": "Code system", "name": "system", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 10, "description": "Code, with or without the dot", "example": "E11.9" }, "required": true, "description": "Code, with or without the dot", "name": "code", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Ancestors", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/codes/{system}/{code}/hierarchy": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Codes" ], "summary": "Code with ancestors and children", "description": "The code, its ancestors (root first) and its direct active children in one call.", "parameters": [ { "schema": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ], "description": "Code system", "example": "icd10cm" }, "required": true, "description": "Code system", "name": "system", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 10, "description": "Code, with or without the dot", "example": "E11.9" }, "required": true, "description": "Code, with or without the dot", "name": "code", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Hierarchy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "parents": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "code": { "$ref": "#/components/schemas/Code" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } } }, "required": [ "parents", "code", "children" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/codes/{system}/batch": { "post": { "x-dataset-class": "core_search", "tags": [ "Codes" ], "summary": "Look up up to 100 codes", "description": "Looks up many codes in one request. Results come back in request order; unknown codes have `found: false`.", "parameters": [ { "schema": { "type": "string", "enum": [ "icd10cm", "icd10pcs", "hcpcs" ], "description": "Code system", "example": "icd10cm" }, "required": true, "description": "Code system", "name": "system", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10 }, "minItems": 1, "maxItems": 100 } }, "required": [ "codes" ], "example": { "codes": [ "E11.9", "I10" ] } } } } }, "responses": { "200": { "description": "Results in request order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CodeBatchResult" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/drugs/ndc/{ndc}": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Drugs" ], "summary": "Look up an NDC", "description": "Accepts a product NDC (`0002-0152`), a package NDC in any 10-digit layout (`0002-0152-01`) or an 11-digit NDC (`00002015201`). Returns the FDA product with its packages (each normalized to NDC-11) and the linked RxNorm concepts (`rxcuis`).", "parameters": [ { "schema": { "type": "string", "minLength": 9, "maxLength": 14, "example": "0002-0152-01", "description": "Product, package (any 10-digit layout) or 11-digit NDC, with or without hyphens" }, "required": true, "description": "Product, package (any 10-digit layout) or 11-digit NDC, with or without hyphens", "name": "ndc", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "The product", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NdcProduct" }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/drugs/rxnorm/{rxcui}": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Drugs" ], "summary": "Look up an RxNorm concept", "description": "An RxNorm concept with its term type, ingredients, related concepts and linked NDC-11s.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{1,8}$", "example": "861007", "description": "RxNorm concept unique identifier" }, "required": true, "description": "RxNorm concept unique identifier", "name": "rxcui", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "The concept", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RxNormConcept" }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/drugs/rxnorm": { "get": { "x-dataset-class": "core_search", "tags": [ "Drugs" ], "summary": "Search RxNorm", "description": "Fuzzy search over RxNorm names, prescribable names and synonyms. Filter by term type with `tty` (e.g. `IN`, `SCD`, `SBD`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search text (fuzzy)", "example": "diabetes" }, "required": true, "description": "Search text (fuzzy)", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Page size (max 100)" }, "required": false, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from `links.next`" }, "required": false, "description": "Opaque cursor from `links.next`", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Z]{2,5}$", "example": "SCD", "description": "Only concepts of this RxNorm term type" }, "required": false, "description": "Only concepts of this RxNorm term type", "name": "tty", "in": "query" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Matching concepts, best first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RxNormSearchResult" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/drugs/search": { "get": { "x-dataset-class": "core_search", "tags": [ "Drugs" ], "summary": "Search drugs across RxNorm and NDC", "description": "Searches RxNorm concepts and FDA NDC products together, ranked by `match_score` across both (RxNorm first on ties); `limit` applies to each source.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search text (fuzzy)", "example": "diabetes" }, "required": true, "description": "Search text (fuzzy)", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Page size (max 100)" }, "required": false, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Hits", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DrugSearchHit" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/taxonomies/{code}": { "get": { "x-dataset-class": "core_lookup", "tags": [ "Taxonomies" ], "summary": "Look up a provider taxonomy code", "description": "NUCC Health Care Provider Taxonomy code with classification, specialization and definition. Returns 503 `dataset-unavailable` until the NUCC license is in place.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9A-Za-z]{9}[Xx]$", "example": "207Q00000X", "description": "10-character NUCC taxonomy code" }, "required": true, "description": "10-character NUCC taxonomy code", "name": "code", "in": "path" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "The taxonomy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Taxonomy" }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/taxonomies": { "get": { "x-dataset-class": "core_search", "tags": [ "Taxonomies" ], "summary": "Search provider taxonomies", "description": "Fuzzy search over taxonomy names, classifications and specializations.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search text (fuzzy)", "example": "diabetes" }, "required": true, "description": "Search text (fuzzy)", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Page size (max 100)" }, "required": false, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from `links.next`" }, "required": false, "description": "Opaque cursor from `links.next`", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "compact", "full" ], "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field" }, "required": false, "description": "`compact` returns only the fields an agent usually needs (fewer tokens); `full` (default) returns every field", "name": "view", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z_]+(,[a-z_]+)*$", "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "example": "code,display,billable" }, "required": false, "description": "Comma-separated record fields to return, e.g. `code,display,billable`", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "Matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomySearchResult" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/datasets": { "get": { "x-dataset-class": "free", "tags": [ "Datasets" ], "summary": "Dataset catalog", "description": "Every published dataset with its current version, publish time, expected cadence and freshness.", "responses": { "200": { "description": "Datasets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/changes": { "get": { "x-dataset-class": "free", "tags": [ "Datasets" ], "summary": "Change feed", "description": "Records added, changed or retired by each published release of a dataset. Oldest first by default (for feed consumers); `order=desc` returns the most recent first. Page with `cursor`. The first (baseline) load of a dataset writes no change rows.", "parameters": [ { "schema": { "type": "string", "example": "icd10cm", "description": "Dataset id from `/v1/datasets`" }, "required": true, "description": "Dataset id from `/v1/datasets`", "name": "dataset", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only changes published after this time" }, "required": false, "description": "Only changes published after this time", "name": "since", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Page size, 1 to 1000 (default 100)" }, "required": false, "description": "Page size, 1 to 1000 (default 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "asc = oldest first (default), desc = newest first" }, "required": false, "description": "asc = oldest first (default), desc = newest first", "name": "order", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d+$", "description": "Opaque cursor from `links.next`" }, "required": false, "description": "Opaque cursor from `links.next`", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Changes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta", "links" ] } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dataset not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/status": { "get": { "x-dataset-class": "free", "tags": [ "Meta" ], "summary": "Service and data freshness status", "description": "Public, no authentication. `degraded` when any dataset is older than 1.5x its expected cadence.", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "datasets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "published_at": { "type": "string" }, "fresh": { "type": "boolean" } }, "required": [ "id", "version", "published_at", "fresh" ] } } }, "required": [ "status", "datasets" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "links": { "$ref": "#/components/schemas/Links" } }, "required": [ "data", "meta" ] } } } } } } } }, "webhooks": {} }