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

# Destinations

Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is.

## List destination types

> Lists every type a destination can be created as, with the configuration fields it takes, which of them it needs to deliver and which are secrets. The list is identical for every environment.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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":{"DestinationType":{"type":"object","properties":{"type":{"type":"string","description":"The value create takes as type."},"display_name":{"type":"string"},"icon_url":{"type":"string"},"config_fields":{"type":"array","items":{"$ref":"#/components/schemas/DestinationConfigField"}},"aws_role_setup":{"description":"On s3 and sqs, when Terra can assume a role in your AWS account instead of using an access key: what you need to create that role. Absent on the public catalogue.","$ref":"#/components/schemas/AwsRoleSetup"}},"required":["type","display_name","icon_url","config_fields"]},"DestinationConfigField":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","integer","object"]},"required":{"type":"boolean","description":"Needed for the destination to deliver. A draft saved inactive may leave it unset."},"secret":{"type":"boolean","description":"Write-only: reads return it masked."},"enum":{"type":["array","null"],"description":"The values the field accepts, or null when it is free text.","items":{"type":"string"}}},"required":["name","type","required","secret","enum"]},"AwsRoleSetup":{"type":"object","description":"What you need to create the role Terra assumes to deliver to your S3 bucket or SQS queue. The role can only write to the bucket and queue you name.","properties":{"external_id":{"type":"string","description":"The External ID the role's trust policy must require. It is derived from your account and is the same for every environment."},"terra_principal_arn":{"type":"string","description":"The Terra principal the role must trust."},"template_url":{"type":"string","description":"The CloudFormation template that creates the role."},"quick_create_url":{"type":"string","description":"A CloudFormation console link that creates the stack with these values filled in. Add param_BucketName and param_QueueArn to fill in the bucket and queue too."}},"required":["external_id","terra_principal_arn","template_url","quick_create_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":{"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"}}}}}},"paths":{"/environments/{dev_id}/unified-api/destination-types":{"get":{"operationId":"listDestinationTypes","tags":["destinations"],"summary":"List destination types","description":"Lists every type a destination can be created as, with the configuration fields it takes, which of them it needs to deliver and which are secrets. The list is identical for every environment.","parameters":[{"$ref":"#/components/parameters/DevId"}],"responses":{"200":{"description":"The destination types.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DestinationType"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## List destinations

> Lists the environment's destinations, cursor-paginated, with inactive ones included as \`active: false\`.\
> \
> \- Rows carry no credential material: each \`url\` has any credentials it embeds removed.\
> \- A webhook's signing secret is returned only in the create response.\
> \- The configuration is read back, masked, by \`GET /environments/{dev\_id}/unified-api/destinations/{destination\_id}\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"DestinationSummary":{"type":"object","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"type":{"type":"string"},"url":{"type":"string","description":"Where the destination delivers, as stored, without any embedded user and password. An azureblob URL omits its SAS token, which retrieving the destination's secrets returns."},"active":{"type":"boolean"},"event_types":{"type":"array","description":"The event types delivered here. An empty list delivers every event type.","items":{"type":"string"}},"disabled_reason":{"type":["string","null"],"enum":["owner","auto_disabled_failed_delivery","unrecorded",null],"description":"Why the destination is off: owner (turned off through the API or dashboard), auto_disabled_failed_delivery (Terra turned it off after deliveries failed for 24 hours), or unrecorded (turned off before Terra recorded why). Null while active."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When the destination was turned off. Null while active, and when it was turned off before Terra recorded when (disabled_reason unrecorded)."}},"required":["id","type","url","active","disabled_reason","disabled_at"]},"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"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/destinations":{"get":{"operationId":"listDestinations","tags":["destinations"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DestinationSummary"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List destinations","description":"Lists the environment's destinations, cursor-paginated, with inactive ones included as `active: false`.\n\n- Rows carry no credential material: each `url` has any credentials it embeds removed.\n- A webhook's signing secret is returned only in the create response.\n- The configuration is read back, masked, by `GET /environments/{dev_id}/unified-api/destinations/{destination_id}`.","parameters":[{"$ref":"#/components/parameters/DevId"}]}}}}
```

## Create a destination

