> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Clinical Decision Support

> Corrective CDSS alerts on a medical record, and how to read them

Corrective CDSS ("clinical decision support") reviews a completed consultation against clinical guidelines and flags actionable issues in the record — an omitted medication, an incorrect dosage, a non-pertinent order. Each finding is an **alert**.

Alerts are attached to the medical record: read them from the `cdssAlerts` field on the [medical record documents](/scribe-api/medical-record-documents) endpoint. `cdssAlerts` is `null` when clinical decision support is disabled for the session or no alerts were generated, and `[]` when it ran and produced none.

## The alert model

```json theme={null}
{
  "id": "cfa_9cba9fa0…SKULL_XRAY",
  "elementId": "SKULL_XRAY",
  "reason": "Loss of consciousness after a suspected concussion; a skull X-ray does not adequately assess intracranial injury.",
  "action": "Replace the skull X-ray with a non-contrast head CT.",
  "actionCategory": "replace",
  "type": "diagnostic_test",
  "issue": "not_pertinent",
  "element": "Skull X-ray",
  "severity": "red",
  "source": ["NICE Head Injury: Assessment and Early Management Guideline NG232, 2023"],
  "newPlanElement": {
    "type": "diagnostic_test",
    "element": "Non-contrast head CT",
    "id": "HEAD_CT",
    "content": "Non-contrast head CT",
    "laboratory": null
  },
  "previousTestDate": null,
  "guidelineIntervalDays": null,
  "status": "accepted"
}
```

<Tip>
  Use `id` as the alert's identifier — it is a stable, opaque token. `elementId` is the clinical element key (e.g. `ASPIRIN`); it is human-readable but can repeat across documents, so never use it as an identifier.
</Tip>

## Field reference

| Field                   | Type           | Description                                                                                                                                                       |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string         | Stable, opaque alert identifier. Use it as-is; do not parse it                                                                                                    |
| `elementId`             | string         | Clinical element key (e.g. `ASPIRIN`). Human-readable, not unique across documents                                                                                |
| `reason`                | string         | Why the alert was raised                                                                                                                                          |
| `action`                | string         | The recommended action                                                                                                                                            |
| `actionCategory`        | string         | `add` \| `remove` \| `replace` \| `modify`                                                                                                                        |
| `type`                  | string         | Order type: `medication`, `diagnostic_test`, `interconsultation`, `referral`, `follow_up`, `general_order`, `non_pharmacological`, `warning_signs`                |
| `issue`                 | string         | `incorrect_dosage` \| `omission` \| `not_pertinent`                                                                                                               |
| `element`               | string         | The plan element the alert refers to                                                                                                                              |
| `severity`              | string         | `red` \| `orange` \| `yellow`                                                                                                                                     |
| `source`                | array          | Guideline citations backing the alert                                                                                                                             |
| `newPlanElement`        | object \| null | The element the alert proposes (on `add`/`replace`/`modify`): `{ type, element, id, content, laboratory }`. Its `content` shape varies with the record's template |
| `previousTestDate`      | string \| null | For test recommendations, the date of the previous test                                                                                                           |
| `guidelineIntervalDays` | number \| null | For test recommendations, the guideline interval in days                                                                                                          |
| `status`                | string         | The doctor's decision: `pending` \| `accepted` \| `rejected`                                                                                                      |

## Acting on an alert

Record the doctor's decision with the alert's `id`. Accepting an alert applies its
proposed change to the medical record; rejecting one leaves the record unchanged. Both
require an API key carrying `scribe:write` or `scribe:cdss`.

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/cdss/alerts/ALERT_ID/accept \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO",
  "elementId": "IBUPROFEN",
  "status": "accepted"
}
```

Use the same request against `/reject` to reject the alert.

<Tip>
  A success response means the decision was recorded. An accepted alert is applied to the medical record in the background, so re-reading the record immediately afterwards may still show its previous content. The alert's own `status` is updated right away.
</Tip>

Recording the same decision twice is safe — the decision is stored per alert, so a
retry produces the same result.

### Several alerts at once

Send one request per consultation review instead of one per alert. Every alert is
validated before any decision is recorded, so a batch containing an alert you cannot
act on records nothing.

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/cdss/decisions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decisions":[{"id":"ALERT_ID","decision":"accepted"}]}'
```

**Response:**

```json theme={null}
{
  "decisions": [
    {
      "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO",
      "elementId": "IBUPROFEN",
      "status": "accepted"
    }
  ]
}
```

Each `decision` is `accepted` or `rejected`. The response lists one entry per submitted
alert, in the order received. An alert may appear only once per request.

## Errors

| Status | Code                  | When                                                                     |
| ------ | --------------------- | ------------------------------------------------------------------------ |
| 400    | `parameter_invalid`   | `alertId` is not a valid alert identifier, or the batch repeats an alert |
| 403    | `permission_denied`   | the API key lacks `scribe:write` and `scribe:cdss`                       |
| 404    | `resource_not_found`  | the alert does not exist or is not available for this API key            |
| 409    | `resource_not_active` | clinical decision support is not active for the consultation             |