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

Changelog

Every Vantage API version, newest first, with its breaking changes and the non-breaking changes shipped while it was the latest.

Each Vantage API version is named by a date. Under each version:

  • Breaking changes apply only once your account is pinned to that version, or when you send it in the X-Terra-Version header. See Versioning for how to upgrade.

  • Non-breaking changes reach every version as soon as they ship, with no upgrade needed. They are listed by the date they shipped, under the version that was the latest at the time.

Enums can gain new values without a new version. Treat a value you don't recognise as described in the API reference.

2026-10-29 (latest)

Breaking

  • Catalogue: a product's description is a rich text document, a JSON tree with a node for every Markdown construct, instead of a string. A product without a description has an empty document. Variant and product type descriptions are still strings.

Non-breaking

2026-10-29

  • Catalogue: each entry in a variant's biomarkers has a summary, a rich text description and a source_url: a plain-language explanation of the biomarker, copied from the U.S. National Cancer Institute or MedlinePlus, and the page it came from. All three are null when no source explains the biomarker. Every API version serves them. See Core concepts.

2026-10-15

Breaking

  • IDs: product, variant, image and product type IDs are decimal strings, such as "42", instead of numbers. A request's variant_id accepts a string or a number.

  • Orders: currency is the ISO 4217 code (USD, EUR, GBP) instead of the numeric code (840, 978, 826).

  • Orders: item_status is a string (pending_shipment, in_transit, delivery_attempted, delivered) instead of an integer. It is omitted until the kit has a shipping status.

  • Lists: GET /orders, GET /results and GET /webhook-deliveries return data, has_more and next_cursor, all always present. Previously the items were under orders, results or deliveries, with no has_more, and next_cursor was omitted on the last page. Catalogue routes and GET /labs are unpaginated and still return a bare array.

  • Idempotency: replaying a request with the same Idempotency-Key and body returns 200 instead of 201.

  • Idempotency: an Idempotency-Key longer than 255 characters returns 400 with code idempotency_key_too_long.

  • Errors: type URIs are https://docs.tryterra.co/vantage-api/errors/<slug> instead of https://api.terra-diagnostics.com/errors/<slug>.

  • Webhook payloads are unchanged.

Non-breaking

2026-10-29

  • Errors: most credential refusals are application/problem+json with a code, whatever the version: unauthorized (401) for a missing, invalid, expired or revoked key or token, scope_missing or audience_restricted (403), and authorization_unavailable (503, retry later). The status codes are unchanged. A few keep the previous format, so choose the schema by Content-Type. Errors

2026-10-28

  • Orders: GET /orders accepts order_id, variant_id, recipient_name and recipient_email filters. status takes several statuses.

  • Results: GET /results accepts variant_id and client_order_reference_id filters. status and order_id take several values.

  • Lists: on GET /orders and GET /results, a list filter takes up to 100 values, repeated or joined with commas, and matches any of them. order=asc returns the oldest first. Send the same order and filters with every page's cursor.

  • Webhooks: a webhook URL with credentials in it, such as https://user:[email protected], returns 400.

2026-10-27

  • Catalogue: an environment can be limited to the UK or US market. Once its markets are set, catalog reads leave out products not sold in them, the variants route returns 404 for one, and ordering one returns 403. Until then it sees every market. See Markets.

  • Webhooks: every event is recorded when it happens. One that could not be sent straight away is sent later under the same event_id, so it can arrive after a newer event for the same order: order them by X-Terra-Ordering-Timestamp.

  • Webhooks: in GET /webhook-deliveries, attempts counts every HTTP attempt across all retries, and a dead-lettered delivery carries its last status code, or null when the last attempt got no response.

  • Webhooks: creating an order sends order.status_changed for order.payment_processing, and for order.payment_complete when payment is taken as the order is created. Previously these two statuses could only be read from the order.

2026-10-09

  • Results: results_status can be results.not_applicable, for a product that never produces a result. It never changes, and no results webhook is sent for it.

2026-10-08

  • Catalogue: variants have a collection_visit, home_phlebotomy or clinic, when the sample is taken at a clinician visit. It is omitted for self-collected kits.

  • Catalogue: collection_method can be automatic_capillary, a self-collected capillary sample from a push-button device.

  • Orders: order items have a collection_visit with type, status (booking, requested or booking_failed) and scheduling_url.

  • Orders: a home-visit item needs an AT_HOME order with a valid phone number, or the request returns 400. A clinic-visit item is ordered as GO_TO_LAB with a shipping_address, and can have the status awaiting_clinic_invite.

  • Orders: POST /orders can return 422 with code order_not_approved for a test that needs clinician approval. The same Idempotency-Key and body can be retried.

  • Orders: kit activation returns 409 while another activation of the same kit is in progress. Retry shortly.

  • Webhooks: results_ready carries amended: true when it is a corrected release of a result already delivered. Fetch the result again.

2026-10-02

  • Orders: GET /orders accepts until and client_order_reference_id filters.

  • Results: GET /results accepts is_acknowledged, order_id, since and until filters.

  • Lists: a limit above 100 is treated as 100 instead of returning 400. An exactly full last page no longer returns a next_cursor.

  • Idempotency: a request that failed without creating anything, such as a 402 or a 403 catalogue rejection, can be retried with the same Idempotency-Key and body.

  • Payments: 402 responses carry a code: payment_method_missing, card_declined or payment_authorization_failed.

  • Webhooks: POST /webhook-events/resend resends a delivered event for up to 30 days, and POST /webhook-events/generate sends a test event marked "test": true. Both need the vantage:write scope and accept ?dry_run=true.

  • Webhooks: every delivery carries X-Terra-Ordering-Timestamp, the Unix time in milliseconds the event was emitted. It is the same on every retry.

  • All responses: carry an X-Request-Id header. Include it when you contact support.

  • Fixed: in result FHIR bundles, every reference now resolves inside the bundle, and each bundle includes an Organization entry.

2026-10-01

Breaking

Catalogue variants carry typed fields. See Core concepts.

  • Catalogue: variant variant_name is renamed to name.

  • Catalogue: variant descriptive_attrs_override is replaced by description.

  • Catalogue: variant variant_defining_attrs is replaced by turnaround_days and collection_method.

  • Catalogue: variant variant_availability is replaced by availability, a string: unknown, in_stock or out_of_stock.

  • Catalogue: variant requires_activation is added.

  • Catalogue: product model_descriptive_attrs is removed. Its collection method is now collection_method on each variant.

  • Catalogue: product availability is a string instead of an integer.

  • Webhook payloads are unchanged.

Non-breaking

2026-10-01

  • Catalogue: product and variant images are populated.

2026-09-29

  • Versioning: your account is pinned to the latest version on its first request, and you can change the pin in the dashboard.

2026-09-28

  • Versioning: the X-Terra-Version header picks the version a request is served in. Every response and webhook delivery carries it, and an unknown value returns 400 with code invalid_api_version.

2026-09-27

The first version. Catalogue variants carry attribute bags and integer availability.

Last updated

Was this helpful?