> Creates a destination and returns it with its secrets masked.\
> \
> \- Terra translates \`config\` into what delivery reads, so send only the fields \`GET /environments/{dev\_id}/unified-api/destination-types\` lists for the type.\
> \- For a webhook, the 201 body is the only place its \`signing\_secret\` appears, so store it now.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"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":{}},"CreatedDestination":{"type":"object","description":"A newly created destination, plus its own webhook signing secret when it is a webhook.","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"type":{"type":"string"},"url":{"type":"string","description":"Where the destination delivers, as stored, without any embedded user and password. An azureblob URL omits its SAS token, which retrieving the destination's secrets returns."},"active":{"type":"boolean"},"event_types":{"type":"array","description":"The event types delivered here. An empty list delivers every event type.","items":{"type":"string"}},"disabled_reason":{"type":["string","null"],"enum":["owner","auto_disabled_failed_delivery","unrecorded",null],"description":"Why the destination is off: owner (turned off through the API or dashboard), auto_disabled_failed_delivery (Terra turned it off after deliveries failed for 24 hours), or unrecorded (turned off before Terra recorded why). Null while active."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When the destination was turned off. Null while active, and when it was turned off before Terra recorded when (disabled_reason unrecorded)."},"configured":{"type":"boolean","description":"Whether the configuration has every field the type needs to deliver. A draft saved inactive reads false until it is completed."},"missing":{"type":"array","description":"The required configuration fields still unset, as config.<field>. Empty when configured.","items":{"type":"string"}},"config":{"description":"Null when the stored configuration cannot be read; configured is then false, and config cannot be changed until the destination is recreated.","anyOf":[{"$ref":"#/components/schemas/DestinationConfigView"},{"type":"null"}]},"signing_secret":{"type":["string","null"],"description":"The secret this destination signs its webhook payloads with. Set for webhook destinations; null otherwise and on an Idempotency-Key replay. Retrieving the destination's secrets returns it again."}},"required":["id","type","url","active","disabled_reason","disabled_at","configured","missing","config","signing_secret"]},"DestinationConfigView":{"description":"A destination's configuration as read back, by type. Every field is present; unset ones are null.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfigView"},{"$ref":"#/components/schemas/S3DestinationConfigView"},{"$ref":"#/components/schemas/SqsDestinationConfigView"},{"$ref":"#/components/schemas/GcsDestinationConfigView"},{"$ref":"#/components/schemas/FirestoreDestinationConfigView"},{"$ref":"#/components/schemas/SupabaseDestinationConfigView"},{"$ref":"#/components/schemas/MongodbDestinationConfigView"},{"$ref":"#/components/schemas/KafkaDestinationConfigView"},{"$ref":"#/components/schemas/SqlDestinationConfigView"},{"$ref":"#/components/schemas/AzureblobDestinationConfigView"}]},"WebhookDestinationConfigView":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The endpoint deliveries are posted to, as set."},"delivery":{"type":"string","enum":["push","ping"]}},"required":["url","delivery"]},"S3DestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]}},"required":["bucket","region","role_arn","access_key_id","secret_access_key_masked"]},"SqsDestinationConfigView":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue's AWS URL."},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]},"s3_bucket":{"type":["string","null"]}},"required":["queue","region","role_arn","access_key_id","secret_access_key_masked","s3_bucket"]},"GcsDestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["bucket","has_service_account_key","service_account_email"]},"FirestoreDestinationConfigView":{"type":"object","properties":{"database":{"type":"string"},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["database","has_service_account_key","service_account_email"]},"SupabaseDestinationConfigView":{"type":"object","properties":{"project_url":{"type":["string","null"]},"bucket":{"type":["string","null"]},"api_key_masked":{"type":["string","null"]},"provisioned_via":{"type":"string","enum":["oauth","api_key"],"description":"oauth when the destination was provisioned through the Supabase connection flow, api_key when it was configured with a key."},"organization_name":{"type":["string","null"]},"project_name":{"type":["string","null"]}},"required":["project_url","bucket","api_key_masked","provisioned_via","organization_name","project_name"]},"MongodbDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","database","username","password_masked"]},"KafkaDestinationConfigView":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["host","port","topic","username","password_masked"]},"SqlDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","port","database","username","password_masked"]},"AzureblobDestinationConfigView":{"type":"object","properties":{"account_url":{"type":["string","null"]},"container":{"type":["string","null"]},"sas_token_masked":{"type":["string","null"]}},"required":["account_url","container","sas_token_masked"]},"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"]},"CreateDestinationRequest":{"type":"object","properties":{"type":{"type":"string","description":"Where data is delivered, e.g. webhook, s3, gcs. Omitted defaults to webhook, which is the common case; an unrecognised type is a 400.","default":"webhook"},"config":{"description":"The type's configuration; GET unified-api/destination-types lists each type's fields. An active destination needs every required field, and each missing one is a 400 naming it. An inactive destination may be saved incomplete as a draft and finished with a PATCH.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfig"},{"$ref":"#/components/schemas/S3DestinationConfig"},{"$ref":"#/components/schemas/SqsDestinationConfig"},{"$ref":"#/components/schemas/GcsDestinationConfig"},{"$ref":"#/components/schemas/FirestoreDestinationConfig"},{"$ref":"#/components/schemas/SupabaseDestinationConfig"},{"$ref":"#/components/schemas/MongodbDestinationConfig"},{"$ref":"#/components/schemas/KafkaDestinationConfig"},{"$ref":"#/components/schemas/SqlDestinationConfig"},{"$ref":"#/components/schemas/AzureblobDestinationConfig"}]},"event_types":{"type":"array","description":"Which events to deliver here, as a list of event-type names. Omitted or empty delivers every event type, and an unrecognised name is a 400 naming it.","items":{"type":"string"}},"active":{"type":"boolean","description":"Whether to start delivering immediately. Omitted defaults to true.","default":true},"signing_secret_source":{"type":"string","enum":["destination"],"description":"Deprecated: every webhook signs with its own secret, generated here and returned once. Webhooks only; environment is rejected.","default":"destination"},"url":{"type":"string","description":"Deprecated: send config instead. The delivery location in the stored form; cannot be combined with config.","deprecated":true},"metadata":{"type":"string","description":"Deprecated: send config instead. Credential JSON in the stored form; cannot be combined with config.","deprecated":true}}},"WebhookDestinationConfig":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The http or https endpoint deliveries are posted to. Reading the destination returns it as set, so verify deliveries with the signing secret rather than a token in the URL."},"delivery":{"type":["string","null"],"enum":["push","ping",null],"description":"push sends each payload; ping sends a notification to fetch it. Defaults to push."}},"additionalProperties":false},"S3DestinationConfig":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"],"description":"A role in your AWS account that Terra assumes instead of using an access key, created by the template in the destination type's aws_role_setup. Set it or access_key_id and secret_access_key, not both; send the other pair as null to switch."},"access_key_id":{"type":["string","null"]},"secret_access_key":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"SqsDestinationConfig":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue URL, its ARN or account_id/queue_name."},"region":{"type":["string","null"],"description":"Optional when the queue URL or ARN names it; a region that disagrees with the queue's is a 400."},"role_arn":{"type":["string","null"],"description":"A role in your AWS account that Terra assumes instead of using an access key, created by the template in the destination type's aws_role_setup. Set it or access_key_id and secret_access_key, not both; send the other pair as null to switch."},"access_key_id":{"type":["string","null"]},"secret_access_key":{"type":["string","null"],"description":"Write-only."},"s3_bucket":{"type":["string","null"],"description":"A bucket to stage payloads in; the message then carries an S3 URL."}},"additionalProperties":false},"GcsDestinationConfig":{"type":"object","properties":{"bucket":{"type":["string","null"]},"service_account_key":{"type":["object","null"],"description":"Write-only. The service account's JSON key file.","additionalProperties":true}},"additionalProperties":false},"FirestoreDestinationConfig":{"type":"object","properties":{"database":{"type":["string","null"],"description":"Defaults to default."},"service_account_key":{"type":["object","null"],"description":"Write-only. The service account's JSON key file.","additionalProperties":true}},"additionalProperties":false},"SupabaseDestinationConfig":{"type":"object","properties":{"project_url":{"type":["string","null"],"description":"The project's URL, e.g. https://abcd.supabase.co."},"bucket":{"type":["string","null"]},"api_key":{"type":["string","null"],"description":"Write-only. A service-role key."}},"additionalProperties":false},"MongodbDestinationConfig":{"type":"object","properties":{"scheme":{"type":["string","null"],"enum":["mongodb","mongodb+srv",null]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"KafkaDestinationConfig":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"SqlDestinationConfig":{"type":"object","properties":{"scheme":{"type":["string","null"],"enum":["postgres","postgresql","mysql",null]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"AzureblobDestinationConfig":{"type":"object","properties":{"account_url":{"type":["string","null"],"description":"The storage account's URL, e.g. https://account.blob.core.windows.net."},"container":{"type":["string","null"]},"sas_token":{"type":["string","null"],"description":"Write-only. The SAS token the destination authenticates with, without its leading ?."}},"additionalProperties":false}},"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"}}}}},"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."}}},"paths":{"/environments/{dev_id}/unified-api/destinations":{"post":{"operationId":"createDestination","tags":["destinations"],"responses":{"200":{"description":"DryRunResult when ?dry_run=true. The preview omits id and signing_secret, which do not exist until the destination does; will_return_signing_secret says one would be issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedDestination"}}}},"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"}},"summary":"Create a destination","description":"Creates a destination and returns it with its secrets masked.\n\n- Terra translates `config` into what delivery reads, so send only the fields `GET /environments/{dev_id}/unified-api/destination-types` lists for the type.\n- For a webhook, the 201 body is the only place its `signing_secret` appears, so store it now.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDestinationRequest"}}}}}}}}
```

## Get destination health

