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

# CDS Hooks

> Clinical Decision Support Hooks registration, invocation, and feedback.

The CDS Hooks simulator stands in for the EHR side of the [CDS Hooks](https://cds-hooks.hl7.org/) specification. It lets you register a CDS service, invoke hooks with a simulated clinical context (`patient-view`, `order-select`, `medication-prescribe`, etc.), and record user feedback on the cards that come back. Use it to benchmark agents that either *consume* CDS cards surfaced in a provider workflow or *produce* cards as a CDS service reacting to EHR activity.

## How your agent connects

The CDS sandbox exposes a CDS Hooks-style surface on the direct-service path. Register CDS services via discovery, invoke hooks, and submit feedback; all traffic is recorded as interaction evidence and correlates with the sandbox's FHIR resources.

<Note>
  CDS Hooks endpoints are not currently mounted on the run-scoped
  `/v1/benchmark-runs/{id}/cds/*` surface. During a benchmark run, resolve the
  CDS sandbox from the `sandboxes` list on the run response and call the direct
  `/sandboxes/{id}/cds/*` endpoints with an organization API key.
</Note>

## Endpoints

| Method | Endpoint                                   | Description                                                                                            |
| ------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `POST` | `/sandboxes/{sandbox_id}/cds/services`     | Register CDS services by pointing to a discovery URL                                                   |
| `GET`  | `/sandboxes/{sandbox_id}/cds/services`     | List CDS services currently registered with the sandbox                                                |
| `POST` | `/sandboxes/{sandbox_id}/cds/hooks/{hook}` | Fire a hook (e.g. `patient-view`, `order-select`) with a simulated context; returns the cards produced |
| `POST` | `/sandboxes/{sandbox_id}/cds/feedback`     | Record user feedback on a CDS card (accepted, overridden, ignored)                                     |

See [Register CDS service](/api-reference/cds/register), [List CDS services](/api-reference/cds/list), [Invoke CDS hook](/api-reference/cds/invoke), and [Submit CDS feedback](/api-reference/cds/feedback).

## Driving the rollout

Register CDS services by pointing at a discovery URL (CDS Hooks publishes a `/cds-services` endpoint per vendor):

```bash theme={null}
curl -X POST "https://api.verial.ai/sandboxes/$CDS_SANDBOX_ID/cds/services" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discovery_url": "https://cds.example.com/cds-services"
  }'
```

Fire a hook (body fields are flat, snake\_case):

```bash theme={null}
curl -X POST "https://api.verial.ai/sandboxes/$CDS_SANDBOX_ID/cds/hooks/patient-view" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "patient-123",
    "user_id": "Practitioner/rivera",
    "encounter_id": "encounter-456"
  }'
```

Record feedback on a card the agent decided to act on:

```bash theme={null}
curl -X POST "https://api.verial.ai/sandboxes/$CDS_SANDBOX_ID/cds/feedback" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "drug-interaction-check",
    "card_uuid": "card_01H...",
    "outcome": "accepted",
    "accepted_suggestions": ["suggestion-1"]
  }'
```

## Configuration

At create time you configure the hooks the sandbox will advertise and, optionally, canned cards the sandbox will return when a hook is invoked.

```bash theme={null}
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CdsHooks",
    "name": "EHR CDS Surface",
    "config": {
      "hooks": ["patient-view", "order-select", "medication-prescribe"]
    }
  }'
```

## Verification

There is no dedicated CDS Hooks check type in the current criterion catalog. CDS evidence is scored in two ways:

* **Interaction evidence.** Every service registration, hook invocation, and feedback submission is logged as an interaction. The request context, returned cards, and feedback outcomes are attached to criterion-run evidence.
* **Cross-simulator criteria.** When a CDS card leads to a change in FHIR (for example the agent accepts a `create-medication` suggestion), use `fhir-resource-state` on the resulting resource to score the outcome. When it leads to a portal action, use `portal-state-match`.

## Next Steps

<CardGroup cols={2}>
  <Card title="FHIR" icon="database" href="/guides/simulators/fhir">
    CDS context objects reference FHIR resources; pair this simulator with a FHIR simulator.
  </Card>

  <Card title="CDS API reference" icon="code" href="/api-reference/cds/register">
    Direct-access CDS Hooks endpoints for authoring.
  </Card>

  <Card title="Criteria" icon="check-double" href="/guides/concepts/criteria">
    The assertions the verification engine currently supports.
  </Card>

  <Card title="Simulators overview" icon="server" href="/guides/simulators/overview">
    Lifecycle, provisioning, and configuration patterns.
  </Card>
</CardGroup>