> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/vantage-api/products.md).

# Products

## List all product types

> Returns all available diagnostic test categories (e.g., Blood Tests, DNA Tests)

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.09.16"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"schemas":{"ProductType":{"type":"object","properties":{"description":{"type":"string"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/api/v1/products":{"get":{"summary":"List all product types","tags":["products"],"description":"Returns all available diagnostic test categories (e.g., Blood Tests, DNA Tests)","responses":{"200":{"description":"Successfully retrieved product types","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Set catalog selection

> Curate which products your own catalog reads return. Full-set write: listed products become enabled, every other product disabled. With no selection saved, everything is enabled; products added to the global catalog after your last save default to enabled until you save again. Disabled products are excluded from catalog reads and cannot be ordered (403).

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.09.16"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"schemas":{"UpdateCatalogSelectionRequest":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"Products to enable; everything else is disabled.","items":{"type":"string"}}}},"UpdateCatalogSelectionResponse":{"type":"object","required":["enabled_count"],"properties":{"enabled_count":{"type":"integer"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/api/v1/products/selection":{"put":{"summary":"Set catalog selection","tags":["products"],"description":"Curate which products your own catalog reads return. Full-set write: listed products become enabled, every other product disabled. With no selection saved, everything is enabled; products added to the global catalog after your last save default to enabled until you save again. Disabled products are excluded from catalog reads and cannot be ordered (403).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogSelectionRequest"}}}},"responses":{"200":{"description":"Selection saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogSelectionResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Get products by type ID

> Returns all products within a specific product type category

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.09.16"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"schemas":{"Product":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Present only on ?show_all=true — the caller's per-product curation flag."},"availability":{"$ref":"#/components/schemas/AvailabilityStatus"},"base_price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"description":{"type":"string"},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"model_descriptive_attrs":{"type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string"},"product_type_id":{"type":"integer","format":"int64"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}},"AvailabilityStatus":{"type":"integer","format":"int32","enum":[0,1,2]},"Currency":{"type":"integer","format":"int32","enum":[0,840,978,826]},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"width":{"type":"integer","format":"int32"}}},"ProductVariant":{"type":"object","properties":{"available_collection_types":{"type":"array","items":{"type":"string"}},"supported_ship_to_countries":{"type":"array","description":"ISO-3166 alpha-2 codes this test can be ordered in (AT_HOME shipping destination; for GO_TO_LAB, the requested lab country). Gate your address form on it - orders outside these countries are rejected with an unsupported_ship_to_country field error.","items":{"type":"string"}},"currency":{"type":"integer","format":"int32"},"descriptive_attrs_override":{"type":"object","additionalProperties":{}},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"price_cents":{"type":"integer","format":"int32"},"product_id":{"type":"integer","format":"int64"},"product_type_id":{"type":"integer","format":"int64"},"variant_availability":{"type":"integer","format":"int32"},"variant_defining_attrs":{"type":"object","additionalProperties":{}},"variant_name":{"type":"string"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]}}},"paths":{"/api/v1/products/{id}":{"get":{"summary":"Get products by type ID","tags":["products"],"description":"Returns all products within a specific product type category","parameters":[{"name":"show_all","in":"query","required":false,"description":"Return the full catalog with per-product enabled flags (curation view).","schema":{"type":"boolean","default":false}},{"name":"id","in":"path","description":"Product Type ID","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successfully retrieved products. An existing product type with no available products returns an empty array.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"400":{"description":"Invalid product type ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"description":"Product type not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","instance","status","title","type"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Get product variants by product ID

> Returns all available variants/options for a specific diagnostic test product (e.g., different panel sizes, customizations)

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.09.16"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"schemas":{"ProductVariant":{"type":"object","properties":{"available_collection_types":{"type":"array","items":{"type":"string"}},"supported_ship_to_countries":{"type":"array","description":"ISO-3166 alpha-2 codes this test can be ordered in (AT_HOME shipping destination; for GO_TO_LAB, the requested lab country). Gate your address form on it - orders outside these countries are rejected with an unsupported_ship_to_country field error.","items":{"type":"string"}},"currency":{"type":"integer","format":"int32"},"descriptive_attrs_override":{"type":"object","additionalProperties":{}},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"price_cents":{"type":"integer","format":"int32"},"product_id":{"type":"integer","format":"int64"},"product_type_id":{"type":"integer","format":"int64"},"variant_availability":{"type":"integer","format":"int32"},"variant_defining_attrs":{"type":"object","additionalProperties":{}},"variant_name":{"type":"string"}}},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"width":{"type":"integer","format":"int32"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]}}},"paths":{"/api/v1/products/{id}/variants":{"get":{"summary":"Get product variants by product ID","tags":["products"],"description":"Returns all available variants/options for a specific diagnostic test product (e.g., different panel sizes, customizations)","parameters":[{"name":"show_all","in":"query","required":false,"description":"Include variants of catalog-disabled products (curation view). Disabled products remain non-orderable regardless.","schema":{"type":"boolean","default":false}},{"name":"id","in":"path","description":"Product ID","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successfully retrieved variants","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}}},"400":{"description":"Invalid product ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"description":"No product variants were found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","instance","status","title","type"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```