> 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/documentation-search.md).

# Documentation search

Ask a question in plain language and get an answer from Terra's published documentation.

## Ask a question about Terra and get an answer from the documentation

> Answers a question about Terra from the published documentation and cites the pages the answer drew on.\
> \
> \- Needs no scope: the search reads no account data, so any valid token may ask.\
> \- An answer with an empty \`sources\` array was not grounded in the documentation; that is a 200, not an error.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"documentation-search","summary":"Documentation search","description":"Ask a question in plain language and get an answer from Terra's published documentation."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":[]}],"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."}}}}},"schemas":{"DocsAskRequest":{"type":"object","properties":{"question":{"type":"string","description":"The question, in natural language.","maxLength":4000}},"required":["question"]},"DocsAskResponse":{"type":"object","properties":{"answer":{"type":"string","description":"The answer as markdown, with footnote markers referring to sources. Empty when nothing was found."},"confidence":{"type":"string","enum":["high","medium","low","unknown"],"description":"How sure the search is of the answer. `unknown` means it returned no rating."},"sources":{"type":"array","description":"The pages the answer came from. Empty when there are none.","items":{"$ref":"#/components/schemas/DocsSource"}}},"required":["answer","confidence","sources"]},"DocsSource":{"type":"object","description":"One documentation page the answer drew on.","properties":{"label":{"type":"string","description":"The footnote marker the answer refers to, e.g. \"1\"."},"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"type":{"type":"string","description":"What kind of record the source is, such as documentation."},"breadcrumbs":{"type":"array","description":"Where the page sits in the documentation navigation.","items":{"type":"string"}}},"required":["url"]},"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"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","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":{"/docs/ask":{"post":{"operationId":"askDocs","tags":["documentation-search"],"summary":"Ask a question about Terra and get an answer from the documentation","description":"Answers a question about Terra from the published documentation and cites the pages the answer drew on.\n\n- Needs no scope: the search reads no account data, so any valid token may ask.\n- An answer with an empty `sources` array was not grounded in the documentation; that is a 200, not an error.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocsAskRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocsAskResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```
