API Reference

The widget calls the following endpoints. You do not need to call them yourself; this reference shows what the callbacks receive and what the API base URL serves. All endpoints are prefixed with the apiBaseUrl you configure (https://gw.careconekt.net/api/codesystems-search), and every request carries your X-API-Key.

Autocomplete

GET /api/v1/autocomplete

Real-time search suggestions as the user types.

Parameters:

Name	Type	Required	Default	Description
`q`	string	Yes	—	Search query text (min 2 characters)
`code_system_slug`	string	No	all	Filter by code system (e.g., `icd10cm`)
`tenant_id`	string	No	—	Tenant UUID for multi-tenant search
`limit`	integer	No	10	Max suggestions (1–20)

Response:

{
  "items": [
    {
      "code": "E11.9",
      "display": "Type 2 diabetes mellitus without complications",
      "code_system_slug": "icd10cm",
      "code_system_name": "ICD10-CM"
    }
  ],
  "took_ms": 12
}

Search

GET /api/v1/search

Full-text search with faceted results and highlights.

Parameters:

Name	Type	Required	Default	Description
`q`	string	Yes	—	Search query text
`code_system_slug`	string	No	all	Filter by code system
`tenant_id`	string	No	—	Tenant UUID
`status`	string	No	`active`	Filter by status (`null` for all)
`size`	integer	No	20	Results per page (1–100)
`offset`	integer	No	0	Pagination offset

Response:

{
  "total": 142,
  "hits": [
    {
      "concept_id": "icd10cm-E11.9",
      "code": "E11.9",
      "code_system_slug": "icd10cm",
      "code_system_name": "ICD10-CM",
      "status": "active",
      "display": "Type 2 diabetes mellitus without complications",
      "score": 12.5,
      "highlights": {
        "display": ["Type 2 <em>diabetes</em> mellitus without complications"]
      }
    }
  ],
  "facets": {
    "code_systems": [
      { "slug": "icd10cm", "doc_count": 89 },
      { "slug": "loinc", "doc_count": 53 }
    ]
  },
  "took_ms": 34
}

Concept Detail

GET /api/v1/concepts/{concept_id}

Full details for a single concept.

Parameters:

Name	Type	Required	Description
`concept_id`	string (path)	Yes	The concept identifier
`tenant_id`	string (query)	No	Tenant UUID

Response:

{
  "concept_id": "icd10cm-E11.9",
  "code": "E11.9",
  "code_system_slug": "icd10cm",
  "code_system_name": "ICD10-CM",
  "version": "2024",
  "status": "active",
  "display": "Type 2 diabetes mellitus without complications",
  "definition": "A type of diabetes mellitus...",
  "synonyms": ["DM2", "NIDDM", "Adult-onset diabetes"],
  "parent_codes": ["E11"],
  "child_codes": [],
  "last_updated": "2024-01-15",
  "properties": {
    "chapter": "IV",
    "block": "E08-E13"
  },
  "score": null
}

Error: Returns 404 if the concept is not found.

Code Systems

GET /api/v1/code-systems

List all available code systems with document counts.

Parameters:

Name	Type	Required	Description
`tenant_id`	string	No	Tenant UUID

Response:

[
  { "slug": "icd10cm", "name": "ICD10-CM", "doc_count": 46498 },
  { "slug": "cpt", "name": "CPT", "doc_count": 15245 },
  { "slug": "loinc", "name": "LOINC", "doc_count": 108248 },
  { "slug": "rxnorm", "name": "RxNorm", "doc_count": 82482 }
]

Error Responses

Status	Meaning	Widget behavior
401	Invalid or missing API key	`onError("Invalid API key")`
403	Valid key but no access to this service	`onError("Access denied — check your subscription plan")`
404	Concept not found	`onError("API error: Not Found")`
429	Rate limit exceeded	`onError("Rate limit exceeded — try again later")`
502	The search service is temporarily unavailable	`onError("API error: Bad Gateway")`