terra-lab-reports

Convert clinical lab report PDFs and images into standardized biomarker data via the Terra Lab Reports API.

Updated Sep 2, 2026
One-click install
npx skills add https://github.com/tryterra/agent-skills --skill terra-lab-reports-tryterra
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: terra-lab-reports
Source: https://github.com/tryterra/agent-skills/tree/main/skills/terra-lab-reports
Command: npx skills add https://github.com/tryterra/agent-skills --skill terra-lab-reports-tryterra

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Integrating clinical lab report parsing is error-prone: uploads return upload IDs instead of session IDs, webhooks redeliver and reprocess with confusing idempotency semantics, unmatched biomarkers arrive with null keys, and reference ranges vary by patient demographics. This Skill encodes the correct handling for each of these pitfalls so agents generate working Terra Lab Reports integrations. ## Core Features & Use Cases - Async Lifecycle Guidance: Covers the upload/standardize/deliver pipeline, the lab_report.completed / lab_report.failed event envelope, and polling fallbacks with rate-limit-safe intervals. - Layered Data Model Reference: Documents the source / biomarker / measurement / interpretation / reference_ranges result structure, UCUM unit codes, LOINC mappings, and open enum handling. - Best-Practice Rules: Seven incorrect/correct code rules covering webhook deduplication on event_id, null biomarker.key fallback, demographic range filtering, snowflake ID string storage, and UTF-8 parsing. - Use Case: Build a webhook handler that dedupes redeliveries on event_id, stores snowflake session IDs as strings, keeps unmatched biomarkers with a source.name fallback, and filters reference ranges by patient sex and age. ## Quick Start Ask your agent to write a webhook handler for Terra lab report results that deduplicates on event_id and stores the parsed biomarker results in a database.

Frequently Asked Questions about terra-lab-reports

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I parse lab report PDFs into structured biomarker data?

Upload one PDF or image per request to POST /v2/lab-reports with the multipart field named file. The API returns a 202 with an upload_id, then processes asynchronously, delivering results via a lab_report.completed webhook or through GET /v2/lab-reports/{session_id} once the session reaches standardized.

How do I handle Terra lab report webhooks idempotently?

Deduplicate on the envelope's event_id, which stays identical across redeliveries of the same payload. A reprocess mints a new event_id with the same session_id, so deduping on session_id would wrongly drop reprocessed results. Branch on the type field for completed versus failed events.

Why is biomarker.key null in some lab report results?

A null biomarker.key means fuzzy matching against the 4,000+ biomarker dataset found no confident match, common for proprietary lab names or uncommon assays. It is the sole no-match signal; never discard these results, and fall back to source.name for display.

Does the upload response return a session_id?

No, the 202 upload response returns an upload_id with current_status processing, because one upload can fan out to several sessions. Learn session IDs from the webhook's data.session_id or by querying GET /v2/lab-reports?upload_id=...

How do I interpret reference ranges that vary by patient demographics?

Use interpretation.applied_range first when present, since Terra already resolved it against patient context. When null, filter reference_ranges yourself by matching each range's context fields (sex, age bounds, pregnancy status) to the patient, treating absent context fields as applying to all.

Why do session IDs lose precision in JavaScript?

Session IDs are snowflake int64 values serialized as JSON strings because they exceed JavaScript's safe integer range. Coercing them to Number silently corrupts low-order digits, so keep them as strings in memory, database columns, and URLs.