> 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/admin-api/lab-reports.md).

# Lab Reports

Configure Lab Reports for an environment.

## Get the lab-reports API version pin

> Returns the lab-reports API version this environment's requests get when they send no \`X-Terra-Version\` header, with every supported version, newest first.\
> \
> \- \`pinned\` is null when the environment has no pin, and such requests get the latest version.\
> \- A pin that cannot be read right now is a 503, never null.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"lab-reports","summary":"Lab Reports","description":"Configure Lab Reports for an environment."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["dataconfig:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}},"schemas":{"LabReportsApiVersion":{"type":"object","description":"The environment's pinned lab-reports API version. X-Terra-Version on a request still overrides the pin for that request.","properties":{"pinned":{"type":["string","null"],"description":"The version requests without X-Terra-Version are served. null when the environment has no pin, in which case they are served the latest version."},"latest":{"type":"string","description":"The newest version, which an environment without a pin is served."},"versions":{"type":"array","description":"Every version the pin can be set to, newest first.","items":{"$ref":"#/components/schemas/ApiVersionEntry"}}},"required":["pinned","latest","versions"]},"ApiVersionEntry":{"type":"object","description":"One servable API version of a versioned product and what it changed.","properties":{"version":{"type":"string","description":"The version's date, as sent in X-Terra-Version."},"summary":{"type":"string","description":"What this version changed from the one before it."}},"required":["version","summary"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"InternalError":{"description":"Unexpected server-side failure while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}}},"paths":{"/environments/{dev_id}/lab-reports/api-version":{"get":{"operationId":"getLabReportsApiVersion","tags":["lab-reports"],"summary":"Get the lab-reports API version pin","description":"Returns the lab-reports API version this environment's requests get when they send no `X-Terra-Version` header, with every supported version, newest first.\n\n- `pinned` is null when the environment has no pin, and such requests get the latest version.\n- A pin that cannot be read right now is a 503, never null.","parameters":[{"$ref":"#/components/parameters/DevId"}],"responses":{"200":{"description":"The pin and the supported versions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabReportsApiVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```

## Change the lab-reports API version pin

> Pins the environment's lab-reports API version and returns the same shape as \`GET /environments/{dev\_id}/lab-reports/api-version\`.\
> \
> \- Any supported version can be pinned, older or newer than the current one, and takes effect on the environment's next lab-reports request.\
> \- An \`X-Terra-Version\` header on a request still overrides the pin for that request.\
> \- There is no unpin.\
> \- A version this API does not list is a 400.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"lab-reports","summary":"Lab Reports","description":"Configure Lab Reports for an environment."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["dataconfig:write"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."},"DryRun":{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true the operation commits nothing and answers 200 with a DryRunResult — {dry_run, would, preview} — whatever its live success code is. Operations whose live success is also 200 publish both the live response and DryRunResult in the response schema."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stripe-style idempotency: same key + same body replays the stored response; same key + different body → 409. Mutations only."}},"schemas":{"SetLabReportsApiVersionRequest":{"type":"object","properties":{"version":{"type":"string","description":"The version to pin, one of the versions GET lists. Takes effect on the environment's next request."}},"required":["version"],"additionalProperties":false},"LabReportsApiVersion":{"type":"object","description":"The environment's pinned lab-reports API version. X-Terra-Version on a request still overrides the pin for that request.","properties":{"pinned":{"type":["string","null"],"description":"The version requests without X-Terra-Version are served. null when the environment has no pin, in which case they are served the latest version."},"latest":{"type":"string","description":"The newest version, which an environment without a pin is served."},"versions":{"type":"array","description":"Every version the pin can be set to, newest first.","items":{"$ref":"#/components/schemas/ApiVersionEntry"}}},"required":["pinned","latest","versions"]},"ApiVersionEntry":{"type":"object","description":"One servable API version of a versioned product and what it changed.","properties":{"version":{"type":"string","description":"The version's date, as sent in X-Terra-Version."},"summary":{"type":"string","description":"What this version changed from the one before it."}},"required":["version","summary"]},"DryRunResult":{"type":"object","description":"Returned by any mutating endpoint invoked with ?dry_run=true.","properties":{"dry_run":{"type":"boolean","enum":[true]},"would":{"type":"string","description":"the action that would be taken"},"preview":{"$ref":"#/components/schemas/DryRunPreview"}},"required":["dry_run","would","preview"]},"DryRunPreview":{"type":"object","description":"The representation the live call would return, or for a delete the representation of what\nwould go. A value that cannot exist without committing is omitted rather than invented, and\nthe will_return_* flags below say one is coming.","properties":{"will_return_token":{"type":"boolean","description":"The call would issue a bearer token, returned once by the live call."},"will_return_signing_secret":{"type":"boolean","description":"The call would issue a webhook signing secret, returned once by the live call."},"will_return_api_key":{"type":"boolean","description":"The call would issue an API key, returned once by the live call."},"will_return_authorization_url":{"type":"boolean","description":"The call would return an authorization URL to send the user to."},"will_return_database_password":{"type":"boolean","description":"The call would generate a database password, returned once by the live call."}},"unevaluatedProperties":{}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"InternalError":{"description":"Unexpected server-side failure while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}}},"paths":{"/environments/{dev_id}/lab-reports/api-version":{"put":{"operationId":"setLabReportsApiVersion","tags":["lab-reports"],"summary":"Change the lab-reports API version pin","description":"Pins the environment's lab-reports API version and returns the same shape as `GET /environments/{dev_id}/lab-reports/api-version`.\n\n- Any supported version can be pinned, older or newer than the current one, and takes effect on the environment's next lab-reports request.\n- An `X-Terra-Version` header on a request still overrides the pin for that request.\n- There is no unpin.\n- A version this API does not list is a 400.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetLabReportsApiVersionRequest"}}}},"responses":{"200":{"description":"Updated (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/LabReportsApiVersion"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```
