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

# Overview

Configure a Terra account and every product on it with a personal access token.

The Admin API configures your Terra account: environments, Unified API sources and destinations, events, Lab Reports, Vantage, team, billing and tokens. It does not serve your end users' health data. The [Terra CLI](https://docs.tryterra.co/developer-tools/terra-cli/terra-cli) and the [MCP server](https://docs.tryterra.co/developer-tools/mcp-server) are both built on it.

```
https://access.tryterra.co/api/v3/admin
```

The full list of public endpoints is the [Admin API OpenAPI spec](https://raw.githubusercontent.com/tryterra/openapi/refs/heads/master/dist/core/admin-bundled.yaml).

## Authentication

Send a [personal access token](https://docs.tryterra.co/reference/admin-api/personal-access-tokens.md) as a bearer token. The Admin API accepts only personal access tokens (`terra_at_`). A dev ID and API key, or a data token (`terra_dt_`), is rejected here, and a personal access token is rejected by the data APIs.

```bash
curl https://access.tryterra.co/api/v3/admin/environments \
  -H "Authorization: Bearer <TOKEN>"
```

`<TOKEN>` comes from `terra login`, from connecting an MCP client, or from **Settings > Personal Access Tokens** in the dashboard. A route that acts on one environment takes its dev ID in the path, as `/environments/{dev_id}/…`. There is no header or body field for it.

## Endpoints

In this table, `…` stands for `/environments/{dev_id}`.

| Area                     | Routes                                                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account                  | `/me`, `/company`, `/environments`, `/entitlements`                                                                                                                                               |
| Team                     | `/team/members`, `/team/invitations`                                                                                                                                                              |
| Billing                  | `/billing/subscriptions`, `/billing/invoices`, `/billing/invoice-details`, `/billing/payment-method`, `/billing/usage`                                                                            |
| Tokens and keys          | `/tokens`, `…/tokens`, `…/api-key`                                                                                                                                                                |
| Unified API sources      | `…/unified-api/source-types`, `…/unified-api/sources`                                                                                                                                             |
| Unified API destinations | `…/unified-api/destination-types`, `…/unified-api/destinations`                                                                                                                                   |
| Unified API data         | `…/unified-api/data-types`, `…/unified-api/scopes`, `…/unified-api/processing`, `…/unified-api/scores`, `…/unified-api/widget/config`                                                             |
| Events                   | `…/events`, `…/event-types`                                                                                                                                                                       |
| Users and test users     | `…/users`, `…/synthetic-users`                                                                                                                                                                    |
| Lab Reports              | `…/lab-reports/api-version`                                                                                                                                                                       |
| Vantage                  | `…/vantage/api-version`, `…/vantage/markets`, `…/vantage/catalogue`, `…/vantage/products`, `…/vantage/variants`, `…/vantage/webhook`, `…/vantage/events`, `…/vantage/orders`, `…/vantage/results` |
| Models                   | `/models/catalog`, `…/models/runs`                                                                                                                                                                |
| Workouts                 | `…/workouts/metadata`                                                                                                                                                                             |
| Diagnostics              | `…/doctor`, `…/unified-api/destinations/health`                                                                                                                                                   |

## Scopes

Each endpoint needs a [scope](https://docs.tryterra.co/reference/admin-api/scopes.md), and the token must hold it. A token without it gets `403` with `code: scope_missing`.

## Dry run

Every write that needs a write or admin scope accepts `?dry_run=true`. A dry run runs the same checks as the real call and fails the same way, but writes, sends and bills nothing. It returns `200` with what the call would do. Values that exist only after the write, such as a new secret, are left out and flagged with `will_return_*`.

```bash
curl -X POST "https://access.tryterra.co/api/v3/admin/environments/<DEV_ID>/unified-api/destinations?dry_run=true" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"type": "webhook", "config": {"url": "https://example.com/terra"}, "event_types": ["activity"]}'
```

```json
{
  "dry_run": true,
  "would": "create",
  "preview": {
    "type": "webhook",
    "url": "https://example.com/terra",
    "active": true,
    "event_types": ["activity"],
    "configured": true,
    "missing": [],
    "config": { "url": "https://example.com/terra", "delivery": "push" },
    "will_return_signing_secret": true
  }
}
```

In the CLI, pass `--dry-run`. In the MCP server, pass `dry_run: true`.

## Errors

Errors are `application/problem+json` with a stable `code`. Branch on `code`, not on the message.

```json
{
  "type": "about:blank",
  "title": "forbidden",
  "detail": "token is missing the required scope: providers:write",
  "instance": "/api/v3/admin/environments/<DEV_ID>/unified-api/sources/garmin",
  "code": "scope_missing",
  "remediation": "Request a new token that includes providers:write (device flow or dashboard) and approve the additional scope."
}
```

A `400` with `code: validation_failed` also lists each field at fault in `errors`.

| Status | Common codes                                                                           | Meaning                                                                       |
| ------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `400`  | `validation_failed`                                                                    | The request is invalid.                                                       |
| `401`  | `unauthorized`, `token_expired`                                                        | The token is missing, unknown, expired or revoked.                            |
| `403`  | `scope_missing`, `audience_restricted`, `entitlement_required`, `environment_disabled` | The token lacks a scope or the environment, or the account lacks the product. |
| `404`  | `not_found`, `dev_id_not_found`                                                        | Not found, or not yours.                                                      |
| `409`  | `conflict`, `idempotency_key_reuse`, `token_limit_reached`                             | The request conflicts with the current state.                                 |
| `410`  | `endpoint_moved`                                                                       | The route moved. `detail` names the new path.                                 |
| `429`  | `rate_limited`                                                                         | Too many requests. See [Rate limits](#rate-limits).                           |
| `503`  | `authorization_unavailable`, `service_unavailable`                                     | Try again shortly.                                                            |

## Pagination

List endpoints return a page of results:

```json
{ "data": [], "has_more": true, "next_cursor": "<CURSOR>" }
```

Pass `next_cursor` back as `?cursor=` to get the next page. It is `null` on the last page. `limit` sets the page size, and a value above the endpoint's maximum is lowered to it. Endpoints that support sorting take `order_by` and `order` (`asc` or `desc`, default `desc`).

## Rate limits

Each token has its own budgets for reads and for writes, and the doctor has its own. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Over the limit, the API returns `429` with `code: rate_limited` and a `Retry-After` header in seconds.

## Idempotency

Writes accept an `Idempotency-Key` header. Retrying with the same key and body within 24 hours returns the stored response with `Idempotency-Replayed: true` instead of running the write again. The same key with a different body returns `409` with `code: idempotency_key_reuse`. A dry run ignores the key.

```bash
curl -X POST https://access.tryterra.co/api/v3/admin/environments/<DEV_ID>/tokens \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "backend", "scopes": ["data:read"]}'
```

A replay does not return the secret again. `token` on a data token, `signing_secret` on a webhook and `database_password` on a Supabase destination are `null` in a replayed response.

## See also

* [Personal access tokens](https://docs.tryterra.co/reference/admin-api/personal-access-tokens.md)
* [Scopes](https://docs.tryterra.co/reference/admin-api/scopes.md)
* [Environment doctor](https://docs.tryterra.co/reference/admin-api/environment-doctor.md)
* [MCP server](https://docs.tryterra.co/developer-tools/mcp-server)
