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-Versionheader. 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
descriptionis 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
biomarkershas asummary, a rich textdescriptionand asource_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 arenullwhen 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'svariant_idaccepts a string or a number.Orders:
currencyis the ISO 4217 code (USD,EUR,GBP) instead of the numeric code (840,978,826).Orders:
item_statusis 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 /resultsandGET /webhook-deliveriesreturndata,has_moreandnext_cursor, all always present. Previously the items were underorders,resultsordeliveries, with nohas_more, andnext_cursorwas omitted on the last page. Catalogue routes andGET /labsare unpaginated and still return a bare array.Idempotency: replaying a request with the same
Idempotency-Keyand body returns200instead of201.Idempotency: an
Idempotency-Keylonger than 255 characters returns400with codeidempotency_key_too_long.Errors:
typeURIs arehttps://docs.tryterra.co/vantage-api/errors/<slug>instead ofhttps://api.terra-diagnostics.com/errors/<slug>.Webhook payloads are unchanged.
Non-breaking
2026-10-29
Errors: most credential refusals are
application/problem+jsonwith acode, whatever the version:unauthorized(401) for a missing, invalid, expired or revoked key or token,scope_missingoraudience_restricted(403), andauthorization_unavailable(503, retry later). The status codes are unchanged. A few keep the previous format, so choose the schema byContent-Type. Errors
2026-10-28
Orders:
GET /ordersacceptsorder_id,variant_id,recipient_nameandrecipient_emailfilters.statustakes several statuses.Results:
GET /resultsacceptsvariant_idandclient_order_reference_idfilters.statusandorder_idtake several values.Lists: on
GET /ordersandGET /results, a list filter takes up to 100 values, repeated or joined with commas, and matches any of them.order=ascreturns the oldest first. Send the sameorderand filters with every page's cursor.Webhooks: a webhook URL with credentials in it, such as
https://user:[email protected], returns400.
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
404for one, and ordering one returns403. 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 byX-Terra-Ordering-Timestamp.Webhooks: in
GET /webhook-deliveries,attemptscounts every HTTP attempt across all retries, and a dead-lettered delivery carries its last status code, ornullwhen the last attempt got no response.Webhooks: creating an order sends
order.status_changedfororder.payment_processing, and fororder.payment_completewhen payment is taken as the order is created. Previously these two statuses could only be read from the order.
2026-10-09
Results:
results_statuscan beresults.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_phlebotomyorclinic, when the sample is taken at a clinician visit. It is omitted for self-collected kits.Catalogue:
collection_methodcan beautomatic_capillary, a self-collected capillary sample from a push-button device.Orders: order items have a
collection_visitwithtype,status(booking,requestedorbooking_failed) andscheduling_url.Orders: a home-visit item needs an
AT_HOMEorder with a valid phone number, or the request returns400. A clinic-visit item is ordered asGO_TO_LABwith ashipping_address, and can have the statusawaiting_clinic_invite.Orders:
POST /orderscan return422with codeorder_not_approvedfor a test that needs clinician approval. The sameIdempotency-Keyand body can be retried.Orders: kit activation returns
409while another activation of the same kit is in progress. Retry shortly.Webhooks:
results_readycarriesamended: truewhen it is a corrected release of a result already delivered. Fetch the result again.
2026-10-02
Orders:
GET /ordersacceptsuntilandclient_order_reference_idfilters.Results:
GET /resultsacceptsis_acknowledged,order_id,sinceanduntilfilters.Lists: a
limitabove 100 is treated as 100 instead of returning400. An exactly full last page no longer returns anext_cursor.Idempotency: a request that failed without creating anything, such as a
402or a403catalogue rejection, can be retried with the sameIdempotency-Keyand body.Payments:
402responses carry acode:payment_method_missing,card_declinedorpayment_authorization_failed.Webhooks:
POST /webhook-events/resendresends a delivered event for up to 30 days, andPOST /webhook-events/generatesends a test event marked"test": true. Both need thevantage:writescope 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-Idheader. Include it when you contact support.Fixed: in result FHIR bundles, every reference now resolves inside the bundle, and each bundle includes an
Organizationentry.
2026-10-01
Breaking
Catalogue variants carry typed fields. See Core concepts.
Catalogue: variant
variant_nameis renamed toname.Catalogue: variant
descriptive_attrs_overrideis replaced bydescription.Catalogue: variant
variant_defining_attrsis replaced byturnaround_daysandcollection_method.Catalogue: variant
variant_availabilityis replaced byavailability, a string:unknown,in_stockorout_of_stock.Catalogue: variant
requires_activationis added.Catalogue: product
model_descriptive_attrsis removed. Its collection method is nowcollection_methodon each variant.Catalogue: product
availabilityis a string instead of an integer.Webhook payloads are unchanged.
Non-breaking
2026-10-01
Catalogue: product and variant
imagesare 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-Versionheader picks the version a request is served in. Every response and webhook delivery carries it, and an unknown value returns400with codeinvalid_api_version.
2026-09-27
The first version. Catalogue variants carry attribute bags and integer availability.
Last updated
Was this helpful?