For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

Errors use the RFC 7807 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.

{
  "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 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.

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:

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. You can move the pin back to 2026-03-24 the same way. A pin cannot be removed.


Upload a lab report

POST /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.

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.

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

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

Response: 202 Accepted

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.

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

GET /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 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

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

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.

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.

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

GET /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

Response: 200 OK

See the Quickstart 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. 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 for field specs)

client_id is intentionally omitted from the API response. The API authenticates by client identity, so echoing it back is redundant.

Error responses

Code
Description

401

Invalid or missing authentication

404

Session not found

500

Internal server error


List deliveries

GET /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), 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

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

GET /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

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

GET /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

POST /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

Response: 202 Accepted

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

DELETE /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 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

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

Last updated

Was this helpful?