API ReferenceReference

API reference

The versioned Partner API surface, its envelopes and its machine-readable description.

Machine-readable description

The Partner API is described by an OpenAPI 3.1 document generated from the same route and scope contracts the server enforces, served at /api/public/partner-openapi. The production server entry appears only when a production base URL is genuinely configured.

Base path: /api/public/partner/v1. Every endpoint page in this section is generated from that same contract, so the reference cannot drift from the implementation.

Envelopes

A successful response returns data plus a request_id, and adds next_cursor where a collection is cursor-paged. A failure returns error with code, message and optional details, plus the same request_id.

json

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not carry the required scope.",
    "details": ["orders:write"]
  },
  "request_id": "req_8f14e45fceea4c2b"
}

Scopes

programs:read
catalog:read
serviceability:read
subjects:write
orders:write
orders:read
orders:cancel
results:read
events:read
webhooks:manage

These are the only scopes that exist. The scope each endpoint requires is stated on its reference page and is the same value the server enforces per request.

Every endpoint

GET/v1/healthVerify credentials and environment

GET/v1/labRetrieve the laboratory capability profile

GET/v1/locationsList externally serviceable collection locations

GET/v1/programsList programs this key may order from

GET/v1/programs/{programId}Retrieve one program

GET/v1/programs/{programId}/catalogList orderable tests in a program

POST/v1/serviceabilityCheck whether a location and test can be fulfilled

PUT/v1/subjects/{externalSubjectId}Register or update your opaque subject reference

GET/v1/programs/{programId}/requirementsDiscover what an order must carry

GET/v1/sandbox/order-fixturesList synthetic order-request fixtures

POST/v1/ordersCreate an order

GET/v1/orders/{orderId}Retrieve order status

POST/v1/orders/{orderId}/cancelCancel an order while cancellation is still possible

GET/v1/orders/{orderId}/resultsRetrieve released structured results

GET/v1/orders/{orderId}/results/{resultId}Retrieve one released result version in full

GET/v1/orders/{orderId}/results/{resultId}/reportRetrieve the governed laboratory report for a released result

GET/v1/orders/{orderId}/exceptionsRead canonical specimen, sample and result exceptions

GET/v1/eventsRead the event stream for reconciliation

GET/v1/sandbox/scenariosList deterministic sandbox scenarios

POST/v1/sandbox/orders/{orderId}/simulateAdvance a synthetic sandbox order through a scenario

Authentication for every endpoint is described in Partner API → Authentication.