> Works out each destination's health on request from its last 24 hours of delivery outcomes, judged on the last hour.\
> \
> \- A delivery is one event to one destination, counted once however many attempts it took, as \`GET /environments/{dev\_id}/events\` shows.\
> \- Failing, with \`info.failing\_since\` set to when it began, means every delivery finished in the last hour failed, deliveries have waited on automatic retries for an hour with none delivered, or retries ran out and none has been delivered since.\
> \- A resend counts whatever its event's age but keeps its creation time, so how long it has retried is unknown; one still failing makes the destination degraded.\
> \- A delivery Terra could not send because it could not load the payload does not count. A disabled destination's error carries its \`disabled\_reason\`, e.g. \`auto\_disabled\_failed\_delivery\` for one Terra turned off after failing.\
> \- When delivery state cannot be read, every destination is \`unknown\` with error \`check\_unavailable\`: health is never assumed.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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":{"DestinationHealth":{"type":"object","description":"A destination's delivery health, worked out from the outcomes of the last 24 hours of deliveries and judged on the last hour.","properties":{"destination_id":{"type":"string","description":"string-encoded 64-bit id"},"status":{"type":"string","enum":["healthy","degraded","failing","idle","disabled","unknown"],"description":"healthy: delivering. degraded: some deliveries in the last hour failed, a delivery has waited on automatic retries for 15 minutes, a resend failed in the last hour and is still retrying, or most deliveries in the last hour needed a retry. failing: every delivery that finished in the last hour failed, deliveries have waited on automatic retries for an hour with none delivered, every delivery that finished in 24 hours failed, or retries ran out and none has been delivered since. idle: no deliveries in 24 hours. disabled: the destination is off. unknown: delivery state could not be read; this is never reported as healthy."},"info":{"description":"The deliveries behind the status. Null when unknown.","anyOf":[{"$ref":"#/components/schemas/DestinationHealthInfo"},{"type":"null"}]},"error":{"description":"Why the destination is not healthy. Null when healthy or idle, and for degraded or failing when the failure left no detail.","anyOf":[{"$ref":"#/components/schemas/DestinationHealthError"},{"type":"null"}]}},"required":["destination_id","status","info","error"]},"DestinationHealthInfo":{"type":"object","description":"The deliveries behind a destination's status. These are the deliveries listWebhookEvents shows for the destination.","properties":{"failing_since":{"type":["string","null"],"format":"date-time","description":"When the current failure began: the first delivery whose retries ran out with no success since. Null when not failing, or failing for less than one full retry chain."},"last_delivered_at":{"type":["string","null"],"format":"date-time","description":"The last delivery that arrived in the last 24 hours, or null."},"last_failure_at":{"type":["string","null"],"format":"date-time","description":"The last failed or retrying delivery's latest attempt, or null."},"last_failure_status_code":{"type":["integer","null"],"description":"The HTTP status a webhook answered on its last failure. Null for other destination types, and when there was no answer: a timeout or a connection failure."},"pending":{"type":"integer","description":"Deliveries still waiting on a retry, including a resend still retrying after its event was delivered. listWebhookEvents shows such a delivery as delivered until the resend ends; health counts it here because it is how the destination is answering now."},"oldest_pending_at":{"type":["string","null"],"format":"date-time","description":"When the oldest delivery still waiting on an automatic retry was created, or null. A resend keeps its event's creation time, so its age is unknown and it is not counted here."},"counts":{"$ref":"#/components/schemas/DestinationHealthCounts"}},"required":["failing_since","last_delivered_at","last_failure_at","last_failure_status_code","pending","oldest_pending_at","counts"]},"DestinationHealthCounts":{"type":"object","description":"Delivery counts over the last hour and the last 24 hours, by when each delivery reached its outcome.","properties":{"last_hour":{"$ref":"#/components/schemas/DestinationDeliveryCounts"},"last_24h":{"$ref":"#/components/schemas/DestinationDeliveryCounts"}},"required":["last_hour","last_24h"]},"DestinationDeliveryCounts":{"type":"object","description":"Deliveries that reached an outcome in a window, counted once per event and destination however many attempts they took. A delivery Terra could not send because it could not load the payload is not counted: that failure is Terra's, not the destination's.","properties":{"delivered":{"type":"integer","description":"Deliveries that arrived."},"failed":{"type":"integer","description":"Deliveries whose retries ran out, or whose retry is more than six hours overdue."},"retried":{"type":"integer","description":"Delivered deliveries that took more than one attempt."}},"required":["delivered","failed","retried"]},"DestinationHealthError":{"type":"object","description":"Why a destination is not healthy.","properties":{"code":{"type":"string","description":"A stable code. For degraded or failing: unauthorized, forbidden, not_found, gone, payload_too_large, rate_limited, timeout (no answer in time, or a 408 or 504), unreachable (could not connect), paused (Terra is holding deliveries back after repeated failures), server_error, rejected, unexpected_status, no_response, retrying (deliveries arrive but most needed a retry), or delivery_error for non-webhook destinations. For disabled: the disabled_reason. For unknown: check_unavailable."},"message":{"type":"string","description":"The code in a sentence."}},"required":["code","message"]},"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"}}}}}},"paths":{"/environments/{dev_id}/unified-api/destinations/health":{"get":{"operationId":"getDestinationsHealth","tags":["destinations"],"summary":"Get destination health","description":"Works out each destination's health on request from its last 24 hours of delivery outcomes, judged on the last hour.\n\n- A delivery is one event to one destination, counted once however many attempts it took, as `GET /environments/{dev_id}/events` shows.\n- Failing, with `info.failing_since` set to when it began, means every delivery finished in the last hour failed, deliveries have waited on automatic retries for an hour with none delivered, or retries ran out and none has been delivered since.\n- A resend counts whatever its event's age but keeps its creation time, so how long it has retried is unknown; one still failing makes the destination degraded.\n- A delivery Terra could not send because it could not load the payload does not count. A disabled destination's error carries its `disabled_reason`, e.g. `auto_disabled_failed_delivery` for one Terra turned off after failing.\n- When delivery state cannot be read, every destination is `unknown` with error `check_unavailable`: health is never assumed.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"destination_id","in":"query","required":false,"description":"Only these destinations, as string-encoded ids. Comma-separate them or repeat the parameter. Omit for every destination in the environment.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DestinationHealth"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Create several destinations

