> For the complete documentation index, see [llms.txt](https://docs.bloodgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloodgpt.com/interpretation-and-results/interpret.md).

# Interpret & Summary

Trigger AI interpretation for a single test or for a patient's whole record

These endpoints trigger BloodGPT's AI interpretation pipeline. Both are asynchronous: they return immediately with a tracking id, and results are delivered through your configured [Webhooks](/interpretation-and-results/webhooks.md) (and surfaced in the dashboard / [Widgets](/reference/widgets.md)).

There are two scopes — choose by intent:

| Endpoint                           | Scope         | Use when                                                           |
| ---------------------------------- | ------------- | ------------------------------------------------------------------ |
| `POST /api/v1/interpret/{test_id}` | Single test   | Interpret one specific uploaded test                               |
| `POST /api/v1/summary`             | Whole patient | Re-analyze a patient across all of their data ("generate summary") |

***

## Interpret a Single Test

**Endpoint:** `POST /api/v1/interpret/{test_id}`

Runs interpretation for a test that has completed recognition. The request body is optional.

```json
{
  "processing_options": {
    "target_language": "en"
  }
}
```

### cURL Example

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/interpret/clxyz789012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"processing_options": {"target_language": "en"}}'
```

### Response (202 Accepted)

```json
{
  "request_id": "req_abc123",
  "test_id": "clxyz789012",
  "status": "interpreting",
  "message": "Interpretation pipeline started"
}
```

Returns `404` if the test does not exist, and a `400`-class error if the test is not in a state that can be interpreted (recognition must have completed first).

***

## Generate a Patient Summary

**Endpoint:** `POST /api/v1/summary`

Generates a patient-scoped summary from the patient's entire FHIR record (not a single test). This creates a `HealthReportRun` and returns its id for status tracking.

### Request

```json
{
  "patient_id": "clxyz123456",
  "processing_options": {
    "target_language": "en"
  }
}
```

| Field                | Type   | Required | Description                              |
| -------------------- | ------ | -------- | ---------------------------------------- |
| `patient_id`         | string | Yes      | The patient's internal id (`Patient.id`) |
| `processing_options` | object | No       | Language and report options              |

### cURL Example

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/summary \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"patient_id": "clxyz123456"}'
```

### Response (202 Accepted)

```json
{
  "request_id": "req_abc123",
  "patient_id": "clxyz123456",
  "analysis_run_id": "clrun123456",
  "status": "waiting_for_analysis",
  "message": "Patient summary pipeline started"
}
```

| Field             | Type   | Description                                                  |
| ----------------- | ------ | ------------------------------------------------------------ |
| `analysis_run_id` | string | `HealthReportRun` id — use it for status / trace bookkeeping |
| `status`          | string | Run status (e.g. `waiting_for_analysis`)                     |

### Errors

| Status | `error`              | Meaning                                                     |
| ------ | -------------------- | ----------------------------------------------------------- |
| `422`  | `missing_patient_id` | `patient_id` was not provided                               |
| `404`  | `patient_not_found`  | No such patient in your organization                        |
| `409`  | `no_prior_test`      | Patient has no completed test yet — upload a document first |

See [Errors & Validation](/reference/errors.md) for the shared error contract.