> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/lab-reports/api-reference.md).

# API reference

Complete reference for all Lab Reports API endpoints.

**Base URL:** `https://access.tryterra.co/api`

All endpoints require the following headers:

| Header            | Type   | Required | Description                                                                                     |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `dev-id`          | string | Yes      | Your Terra developer ID                                                                         |
| `x-api-key`       | string | Yes      | Your Terra API key                                                                              |
| `X-Terra-Version` | string | No       | The API version to serve the request in, as a `YYYY-MM-DD` date. See [Versioning](#versioning). |

{% hint style="info" %}
These endpoints live under `/v2/reports`. They take DXA body-composition scans as well as clinical lab panels. If you integrated against the earlier `/v2/lab-reports` path it keeps working unchanged; point new work at `/v2/reports`.
{% endhint %}

Errors use the [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) Problem JSON format. When an error carries a machine-readable `code`, branch on it rather than on `detail`, which is written for people and can change.

```json
{
  "type": "about:blank",
  "title": "bad request",
  "detail": "file 0 is text/plain; upload a PDF or a PNG, JPEG, GIF, WebP or HEIC image",
  "instance": "/api/v2/reports",
  "code": "unsupported_file_type"
}
```

***

## Versioning

The Lab Reports API is versioned by date. Only the [List Sessions](#list-sessions) response differs between versions.

| Version      | What changed                                                                                                      |
| ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `2026-10-21` | Latest. The list is paginated: `limit` and `cursor` parameters, and a `data`, `has_more`, `next_cursor` response. |
| `2026-03-24` | The original shape. The list returns up to 500 sessions in `sessions`, with no pagination.                        |

Each request is served in one version, picked in this order:

1. The `X-Terra-Version` header, if you send one. It takes a date and serves the newest version on or before it. A date before `2026-03-24` serves `2026-03-24`.
2. Your environment's pinned version.
3. The latest version, if your environment has no pin.

Environments that used Lab Reports before `2026-10-21` was released, or whose account already had Lab Reports enabled, are pinned to `2026-03-24`. Existing integrations keep the list shape they were built against. An environment without a pin is pinned to the latest version on its first API request, so it keeps that version when a newer one is released.

Every authenticated response carries an `X-Terra-Version` header stating the version it was served in. A malformed date, or a date in the future, returns `400` with `code` `invalid_api_version`.

Webhook deliveries carry an `X-Terra-Version` header with your environment's pinned version. See [Webhook payload](https://docs.tryterra.co/lab-reports/webhook-payload.md#x-terra-version-header).

### Changing your pinned version

To move an environment to the paginated list:

1. Send `X-Terra-Version: 2026-10-21` on your list requests, and update your code to read `data` and follow `next_cursor`.
2. Change the pin, so requests without the header get the new version too. With the [Terra CLI](https://docs.tryterra.co/developer-tools/terra-cli/raw-requests):

```bash
terra admin-api /environments/YOUR_DEV_ID/lab-reports/api-version -X PUT -d version=2026-10-21
```

The change takes effect on the environment's next request. A `GET` on the same path shows the current pin, the latest version, and every version you can pin to. Changing the pin needs the `dataconfig:write` [scope](https://docs.tryterra.co/reference/admin-api/scopes). You can move the pin back to `2026-03-24` the same way. A pin cannot be removed.

***

## Upload a lab report

<mark style="color:green;">`POST`</mark> `/v2/reports`

Upload one report for processing, as multipart form data. Send the report as one file, or as one file per page, in page order. Accepted formats: PDF, PNG, JPEG, GIF, WebP and HEIC/HEIF.

### Headers

| Header         | Value                 |
| -------------- | --------------------- |
| `dev-id`       | Your developer ID     |
| `x-api-key`    | Your API key          |
| `Content-Type` | `multipart/form-data` |

### Query parameters

| Name           | Type   | Required | Description                                      |
| -------------- | ------ | -------- | ------------------------------------------------ |
| `reference_id` | string | No       | Your external identifier for this report/patient |

### Request body (multipart)

| Field  | Type | Required | Description                                                                                                                                           |
| ------ | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | file | Yes      | A file of the report: a PDF, or a PNG, JPEG, GIF, WebP or HEIC/HEIF image. Repeat the part, up to 20 times, to send the pages of one report in order. |

The form field name is `file` (singular) for every part. Each part needs a filename, which curl's `-F "file=@..."` sends for you.

Terra identifies each file's type from its contents, not from its name or declared `Content-Type`. A photo saved as `image.jpg` that is really a HEIC is read as a HEIC.

### Limits

| Limit            | Value                                                                       |
| ---------------- | --------------------------------------------------------------------------- |
| Files per upload | 20, the pages of one report                                                 |
| File size        | 20 MB per file                                                              |
| Upload size      | 50 MB in total                                                              |
| PDF size         | 22.5 MB of PDF in total per upload                                          |
| Image size       | 64 megapixels for HEIC, HEIF, GIF and WebP; 256 megapixels for JPEG and PNG |

An upload over the file, upload or PDF size limit is refused with `413`. An image over its pixel limit is accepted, and the report then fails with `file_too_large`. A report whose files together are more than can be read as one report fails the same way. See [Error Codes](https://docs.tryterra.co/lab-reports/webhook-payload.md#error-codes).

{% hint style="info" %}
**One upload is one report.** Every file in an upload is read as a page of the same report and produces one session. Upload separate reports separately.
{% endhint %}

Files are stored exactly as uploaded. A HEIC photo keeps its EXIF metadata, including GPS location. Strip location data on the device before uploading if you do not want it stored.

### Example

```bash
curl -X POST "https://access.tryterra.co/api/v2/reports?reference_id=patient_456" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/report.pdf"
```

A report photographed page by page, sent as one upload:

```bash
curl -X POST "https://access.tryterra.co/api/v2/reports?reference_id=patient_456" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/page-1.heic" \
  -F "file=@/path/to/page-2.heic" \
  -F "file=@/path/to/page-3.heic"
```

### Response: 202 Accepted

```json
{
  "upload_id": "upl_4a2b8c1d",
  "current_status": "processing"
}
```

{% hint style="info" %}
The upload returns an `upload_id`, not a `session_id`. Learn the `session_id` from the webhook event, or list it with `GET /v2/reports?upload_id=upl_4a2b8c1d`. Every session and webhook event carries its `upload_id`. `session_id` is the per-report identifier you use for `GET /v2/reports/{session_id}`.

The list is eventually consistent: immediately after upload the sessions may not all exist yet, so a `GET ?upload_id=…` right after the `202` can return an empty or partial list. Webhook events are the reliable signal that a report finished.
{% endhint %}

### Error responses

| Status | `code`                      | Description                                                                          |
| ------ | --------------------------- | ------------------------------------------------------------------------------------ |
| 400    | `validation_failed`         | No `file` part, an empty file, a part without a filename, or a malformed form        |
| 400    | `unsupported_file_type`     | A file is not a PDF or a supported image. `detail` names the type its contents show. |
| 400    | `too_many_files`            | More than 20 files                                                                   |
| 401    |                             | Invalid or missing `dev-id` / `x-api-key`                                            |
| 403    | `entitlement_required`      | Lab Reports is not enabled for your account                                          |
| 413    | `payload_too_large`         | A file over 20 MB, an upload over 50 MB, or more than 22.5 MB of PDF                 |
| 500    |                             | Internal server error                                                                |
| 503    | `authorization_unavailable` | Access could not be checked. Retry shortly.                                          |

***

## List sessions

<mark style="color:blue;">`GET`</mark> `/v2/reports`

List lab report sessions for your account, newest first, with optional filters. List items carry the summary fields only, without `results` or `panels`.

The response shape depends on the [API version](#versioning) the request is served in.

### Query parameters

| Name               | Type    | Required | Description                                                                                              |
| ------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `limit`            | integer | No       | Page size. Defaults to 50. A value above 200 is served as 200. From version `2026-10-21`.                |
| `cursor`           | string  | No       | The previous page's `next_cursor`. From version `2026-10-21`.                                            |
| `reference_id`     | string  | No       | Filter by your external reference ID                                                                     |
| `upload_id`        | string  | No       | Filter by the upload handle                                                                              |
| `report_type`      | string  | No       | Return only sessions of this kind: `lab` or `dexa`. Omit for both. Any other value is rejected with 400. |
| `report_date_from` | string  | No       | Lab report date lower bound (ISO-8601 `YYYY-MM-DD`)                                                      |
| `report_date_to`   | string  | No       | Lab report date upper bound (ISO-8601 `YYYY-MM-DD`)                                                      |
| `uploaded_at_from` | string  | No       | Upload date lower bound (ISO-8601 `YYYY-MM-DD`)                                                          |
| `uploaded_at_to`   | string  | No       | Upload date upper bound (ISO-8601 `YYYY-MM-DD`)                                                          |

All date filters are inclusive and can be combined. For example, you can query "reports from January uploaded this week" by setting both `report_date_from`/`report_date_to` and `uploaded_at_from`/`uploaded_at_to`.

### Example

```bash
curl "https://access.tryterra.co/api/v2/reports?reference_id=patient_456&uploaded_at_from=2026-03-01" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Terra-Version: 2026-10-21"
```

### Response: 200 OK (version `2026-10-21`)

```json
{
  "data": [
    {
      "session_id": "297405620317847552",
      "upload_id": "upl_4a2b8c1d",
      "reference_id": "patient_456",
      "report_type": "lab",
      "current_status": "sent",
      "report_date": "2026-03-15",
      "uploaded_at": "2026-03-28T14:22:10Z",
      "updated_at": "2026-03-28T14:23:45Z"
    }
  ],
  "has_more": true,
  "next_cursor": "MTc3NDcwODEzMDAwMDAwMHwyOTc0MDU2MjAzMTc4NDc1NTJ8..."
}
```

| Field         | Type      | Description                                                        |
| ------------- | --------- | ------------------------------------------------------------------ |
| `data`        | object\[] | This page's sessions                                               |
| `has_more`    | boolean   | Whether another page follows                                       |
| `next_cursor` | string?   | Pass it as `cursor` to get the next page. `null` on the last page. |

To get the next page, repeat the request with the same filters and add `cursor`. A cursor is tied to the filters it was issued for: sending it with different filters returns `400` with `code` `validation_failed`. Treat the cursor as opaque.

```python
import requests

url = "https://access.tryterra.co/api/v2/reports"
headers = {
    "dev-id": DEV_ID,
    "x-api-key": API_KEY,
    "X-Terra-Version": "2026-10-21",
}
params = {"reference_id": "patient_456", "limit": 100}

sessions = []
while True:
    page = requests.get(url, headers=headers, params=params).json()
    sessions.extend(page["data"])
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]
```

### Response: 200 OK (version `2026-03-24`)

Up to 500 sessions in `sessions`, newest first, with no pagination. `limit` and `cursor` are ignored. Use the filters to narrow the list.

```json
{
  "sessions": [
    {
      "session_id": "297405620317847552",
      "upload_id": "upl_4a2b8c1d",
      "reference_id": "patient_456",
      "report_type": "lab",
      "current_status": "sent",
      "report_date": "2026-03-15",
      "uploaded_at": "2026-03-28T14:22:10Z",
      "updated_at": "2026-03-28T14:23:45Z"
    }
  ]
}
```

### Error responses

| Status | `code`                                             | Description                                                                     |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------------- |
| 400    |                                                    | An invalid `report_type` or date filter                                         |
| 400    | `validation_failed`                                | An invalid `limit`, a malformed cursor, or a cursor sent with different filters |
| 400    | `invalid_api_version`                              | `X-Terra-Version` is not a date, or is in the future                            |
| 401    |                                                    | Invalid or missing authentication                                               |
| 503    | `authorization_unavailable`, `service_unavailable` | Temporarily unavailable. Retry.                                                 |

***

## Retrieve a session

<mark style="color:blue;">`GET`</mark> `/v2/reports/{session_id}`

Retrieve the report: metadata, results, reference ranges, and status history. This response is **immutable and cacheable**. It does not include presigned file URLs (which expire) or per-destination delivery state (which changes). Fetch those from the sub-resources below.

### Path parameters

| Name         | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `session_id` | string | Yes      | The session's snowflake ID |

### Example

```bash
curl "https://access.tryterra.co/api/v2/reports/297405620317847552" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response: 200 OK

See the [Quickstart](https://docs.tryterra.co/lab-reports/quickstart.md) page for a complete example response. The session object is returned directly at the top level. Key fields include:

* `session_id`: Snowflake ID (string)
* `upload_id`: The upload this report came from (string)
* `reference_id`: Your external reference (omitted if not set)
* `current_status`: Current status as a clean lowercase string (e.g. `"sent"`, `"processing"`)
* `report_type`: Report type (e.g. `"lab"`)
* `report_date`: Date from the lab report (YYYY-MM-DD string, omitted if not extracted)
* `report_time`: Time from the lab report (HH:MM 24-hour, omitted if not extracted)
* `collection_date`: Specimen collection date (YYYY-MM-DD string, omitted if not extracted)
* `collection_time`: Specimen collection time (HH:MM 24-hour, omitted if not extracted)
* `uploaded_at`: Session creation timestamp (ISO-8601)
* `updated_at`: Last update timestamp (ISO-8601)
* `report_locale`: Locale of the report (e.g. `"ja-JP"`, `"pt-BR"`)
* `lab_name`: Name of the laboratory
* `patient_sex`: Clean lowercase string (e.g. `"male"`, `"female"`, omitted if unspecified)
* `patient_age_at_collection`: Patient age in years (integer, omitted if unknown)
* `report_notes`: Free-text notes extracted from the report
* `error`: Why the report failed, as `{ code, message, retriable, document_class? }`. The same object as the [failure webhook](https://docs.tryterra.co/lab-reports/webhook-payload.md#failure-webhook). Present only while `current_status` is `failed`.
* `status_history[]`: Array of `{ status, timestamp, note }` entries
* `results_count`: Number of biomarker results
* `file_count`: Number of uploaded files
* `input_bytes`: Size of uploaded file(s) in bytes
* `output_bytes`: Size of output data in bytes
* `panels[]`: Report-level panels that results reference by `panel_id` (omitted if the report has no panel grouping)
* `results[]`: Array of biomarker results, each grouped into `source` / `biomarker` / `measurement` / `interpretation` layers (see [Core concepts](https://docs.tryterra.co/lab-reports/core-concepts.md) for field specs)

{% hint style="info" %}
`client_id` is intentionally omitted from the API response. The API authenticates by client identity, so echoing it back is redundant.
{% endhint %}

### Error responses

| Code | Description                       |
| ---- | --------------------------------- |
| 401  | Invalid or missing authentication |
| 404  | Session not found                 |
| 500  | Internal server error             |

***

## List deliveries

<mark style="color:blue;">`GET`</mark> `/v2/reports/{session_id}/deliveries`

The per-destination delivery state for a report. A report is fanned out to every destination that has opted in to lab reports (see [Delivery destinations](https://docs.tryterra.co/lab-reports/core-concepts.md#delivery-destinations)), and each is tracked independently, so a failure to one never hides that the report reached the others. This is also why a session can be `partially_sent`. Delivery state is mutable (pending → delivered/failed/retrying), so it lives here rather than on the cacheable session.

### Response: 200 OK

```json
{
  "deliveries": [
    { "destination_id": "12", "destination_type": "webhook", "status": "delivered", "attempt_count": 0 },
    { "destination_id": "15", "destination_type": "s3", "status": "failed", "attempt_count": 3, "last_error": "access denied" }
  ]
}
```

| Field              | Type    | Description                                                  |
| ------------------ | ------- | ------------------------------------------------------------ |
| `destination_id`   | string  | The destination's ID                                         |
| `destination_type` | string  | The destination's type (e.g. `webhook`, `s3`)                |
| `status`           | string  | `pending`, `delivered`, or `failed`                          |
| `attempt_count`    | integer | Retry count: `0` on the first attempt, incremented per retry |
| `last_error`       | string? | Most recent delivery error (omitted when delivered)          |

***

## List files

<mark style="color:blue;">`GET`</mark> `/v2/reports/{session_id}/files`

The uploaded input files and the report thumbnail, with **freshly minted** presigned download URLs. URLs are issued on demand because they expire. They are not embedded in the cacheable session or the webhook.

### Response: 200 OK

```json
{
  "files": [
    { "filename": "000.heic", "presigned_url": "https://storage.googleapis.com/...signed-url...", "content_type": "image/heic" },
    { "filename": "001.heic", "presigned_url": "https://storage.googleapis.com/...signed-url...", "content_type": "image/heic" }
  ],
  "thumbnail": { "filename": "thumbnail.png", "presigned_url": "https://storage.googleapis.com/...signed-thumbnail-url..." },
  "expires_at": "2026-03-28T15:22:10Z"
}
```

`files` lists the uploaded files in upload order, exactly as they were uploaded. Each is named by its position, not by the name it was sent with, and `content_type` is the type Terra detected from its contents.

`expires_at` applies to every URL in the response. URLs last at most one hour. Fetch the endpoint again to mint fresh URLs.

***

## List artifacts

<mark style="color:blue;">`GET`</mark> `/v2/reports/{session_id}/artifacts`

Intermediate processing artifacts, with freshly minted presigned URLs. **Privileged keys only**. Standard keys receive a 404. Same response shape as `/files` (an `artifacts[]` array plus `expires_at`).

***

## Reprocess a session

<mark style="color:orange;">`POST`</mark> `/v2/reports/{session_id}/reprocess`

Re-run extraction and standardization on an existing session, from the files it was uploaded with. Use it to retry a failed report whose `error.retriable` is `true`, or to pick up improvements in processing. When `retriable` is `false`, reprocessing the same files fails the same way: upload a new file instead.

### Path parameters

| Name         | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `session_id` | string | Yes      | The session's snowflake ID |

### Example

```bash
curl -X POST "https://access.tryterra.co/api/v2/reports/297405620317847552/reprocess" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response: 202 Accepted

```json
{
  "session_id": "297405620317847552",
  "current_status": "processing"
}
```

Includes a `Location` header pointing to the session. The session re-enters the `processing -> ... -> sent` flow. A reprocess is a new run, so it ends in a new webhook event, `lab_report.completed` or `lab_report.failed`, with a new `event_id`.

Only finished sessions can be reprocessed: `sent`, `partially_sent`, `delivery_failed` or `failed`. Each session can be reprocessed up to 3 times. A report that was already billed is not billed again.

### Error responses

| Status | `code`                    | Description                                       |
| ------ | ------------------------- | ------------------------------------------------- |
| 401    |                           | Invalid or missing authentication                 |
| 403    | `entitlement_required`    | Lab Reports is not enabled for your account       |
| 404    |                           | Session not found                                 |
| 409    |                           | The session is still processing, or was cancelled |
| 409    | `reprocess_limit_reached` | The session has been reprocessed 3 times already  |
| 500    |                           | Internal server error                             |

***

## Delete a session

<mark style="color:red;">`DELETE`</mark> `/v2/reports/{session_id}`

Delete a report. It is removed from the API immediately: every endpoint returns `404` for it afterwards, and it is no longer listed. Delete works even if your Lab Reports access has ended.

What happens to the data:

* **Files, results and the copies Terra keeps** are erased from active systems within 30 days. The target is 24 hours.
* **Backup copies** are kept only for disaster recovery, and expire within 10 days.
* **File URLs** already issued by [List Files](#list-files) keep working until they expire, at most one hour after they were issued.
* **Copies delivered to your destinations** are yours. Delete them from your webhook store, bucket or database yourself.

Reports you do not delete are kept until you delete them or close your account.

### Path parameters

| Name         | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `session_id` | string | Yes      | The session's snowflake ID |

### Example

```bash
curl -X DELETE "https://access.tryterra.co/api/v2/reports/297405620317847552" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response: 204 No Content

No response body.

### Error responses

| Code | Description                           |
| ---- | ------------------------------------- |
| 401  | Invalid or missing authentication     |
| 404  | Session not found, or already deleted |
| 500  | Internal server error                 |