> Creates several destinations in one transaction and returns them in request order.\
> \
> \- Every invalid item is reported in one 400 whose errors are prefixed with its position, e.g. \`items\[2].config.url\`.\
> \- The deprecated \`url\` and \`metadata\` fields are not accepted.\
> \- For a webhook, its item in the response is the only place its \`signing\_secret\` appears, so store it now. The MCP refuses an oversized batch so that no signing secret is ever lost to a truncated result.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"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":{}},"BatchCreatedDestinations":{"type":"object","properties":{"data":{"type":"array","description":"One created destination per item, in request order.","items":{"$ref":"#/components/schemas/CreatedDestination"}}},"required":["data"]},"CreatedDestination":{"type":"object","description":"A newly created destination, plus its own webhook signing secret when it is a webhook.","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"type":{"type":"string"},"url":{"type":"string","description":"Where the destination delivers, as stored, without any embedded user and password. An azureblob URL omits its SAS token, which retrieving the destination's secrets returns."},"active":{"type":"boolean"},"event_types":{"type":"array","description":"The event types delivered here. An empty list delivers every event type.","items":{"type":"string"}},"disabled_reason":{"type":["string","null"],"enum":["owner","auto_disabled_failed_delivery","unrecorded",null],"description":"Why the destination is off: owner (turned off through the API or dashboard), auto_disabled_failed_delivery (Terra turned it off after deliveries failed for 24 hours), or unrecorded (turned off before Terra recorded why). Null while active."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When the destination was turned off. Null while active, and when it was turned off before Terra recorded when (disabled_reason unrecorded)."},"configured":{"type":"boolean","description":"Whether the configuration has every field the type needs to deliver. A draft saved inactive reads false until it is completed."},"missing":{"type":"array","description":"The required configuration fields still unset, as config.<field>. Empty when configured.","items":{"type":"string"}},"config":{"description":"Null when the stored configuration cannot be read; configured is then false, and config cannot be changed until the destination is recreated.","anyOf":[{"$ref":"#/components/schemas/DestinationConfigView"},{"type":"null"}]},"signing_secret":{"type":["string","null"],"description":"The secret this destination signs its webhook payloads with. Set for webhook destinations; null otherwise and on an Idempotency-Key replay. Retrieving the destination's secrets returns it again."}},"required":["id","type","url","active","disabled_reason","disabled_at","configured","missing","config","signing_secret"]},"DestinationConfigView":{"description":"A destination's configuration as read back, by type. Every field is present; unset ones are null.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfigView"},{"$ref":"#/components/schemas/S3DestinationConfigView"},{"$ref":"#/components/schemas/SqsDestinationConfigView"},{"$ref":"#/components/schemas/GcsDestinationConfigView"},{"$ref":"#/components/schemas/FirestoreDestinationConfigView"},{"$ref":"#/components/schemas/SupabaseDestinationConfigView"},{"$ref":"#/components/schemas/MongodbDestinationConfigView"},{"$ref":"#/components/schemas/KafkaDestinationConfigView"},{"$ref":"#/components/schemas/SqlDestinationConfigView"},{"$ref":"#/components/schemas/AzureblobDestinationConfigView"}]},"WebhookDestinationConfigView":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The endpoint deliveries are posted to, as set."},"delivery":{"type":"string","enum":["push","ping"]}},"required":["url","delivery"]},"S3DestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]}},"required":["bucket","region","role_arn","access_key_id","secret_access_key_masked"]},"SqsDestinationConfigView":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue's AWS URL."},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]},"s3_bucket":{"type":["string","null"]}},"required":["queue","region","role_arn","access_key_id","secret_access_key_masked","s3_bucket"]},"GcsDestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["bucket","has_service_account_key","service_account_email"]},"FirestoreDestinationConfigView":{"type":"object","properties":{"database":{"type":"string"},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["database","has_service_account_key","service_account_email"]},"SupabaseDestinationConfigView":{"type":"object","properties":{"project_url":{"type":["string","null"]},"bucket":{"type":["string","null"]},"api_key_masked":{"type":["string","null"]},"provisioned_via":{"type":"string","enum":["oauth","api_key"],"description":"oauth when the destination was provisioned through the Supabase connection flow, api_key when it was configured with a key."},"organization_name":{"type":["string","null"]},"project_name":{"type":["string","null"]}},"required":["project_url","bucket","api_key_masked","provisioned_via","organization_name","project_name"]},"MongodbDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","database","username","password_masked"]},"KafkaDestinationConfigView":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["host","port","topic","username","password_masked"]},"SqlDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","port","database","username","password_masked"]},"AzureblobDestinationConfigView":{"type":"object","properties":{"account_url":{"type":["string","null"]},"container":{"type":["string","null"]},"sas_token_masked":{"type":["string","null"]}},"required":["account_url","container","sas_token_masked"]},"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"]},"BatchCreateDestinationsRequest":{"type":"object","properties":{"items":{"type":"array","description":"The destinations to create, each shaped like a single create: at least 1 and at most 100. Every item is validated before anything is written, and an invalid one is a 400 naming its position, so either every destination is created or none is. Through the MCP, a batch whose result would not fit in one tool result is a 400 asking for smaller batches.","items":{"$ref":"#/components/schemas/BatchDestinationItem"},"minItems":1,"maxItems":100}},"required":["items"]},"BatchDestinationItem":{"type":"object","properties":{"type":{"type":"string","description":"Where data is delivered, e.g. webhook, s3, gcs. Omitted defaults to webhook, which is the common case; an unrecognised type is a 400.","default":"webhook"},"config":{"description":"The type's configuration; GET unified-api/destination-types lists each type's fields. An active destination needs every required field, and each missing one is a 400 naming it. An inactive destination may be saved incomplete as a draft and finished with a PATCH.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfig"},{"$ref":"#/components/schemas/S3DestinationConfig"},{"$ref":"#/components/schemas/SqsDestinationConfig"},{"$ref":"#/components/schemas/GcsDestinationConfig"},{"$ref":"#/components/schemas/FirestoreDestinationConfig"},{"$ref":"#/components/schemas/SupabaseDestinationConfig"},{"$ref":"#/components/schemas/MongodbDestinationConfig"},{"$ref":"#/components/schemas/KafkaDestinationConfig"},{"$ref":"#/components/schemas/SqlDestinationConfig"},{"$ref":"#/components/schemas/AzureblobDestinationConfig"}]},"event_types":{"type":"array","description":"Which events to deliver here, as a list of event-type names. Omitted or empty delivers every event type, and an unrecognised name is a 400 naming it.","items":{"type":"string"}},"active":{"type":"boolean","description":"Whether to start delivering immediately. Omitted defaults to true.","default":true},"signing_secret_source":{"type":"string","enum":["destination"],"description":"Deprecated: every webhook signs with its own secret, generated here and returned once. Webhooks only; environment is rejected.","default":"destination"}}},"WebhookDestinationConfig":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The http or https endpoint deliveries are posted to. Reading the destination returns it as set, so verify deliveries with the signing secret rather than a token in the URL."},"delivery":{"type":["string","null"],"enum":["push","ping",null],"description":"push sends each payload; ping sends a notification to fetch it. Defaults to push."}},"additionalProperties":false},"S3DestinationConfig":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"],"description":"A role in your AWS account that Terra assumes instead of using an access key, created by the template in the destination type's aws_role_setup. Set it or access_key_id and secret_access_key, not both; send the other pair as null to switch."},"access_key_id":{"type":["string","null"]},"secret_access_key":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"SqsDestinationConfig":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue URL, its ARN or account_id/queue_name."},"region":{"type":["string","null"],"description":"Optional when the queue URL or ARN names it; a region that disagrees with the queue's is a 400."},"role_arn":{"type":["string","null"],"description":"A role in your AWS account that Terra assumes instead of using an access key, created by the template in the destination type's aws_role_setup. Set it or access_key_id and secret_access_key, not both; send the other pair as null to switch."},"access_key_id":{"type":["string","null"]},"secret_access_key":{"type":["string","null"],"description":"Write-only."},"s3_bucket":{"type":["string","null"],"description":"A bucket to stage payloads in; the message then carries an S3 URL."}},"additionalProperties":false},"GcsDestinationConfig":{"type":"object","properties":{"bucket":{"type":["string","null"]},"service_account_key":{"type":["object","null"],"description":"Write-only. The service account's JSON key file.","additionalProperties":true}},"additionalProperties":false},"FirestoreDestinationConfig":{"type":"object","properties":{"database":{"type":["string","null"],"description":"Defaults to default."},"service_account_key":{"type":["object","null"],"description":"Write-only. The service account's JSON key file.","additionalProperties":true}},"additionalProperties":false},"SupabaseDestinationConfig":{"type":"object","properties":{"project_url":{"type":["string","null"],"description":"The project's URL, e.g. https://abcd.supabase.co."},"bucket":{"type":["string","null"]},"api_key":{"type":["string","null"],"description":"Write-only. A service-role key."}},"additionalProperties":false},"MongodbDestinationConfig":{"type":"object","properties":{"scheme":{"type":["string","null"],"enum":["mongodb","mongodb+srv",null]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"KafkaDestinationConfig":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"SqlDestinationConfig":{"type":"object","properties":{"scheme":{"type":["string","null"],"enum":["postgres","postgresql","mysql",null]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"AzureblobDestinationConfig":{"type":"object","properties":{"account_url":{"type":["string","null"],"description":"The storage account's URL, e.g. https://account.blob.core.windows.net."},"container":{"type":["string","null"]},"sas_token":{"type":["string","null"],"description":"Write-only. The SAS token the destination authenticates with, without its leading ?."}},"additionalProperties":false}},"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"}}}}},"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."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/batch-create":{"post":{"operationId":"batchCreateDestinations","tags":["destinations"],"responses":{"200":{"description":"DryRunResult when ?dry_run=true. Each item's preview omits id and signing_secret, which do not exist until the destination does; its will_return_signing_secret says one would be issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreatedDestinations"}}}},"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"}},"summary":"Create several destinations","description":"Creates several destinations in one transaction and returns them in request order.\n\n- Every invalid item is reported in one 400 whose errors are prefixed with its position, e.g. `items[2].config.url`.\n- The deprecated `url` and `metadata` fields are not accepted.\n- For a webhook, its item in the response is the only place its `signing_secret` appears, so store it now. The MCP refuses an oversized batch so that no signing secret is ever lost to a truncated result.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateDestinationsRequest"}}}}}}}}
```

## Retrieve a destination

