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

Quickstart

Upload a lab report, check status, and retrieve structured biomarker data in three steps.

Prerequisites

  • A Terra developer account with a dev-id and x-api-key (get these from the Terra Dashboard)

  • A webhook destination configured in the dashboard (optional but recommended)

  • A lab report file to upload (PDF, PNG, JPEG, GIF, WebP, or HEIC)

Upload a report

curl -X POST "https://access.tryterra.co/api/v2/reports" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/blood-test.pdf"

You can optionally tag the upload with your own identifier:

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/blood-test.pdf"

If the report was photographed page by page, send every page in the same upload, in page order. One upload is one report.

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.jpg" \
  -F "file=@/path/to/page-2.jpg"

Response (202 Accepted):

The upload returns an upload_id, the durable handle for this upload. The session_id(s) are learned from the webhook events or via GET /v2/reports?upload_id=upl_4a2b8c1d. Both IDs are strings; store snowflake session_ids as strings to avoid JavaScript integer precision issues.

Wait for processing

The report moves through several statuses before results are ready:

Option A: Webhook (recommended): Terra delivers a lab_report.completed event, with the report under data, to your configured webhook endpoint when processing finishes. If the report can't be processed, you get a lab_report.failed event with the reason instead. No polling needed. See Failure webhook.

Lab reports can be delivered to any destination you've configured, not just webhooks, but also cloud storage, message queues, and databases. Delivery is opt-in per destination: add "lab_report" to a destination's destination_event_types to start receiving reports there. See Delivery destinations.

Option B: Poll the session: Check status by retrieving the session:

Processing typically takes 3 to 5 minutes, depending on report complexity and load.

terminalCheck a lab report session and its delivery outcomes

Retrieve results

Once the session status is sent (or standardized or later), the results are available:

Response (200 OK):

What's next?

Last updated

Was this helpful?