# 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
[
  { "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")` |