> Returns one destination, with its configuration under the field names create and update take.\
> \
> \- Each secret comes back as \`\<field>\_masked\`, the last four characters behind asterisks, or null when unset; a key file as \`has\_service\_account\_key\` with its \`service\_account\_email\`.\
> \- \`GET /environments/{dev\_id}/unified-api/destinations/{destination\_id}/secrets\` reveals the secrets, under \`keys:read\`.\
> \- \`configured\` and \`missing\` say whether the destination has everything it needs to deliver.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"Destination":{"type":"object","description":"A destination with its configuration. Secrets are never returned: each is replaced by a masked form ending in its last four characters, or null when unset.","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"type":{"type":"string"},"url":{"type":"string","description":"Where the destination delivers, as stored, without any embedded user and password. An azureblob URL omits its SAS token, which retrieving the destination's secrets returns."},"active":{"type":"boolean"},"event_types":{"type":"array","description":"The event types delivered here. An empty list delivers every event type.","items":{"type":"string"}},"disabled_reason":{"type":["string","null"],"enum":["owner","auto_disabled_failed_delivery","unrecorded",null],"description":"Why the destination is off: owner (turned off through the API or dashboard), auto_disabled_failed_delivery (Terra turned it off after deliveries failed for 24 hours), or unrecorded (turned off before Terra recorded why). Null while active."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When the destination was turned off. Null while active, and when it was turned off before Terra recorded when (disabled_reason unrecorded)."},"configured":{"type":"boolean","description":"Whether the configuration has every field the type needs to deliver. A draft saved inactive reads false until it is completed."},"missing":{"type":"array","description":"The required configuration fields still unset, as config.<field>. Empty when configured.","items":{"type":"string"}},"config":{"description":"Null when the stored configuration cannot be read; configured is then false, and config cannot be changed until the destination is recreated.","anyOf":[{"$ref":"#/components/schemas/DestinationConfigView"},{"type":"null"}]}},"required":["id","type","url","active","disabled_reason","disabled_at","configured","missing","config"]},"DestinationConfigView":{"description":"A destination's configuration as read back, by type. Every field is present; unset ones are null.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfigView"},{"$ref":"#/components/schemas/S3DestinationConfigView"},{"$ref":"#/components/schemas/SqsDestinationConfigView"},{"$ref":"#/components/schemas/GcsDestinationConfigView"},{"$ref":"#/components/schemas/FirestoreDestinationConfigView"},{"$ref":"#/components/schemas/SupabaseDestinationConfigView"},{"$ref":"#/components/schemas/MongodbDestinationConfigView"},{"$ref":"#/components/schemas/KafkaDestinationConfigView"},{"$ref":"#/components/schemas/SqlDestinationConfigView"},{"$ref":"#/components/schemas/AzureblobDestinationConfigView"}]},"WebhookDestinationConfigView":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The endpoint deliveries are posted to, as set."},"delivery":{"type":"string","enum":["push","ping"]}},"required":["url","delivery"]},"S3DestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]}},"required":["bucket","region","role_arn","access_key_id","secret_access_key_masked"]},"SqsDestinationConfigView":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue's AWS URL."},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]},"s3_bucket":{"type":["string","null"]}},"required":["queue","region","role_arn","access_key_id","secret_access_key_masked","s3_bucket"]},"GcsDestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["bucket","has_service_account_key","service_account_email"]},"FirestoreDestinationConfigView":{"type":"object","properties":{"database":{"type":"string"},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["database","has_service_account_key","service_account_email"]},"SupabaseDestinationConfigView":{"type":"object","properties":{"project_url":{"type":["string","null"]},"bucket":{"type":["string","null"]},"api_key_masked":{"type":["string","null"]},"provisioned_via":{"type":"string","enum":["oauth","api_key"],"description":"oauth when the destination was provisioned through the Supabase connection flow, api_key when it was configured with a key."},"organization_name":{"type":["string","null"]},"project_name":{"type":["string","null"]}},"required":["project_url","bucket","api_key_masked","provisioned_via","organization_name","project_name"]},"MongodbDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","database","username","password_masked"]},"KafkaDestinationConfigView":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["host","port","topic","username","password_masked"]},"SqlDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","port","database","username","password_masked"]},"AzureblobDestinationConfigView":{"type":"object","properties":{"account_url":{"type":["string","null"]},"container":{"type":["string","null"]},"sas_token_masked":{"type":["string","null"]}},"required":["account_url","container","sas_token_masked"]},"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"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/{destination_id}":{"get":{"operationId":"retrieveDestination","tags":["destinations"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Destination"}}}},"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"}},"summary":"Retrieve a destination","description":"Returns one destination, with its configuration under the field names create and update take.\n\n- Each secret comes back as `<field>_masked`, the last four characters behind asterisks, or null when unset; a key file as `has_service_account_key` with its `service_account_email`.\n- `GET /environments/{dev_id}/unified-api/destinations/{destination_id}/secrets` reveals the secrets, under `keys:read`.\n- `configured` and `missing` say whether the destination has everything it needs to deliver.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"destination_id","in":"path","required":true,"schema":{"type":"string"},"description":"The destination to read, by the id its creation returned."}]}}}}
```

## Delete a destination

> Permanently deletes a destination together with its signing secret.\
> \
> \- Recreating the same URL produces a new destination with a new secret that receivers have to be told about.\
> \- Its delivery-failure tracking is reset.\
> \- Pass \`?dry\_run=true\` first to preview what would go.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"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":{"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"}}}}},"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."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/{destination_id}":{"delete":{"operationId":"deleteDestination","tags":["destinations"],"responses":{"200":{"description":"Dry-run preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a destination","description":"Permanently deletes a destination together with its signing secret.\n\n- Recreating the same URL produces a new destination with a new secret that receivers have to be told about.\n- Its delivery-failure tracking is reset.\n- Pass `?dry_run=true` first to preview what would go.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"destination_id","in":"path","required":true,"schema":{"type":"string"},"description":"The destination to act on, by the id its creation returned."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}]}}}}
```

## Update a destination

> Updates a destination and returns it with its secrets masked.\
> \
> \- Editing an active destination needs a complete configuration, as activating one does.\
> \- A webhook keeps its signing secret.\
> \- Any successful update resets the destination's delivery-failure tracking.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"Destination":{"type":"object","description":"A destination with its configuration. Secrets are never returned: each is replaced by a masked form ending in its last four characters, or null when unset.","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"type":{"type":"string"},"url":{"type":"string","description":"Where the destination delivers, as stored, without any embedded user and password. An azureblob URL omits its SAS token, which retrieving the destination's secrets returns."},"active":{"type":"boolean"},"event_types":{"type":"array","description":"The event types delivered here. An empty list delivers every event type.","items":{"type":"string"}},"disabled_reason":{"type":["string","null"],"enum":["owner","auto_disabled_failed_delivery","unrecorded",null],"description":"Why the destination is off: owner (turned off through the API or dashboard), auto_disabled_failed_delivery (Terra turned it off after deliveries failed for 24 hours), or unrecorded (turned off before Terra recorded why). Null while active."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When the destination was turned off. Null while active, and when it was turned off before Terra recorded when (disabled_reason unrecorded)."},"configured":{"type":"boolean","description":"Whether the configuration has every field the type needs to deliver. A draft saved inactive reads false until it is completed."},"missing":{"type":"array","description":"The required configuration fields still unset, as config.<field>. Empty when configured.","items":{"type":"string"}},"config":{"description":"Null when the stored configuration cannot be read; configured is then false, and config cannot be changed until the destination is recreated.","anyOf":[{"$ref":"#/components/schemas/DestinationConfigView"},{"type":"null"}]}},"required":["id","type","url","active","disabled_reason","disabled_at","configured","missing","config"]},"DestinationConfigView":{"description":"A destination's configuration as read back, by type. Every field is present; unset ones are null.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfigView"},{"$ref":"#/components/schemas/S3DestinationConfigView"},{"$ref":"#/components/schemas/SqsDestinationConfigView"},{"$ref":"#/components/schemas/GcsDestinationConfigView"},{"$ref":"#/components/schemas/FirestoreDestinationConfigView"},{"$ref":"#/components/schemas/SupabaseDestinationConfigView"},{"$ref":"#/components/schemas/MongodbDestinationConfigView"},{"$ref":"#/components/schemas/KafkaDestinationConfigView"},{"$ref":"#/components/schemas/SqlDestinationConfigView"},{"$ref":"#/components/schemas/AzureblobDestinationConfigView"}]},"WebhookDestinationConfigView":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The endpoint deliveries are posted to, as set."},"delivery":{"type":"string","enum":["push","ping"]}},"required":["url","delivery"]},"S3DestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]}},"required":["bucket","region","role_arn","access_key_id","secret_access_key_masked"]},"SqsDestinationConfigView":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue's AWS URL."},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"]},"access_key_id":{"type":["string","null"]},"secret_access_key_masked":{"type":["string","null"]},"s3_bucket":{"type":["string","null"]}},"required":["queue","region","role_arn","access_key_id","secret_access_key_masked","s3_bucket"]},"GcsDestinationConfigView":{"type":"object","properties":{"bucket":{"type":["string","null"]},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["bucket","has_service_account_key","service_account_email"]},"FirestoreDestinationConfigView":{"type":"object","properties":{"database":{"type":"string"},"has_service_account_key":{"type":"boolean"},"service_account_email":{"type":["string","null"],"description":"The key file's client_email."}},"required":["database","has_service_account_key","service_account_email"]},"SupabaseDestinationConfigView":{"type":"object","properties":{"project_url":{"type":["string","null"]},"bucket":{"type":["string","null"]},"api_key_masked":{"type":["string","null"]},"provisioned_via":{"type":"string","enum":["oauth","api_key"],"description":"oauth when the destination was provisioned through the Supabase connection flow, api_key when it was configured with a key."},"organization_name":{"type":["string","null"]},"project_name":{"type":["string","null"]}},"required":["project_url","bucket","api_key_masked","provisioned_via","organization_name","project_name"]},"MongodbDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","database","username","password_masked"]},"KafkaDestinationConfigView":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["host","port","topic","username","password_masked"]},"SqlDestinationConfigView":{"type":"object","properties":{"scheme":{"type":["string","null"]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password_masked":{"type":["string","null"]}},"required":["scheme","host","port","database","username","password_masked"]},"AzureblobDestinationConfigView":{"type":"object","properties":{"account_url":{"type":["string","null"]},"container":{"type":["string","null"]},"sas_token_masked":{"type":["string","null"]}},"required":["account_url","container","sas_token_masked"]},"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"]},"PatchDestinationRequest":{"type":"object","properties":{"active":{"type":"boolean","description":"Whether the destination is delivering. Omitted leaves it as it is. Activating needs a complete configuration."},"event_types":{"type":"array","description":"Which events to deliver here, replaced wholesale, so send the full list rather than the additions. Omitted leaves the current set alone, an empty list delivers every event type, and an unrecognised name is a 400 naming it.","items":{"type":"string"}},"config":{"description":"Fields to change, merged over the stored configuration: an omitted field keeps its value, secrets included, and null clears an optional one. Changing where a secret is sent (a database's scheme, host, port, database or username, a Kafka host or port, a Supabase project_url, an Azure account_url) requires resending that secret, because a stored secret is never sent to a new endpoint; a missing one is a 400 naming it. An empty secret is a 400. The type cannot change.","anyOf":[{"$ref":"#/components/schemas/WebhookDestinationConfig"},{"$ref":"#/components/schemas/S3DestinationConfig"},{"$ref":"#/components/schemas/SqsDestinationConfig"},{"$ref":"#/components/schemas/GcsDestinationConfig"},{"$ref":"#/components/schemas/FirestoreDestinationConfig"},{"$ref":"#/components/schemas/SupabaseDestinationConfig"},{"$ref":"#/components/schemas/MongodbDestinationConfig"},{"$ref":"#/components/schemas/KafkaDestinationConfig"},{"$ref":"#/components/schemas/SqlDestinationConfig"},{"$ref":"#/components/schemas/AzureblobDestinationConfig"}]}}},"WebhookDestinationConfig":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The http or https endpoint deliveries are posted to. Reading the destination returns it as set, so verify deliveries with the signing secret rather than a token in the URL."},"delivery":{"type":["string","null"],"enum":["push","ping",null],"description":"push sends each payload; ping sends a notification to fetch it. Defaults to push."}},"additionalProperties":false},"S3DestinationConfig":{"type":"object","properties":{"bucket":{"type":["string","null"]},"region":{"type":["string","null"]},"role_arn":{"type":["string","null"],"description":"A role in your AWS account that Terra assumes instead of using an access key, created by the template in the destination type's aws_role_setup. Set it or access_key_id and secret_access_key, not both; send the other pair as null to switch."},"access_key_id":{"type":["string","null"]},"secret_access_key":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"SqsDestinationConfig":{"type":"object","properties":{"queue":{"type":["string","null"],"description":"The queue URL, its ARN or account_id/queue_name."},"region":{"type":["string","null"],"description":"Optional when the queue URL or ARN names it; a region that disagrees with the queue's is a 400."},"role_arn":{"type":["string","null"],"description":"A role in your AWS account that Terra assumes instead of using an access key, created by the template in the destination type's aws_role_setup. Set it or access_key_id and secret_access_key, not both; send the other pair as null to switch."},"access_key_id":{"type":["string","null"]},"secret_access_key":{"type":["string","null"],"description":"Write-only."},"s3_bucket":{"type":["string","null"],"description":"A bucket to stage payloads in; the message then carries an S3 URL."}},"additionalProperties":false},"GcsDestinationConfig":{"type":"object","properties":{"bucket":{"type":["string","null"]},"service_account_key":{"type":["object","null"],"description":"Write-only. The service account's JSON key file.","additionalProperties":true}},"additionalProperties":false},"FirestoreDestinationConfig":{"type":"object","properties":{"database":{"type":["string","null"],"description":"Defaults to default."},"service_account_key":{"type":["object","null"],"description":"Write-only. The service account's JSON key file.","additionalProperties":true}},"additionalProperties":false},"SupabaseDestinationConfig":{"type":"object","properties":{"project_url":{"type":["string","null"],"description":"The project's URL, e.g. https://abcd.supabase.co."},"bucket":{"type":["string","null"]},"api_key":{"type":["string","null"],"description":"Write-only. A service-role key."}},"additionalProperties":false},"MongodbDestinationConfig":{"type":"object","properties":{"scheme":{"type":["string","null"],"enum":["mongodb","mongodb+srv",null]},"host":{"type":["string","null"]},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"KafkaDestinationConfig":{"type":"object","properties":{"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"topic":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"SqlDestinationConfig":{"type":"object","properties":{"scheme":{"type":["string","null"],"enum":["postgres","postgresql","mysql",null]},"host":{"type":["string","null"]},"port":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"database":{"type":["string","null"]},"username":{"type":["string","null"]},"password":{"type":["string","null"],"description":"Write-only."}},"additionalProperties":false},"AzureblobDestinationConfig":{"type":"object","properties":{"account_url":{"type":["string","null"],"description":"The storage account's URL, e.g. https://account.blob.core.windows.net."},"container":{"type":["string","null"]},"sas_token":{"type":["string","null"],"description":"Write-only. The SAS token the destination authenticates with, without its leading ?."}},"additionalProperties":false}},"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"}}}}},"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."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/{destination_id}":{"patch":{"operationId":"patchDestination","tags":["destinations"],"responses":{"200":{"description":"Updated (or DryRunResult when ?dry_run=true).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/Destination"},{"$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"}},"summary":"Update a destination","description":"Updates a destination and returns it with its secrets masked.\n\n- Editing an active destination needs a complete configuration, as activating one does.\n- A webhook keeps its signing secret.\n- Any successful update resets the destination's delivery-failure tracking.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"destination_id","in":"path","required":true,"schema":{"type":"string"},"description":"The destination to act on, by the id its creation returned."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDestinationRequest"}}}}}}}}
```

## Reveal a destination's credentials

> Returns in plaintext the secret configuration fields that \`GET /environments/{dev\_id}/unified-api/destinations/{destination\_id}\` masks: a database password, an access key secret, a key file, an API key, a SAS token, or the secret a webhook's deliveries are signed with.\
> \
> \- Gated by \`keys:read\`, the same sensitive plaintext disclosure class as \`GET /environments/{dev\_id}/api-key\`, and audited.\
> \- A destination whose stored configuration is unreadable is a 409.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["keys: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":{"DestinationSecrets":{"type":"object","description":"A destination's stored secrets in plaintext.","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"type":{"type":"string"},"secrets":{"$ref":"#/components/schemas/DestinationSecretValues"}},"required":["id","type","secrets"]},"DestinationSecretValues":{"type":"object","description":"The secret configuration fields of the destination's type, each null when unset. Only the type's own fields are present: password (sql, mongodb, kafka), secret_access_key (s3, sqs), service_account_key (gcs, firestore), api_key (supabase), sas_token (azureblob), signing_secret (webhook).","properties":{"password":{"type":["string","null"]},"secret_access_key":{"type":["string","null"]},"service_account_key":{"type":["object","null"],"description":"The service account's JSON key file.","additionalProperties":true},"api_key":{"type":["string","null"]},"sas_token":{"type":["string","null"]},"signing_secret":{"type":["string","null"]}}},"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"}}}},"Conflict":{"description":"Idempotency-Key reuse with a different body, or a precondition conflict.","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"}}}}}},"paths":{"/environments/{dev_id}/unified-api/destinations/{destination_id}/secrets":{"get":{"operationId":"revealDestinationSecrets","tags":["destinations"],"summary":"Reveal a destination's credentials","description":"Returns in plaintext the secret configuration fields that `GET /environments/{dev_id}/unified-api/destinations/{destination_id}` masks: a database password, an access key secret, a key file, an API key, a SAS token, or the secret a webhook's deliveries are signed with.\n\n- Gated by `keys:read`, the same sensitive plaintext disclosure class as `GET /environments/{dev_id}/api-key`, and audited.\n- A destination whose stored configuration is unreadable is a 409.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"destination_id","in":"path","required":true,"schema":{"type":"string"},"description":"The destination to read, by the id its creation returned. A destination outside this environment is a 404."}],"responses":{"200":{"description":"The destination's secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationSecrets"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Rotate a webhook's signing secret

> Generates a new signing secret for one webhook destination, replacing its own or the environment's it was signed with, and returns it once.\
> \
> \- Every delivery after the call is signed with it, so update the receiver straight away. Other destinations keep theirs.\
> \- A destination whose stored configuration is unreadable is a 409.\
> \- A \`?dry\_run=true\` preview generates and writes nothing.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations:write","keys: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":{"RotatedSigningSecret":{"type":"object","description":"A webhook destination's new signing secret.","properties":{"id":{"type":"string","description":"string-encoded 64-bit id"},"signing_secret":{"type":["string","null"],"description":"The new secret. Deliveries are signed with it from now on. Null on an Idempotency-Key replay; retrieving the destination's secrets returns it again."}},"required":["id","signing_secret"]},"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"}}}},"Conflict":{"description":"Idempotency-Key reuse with a different body, or a precondition conflict.","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"}}}}}},"paths":{"/environments/{dev_id}/unified-api/destinations/{destination_id}/signing-secret/rotate":{"post":{"operationId":"rotateDestinationSigningSecret","tags":["destinations"],"summary":"Rotate a webhook's signing secret","description":"Generates a new signing secret for one webhook destination, replacing its own or the environment's it was signed with, and returns it once.\n\n- Every delivery after the call is signed with it, so update the receiver straight away. Other destinations keep theirs.\n- A destination whose stored configuration is unreadable is a 409.\n- A `?dry_run=true` preview generates and writes nothing.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"destination_id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook destination to act on, by the id its creation returned. A destination that is not a webhook is a 400."},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Rotated (or DryRunResult when ?dry_run=true; the new secret is never previewed).","content":{"application/json":{"schema":{"type":"object","anyOf":[{"$ref":"#/components/schemas/RotatedSigningSecret"},{"$ref":"#/components/schemas/DryRunResult"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Start Supabase OAuth

> Opens a Supabase pairing session and changes nothing yet: someone has to visit the \`authorization\_url\` and approve access, after which \`GET /environments/{dev\_id}/unified-api/destinations/supabase/oauth/{oauth\_session\_id}\` reports \`ready\`.\
> \
> \- The session expires after \`expires\_in\` seconds, and \`interval\` is how often to poll in the meantime.\
> \- The body is optional.\
> \- With \`return\_to: dashboard\` the browser comes back with \`supabase\_setup=success\&oauth\_session\_id=\<id>\`, or \`supabase\_setup=error\&reason=\<code>\` if the authorization failed.\
> \- Both \`return\_to\` values share one redirect\_uri, Terra's callback registered with Supabase; \`return\_to\` only picks where it sends the browser.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"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":{}},"SupabaseStartResponse":{"type":"object","properties":{"authorization_url":{"type":"string"},"oauth_session_id":{"type":"string"},"expires_in":{"type":"integer"},"interval":{"type":"integer"}}},"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"]},"SupabaseStartRequest":{"type":"object","properties":{"return_to":{"type":"string","enum":["cli","dashboard"],"description":"Where the browser lands after the user approves access. cli (the default) shows a page telling them to return to their terminal; dashboard returns to the Terra dashboard's connections page with the oauth_session_id in the query string, or with an error reason if the authorization failed. A closed set, never a URL."}}}},"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"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"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."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/supabase/oauth":{"post":{"operationId":"startSupabaseOauth","tags":["destinations"],"responses":{"200":{"description":"DryRunResult when ?dry_run=true. The authorization URL carries a session token, so previewing one would mean creating the session the preview promised not to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"201":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupabaseStartResponse"}}}},"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"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Start Supabase OAuth","description":"Opens a Supabase pairing session and changes nothing yet: someone has to visit the `authorization_url` and approve access, after which `GET /environments/{dev_id}/unified-api/destinations/supabase/oauth/{oauth_session_id}` reports `ready`.\n\n- The session expires after `expires_in` seconds, and `interval` is how often to poll in the meantime.\n- The body is optional.\n- With `return_to: dashboard` the browser comes back with `supabase_setup=success&oauth_session_id=<id>`, or `supabase_setup=error&reason=<code>` if the authorization failed.\n- Both `return_to` values share one redirect_uri, Terra's callback registered with Supabase; `return_to` only picks where it sends the browser.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupabaseStartRequest"}}}}}}}}
```

## Poll Supabase OAuth state

> Returns whether a session started with \`POST /environments/{dev\_id}/unified-api/destinations/supabase/oauth\` is \`pending\`, \`ready\` or \`failed\`.\
> \
> \- Poll at the start response's \`interval\` and give up at its \`expires\_in\`. The session reads \`pending\` until the authorization completes.\
> \- A failed authorization is a 200 carrying \`state: failed\`, not an error status.\
> \- A 404 means only that the handle is unknown or expired.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"SupabaseState":{"type":"object","properties":{"state":{"type":"string","description":"pending | ready | failed"}}},"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"}}}},"ServiceUnavailable":{"description":"A required subsystem is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/supabase/oauth/{oauth_session_id}":{"get":{"operationId":"pollSupabaseOauth","tags":["destinations"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupabaseState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Poll Supabase OAuth state","description":"Returns whether a session started with `POST /environments/{dev_id}/unified-api/destinations/supabase/oauth` is `pending`, `ready` or `failed`.\n\n- Poll at the start response's `interval` and give up at its `expires_in`. The session reads `pending` until the authorization completes.\n- A failed authorization is a 200 carrying `state: failed`, not an error status.\n- A 404 means only that the handle is unknown or expired.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"oauth_session_id","in":"path","required":true,"schema":{"type":"string"},"description":"The session handle the start step returned. It expires, so a stale handle is a 404 rather than an error naming the session."}]}}}}
```

## List Supabase projects

> Lists the Supabase projects visible to an OAuth session, each with the organization it belongs to.\
> \
> \- The session must have reached \`ready\`, or this is a 409: poll \`GET /environments/{dev\_id}/unified-api/destinations/supabase/oauth/{oauth\_session\_id}\` first.\
> \- \`meta.organizations\` lists every organization the authorization can see, so a project can be created in one that has none yet.\
> \- Pass a row's \`id\` to \`POST /environments/{dev\_id}/unified-api/destinations/supabase/provision\` as \`project\_ref\`, or an organization's \`id\` as \`create\_project.organization\_id\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"SupabaseProject":{"type":"object","description":"A Supabase project the OAuth session can see.","properties":{"id":{"type":"string","description":"The project reference. Pass it to provision as project_ref."},"name":{"type":"string"},"organization_id":{"type":"string","description":"The organization the project belongs to; its name is in meta.organizations."},"region":{"type":"string"},"status":{"type":"string","description":"Supabase's own project status, such as ACTIVE_HEALTHY or INACTIVE."}},"required":["id","name","organization_id","region","status"]},"SupabaseOrganization":{"type":"object","description":"A Supabase organization the OAuth session can see.","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"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"}}}},"Conflict":{"description":"Idempotency-Key reuse with a different body, or a precondition conflict.","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"}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/supabase/oauth/{oauth_session_id}/projects":{"get":{"operationId":"listSupabaseProjects","tags":["destinations"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SupabaseProject"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"meta":{"type":"object","properties":{"organizations":{"type":"array","description":"Every organization the authorization can see, including any without projects. create_project.organization_id must be one of these.","items":{"$ref":"#/components/schemas/SupabaseOrganization"}}},"required":["organizations"]}},"required":["data","has_more","next_cursor","meta"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Supabase's management API returned an error (code dependency_failed, with Supabase's message as the remediation), or Supabase provisioning is not available on this deployment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"summary":"List Supabase projects","description":"Lists the Supabase projects visible to an OAuth session, each with the organization it belongs to.\n\n- The session must have reached `ready`, or this is a 409: poll `GET /environments/{dev_id}/unified-api/destinations/supabase/oauth/{oauth_session_id}` first.\n- `meta.organizations` lists every organization the authorization can see, so a project can be created in one that has none yet.\n- Pass a row's `id` to `POST /environments/{dev_id}/unified-api/destinations/supabase/provision` as `project_ref`, or an organization's `id` as `create_project.organization_id`.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"oauth_session_id","in":"path","required":true,"schema":{"type":"string"},"description":"The session handle the start step returned. It expires, so a stale handle is a 404 rather than an error naming the session."}]}}}}
```

## Provision the Supabase destination

> Connects a Supabase project as a data destination, first creating the project when \`create\_project\` is sent, and returns the new \`destination\_id\`.\
> \
> \- Long-running: provisioning a project can take minutes, so allow a generous timeout rather than reading a slow response as a hang.\
> \- The destination it creates delivers every event type and is managed through the ordinary destinations endpoints from then on.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"destinations","summary":"Destinations","description":"Where Terra sends your data, such as a webhook, a database or a storage bucket, and how healthy delivery is."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations: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."}}}}},"schemas":{"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":{}},"SupabaseProvisioned":{"type":"object","properties":{"provisioned":{"type":"boolean"},"project_ref":{"type":"string","description":"The project provisioned into: the one passed, or the reference of the project created."},"project_created":{"type":"boolean","description":"Whether this call created the project."},"destination_id":{"type":"string","description":"Id of the created Supabase data destination (string-encoded). It delivers every event type; manage it, including narrowing its event_types, via the destinations CRUD."},"database_password":{"type":["string","null"],"description":"The new project's database password, returned once, by the call that connects the project it created. Terra holds it on the OAuth session only until then. Null when no project was created, and in an Idempotency-Key replay."},"replaced_destination_id":{"type":["string","null"],"description":"The destination deleted in place of replace_destination_id. Null when none was requested, or when that delete failed after the new destination was written; delete it through the destinations endpoint then."}},"required":["provisioned","project_ref","project_created","destination_id","database_password","replaced_destination_id"]},"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"]},"SupabaseProvisionRequest":{"type":"object","properties":{"oauth_session_id":{"type":"string","description":"The session handle the start step returned. Required. It must have reached the ready state, and not be provisioning or have provisioned already, or this is a 409; the Supabase access token stays server-side and is never sent here."},"project_ref":{"type":"string","description":"An existing Supabase project to provision into: the id of a row from the projects step. Its status must not be paused, failed or removed, or this is a 422. Send exactly one of project_ref and create_project."},"project_name":{"type":"string","description":"Display only, with project_ref; defaults to the project's Supabase name. Not accepted with create_project, which names the project itself."},"create_project":{"description":"A new project to create in one of the session's organizations and provision into. Send exactly one of project_ref and create_project. Supabase may bill for the new project. Its database password is generated by Terra and returned once in the response, so send an Idempotency-Key: once a call succeeds, a retry with the same key returns the stored result with database_password null. If a call fails after Supabase created the project, retrying the same create_project on the same session resumes that project instead of creating a second one, and returns its password once it is connected.","$ref":"#/components/schemas/SupabaseCreateProject"},"replace_destination_id":{"type":"string","description":"An existing Supabase destination in this environment to delete once the new one is written, such as a placeholder being replaced. A destination outside this environment is a 404 and one of another type a 400, both before anything is created."}},"required":["oauth_session_id"]},"SupabaseCreateProject":{"type":"object","description":"A new Supabase project to create and connect.","properties":{"name":{"type":"string","description":"The new project's name."},"organization_id":{"type":"string","description":"The organization to create it in. It must be one listed in meta.organizations by the projects step, or this is a 400."},"region":{"type":"string","description":"The Supabase region to create it in, such as us-east-1. Required; there is no default."}},"required":["name","organization_id","region"]}},"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"}}}},"Conflict":{"description":"Idempotency-Key reuse with a different body, or a precondition conflict.","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"}}}}},"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."}}},"paths":{"/environments/{dev_id}/unified-api/destinations/supabase/provision":{"post":{"operationId":"provisionSupabase","tags":["destinations"],"responses":{"200":{"description":"DryRunResult when ?dry_run=true. The OAuth session, its readiness, the project reference and its status, or the new project's organization, and any destination to replace are all validated, so the preview refuses what the call would refuse; nothing is created or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResult"}}}},"201":{"description":"Provisioned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupabaseProvisioned"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"The project_ref names a project that is paused, or that failed or was removed, so it cannot be provisioned into until it is restored or repaired in Supabase (code unsupported_operation, with the project's status in the remediation). Retrying unchanged returns the same error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Supabase's management API returned an error (code dependency_failed, with Supabase's message as the remediation), or Supabase provisioning is not available on this deployment. When a project was created but could not be connected, the remediation names its reference to retry with as project_ref.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}},"summary":"Provision the Supabase destination","description":"Connects a Supabase project as a data destination, first creating the project when `create_project` is sent, and returns the new `destination_id`.\n\n- Long-running: provisioning a project can take minutes, so allow a generous timeout rather than reading a slow response as a hang.\n- The destination it creates delivers every event type and is managed through the ordinary destinations endpoints from then on.","parameters":[{"$ref":"#/components/parameters/DevId"},{"$ref":"#/components/parameters/DryRun"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupabaseProvisionRequest"}}}}}}}}
```
