api-reference.md

# API Reference

Terrapod implements the subset of the TFE V2 API that the `terraform`/`tofu` `cloud` backend consumes (over the `go-tfe` protocol) — a stable contract mounted at `/api/tfe/v2/` and catalogued in [`tfe-cli-surface.md`](tfe-cli-surface.md). It is **not** a reimplementation of the full TFE V2 API: everything beyond that CLI-consumed slice is Terrapod's own native API at `/api/v1/`. All endpoints use JSON:API format.

The interactive API documentation is also available in the web UI under **API** in the navigation bar, offering both ReDoc and Swagger UI views.

![API Documentation (ReDoc)](images/api-docs-redoc.png)

---

## Consumers

The Terrapod API has four distinct consumer classes. Every API change must update every affected consumer — this is a hard contract:

1. **Web UI** (`web/`) — Next.js BFF + React frontend. Server-side SSR + client-side `fetch()`. Frontend changes when JSON:API attribute names, endpoint paths, or response shapes change.
2. **go-terrapod** (`go-terrapod/`) — the **canonical Go SDK**. Strongly-typed methods over the Terrapod JSON:API surface. Single source of truth for the Go view of the API: the provider and migration tool both import it; third-party Go automation can import it directly (`github.com/mattrobinsonsre/terrapod/go-terrapod`). Same shape and stability story as `hashicorp/go-tfe`.
3. **terraform-provider-terrapod** (`provider/`) — a **thin wrapper around go-terrapod**. The provider holds only Terraform-plugin-framework code (schema, state translation, lifecycle hooks); every API call goes through go-terrapod. No JSON:API marshalling code lives inside `provider/internal/`.
4. **terrapod-migrate** (`migrate/`) — the **migration tool** that moves TFE/HCP + Atlantis platforms onto Terrapod. Reads from the source via `go-tfe` (TFE migrations) or local-clone HCL parsing (Atlantis migrations). Writes to Terrapod via go-terrapod. Distributed as a universal-macOS + linux/windows amd64+arm64 GitHub Release artifact.

### Workflow for extending the API

1. Add the endpoint to the appropriate Python router (`services/terrapod/api/routers/*.py`).
2. Add a typed method on go-terrapod (`go-terrapod/<resource>.go`) + tests.
3. Update each consumer that needs it: the provider's resource file, the frontend page, or the migration tool's writer.

### Endpoint coverage

go-terrapod targets the full Terrapod API surface — both the TFE-V2-compatible (`/api/tfe/v2/`) and Terrapod-native (`/api/v1/`) prefixes. The migration tool is a heavy consumer of the API-only routers (config-versions, state-management, registry endpoints) that the UI doesn't surface; the provider mostly consumes the frontend-also routers. Both can rely on the same typed surface in go-terrapod.

### Version contract

go-terrapod pins to a specific Terrapod API version at build time via the `SDKVersion` constant and exposes `Client.VersionCheck` so a consumer can fail-fast on a version mismatch. Releases of Terrapod, go-terrapod, the provider, and the migration tool all happen at the same tag — they ship together, so keeping the CLIs and the server on matching versions avoids schema drift.

---

## Base URL and Authentication

### Base URL

Terrapod exposes two API surfaces, each with a deprecated alias:

| Prefix | Contract | Audience |
|---|---|---|
| `/api/tfe/v2/` | **Stable** TFE V2 subset consumed by `terraform`, `tofu`, and `tfci`. Documented in [`docs/tfe-cli-surface.md`](tfe-cli-surface.md). |  Terraform/OpenTofu CLI, `tfci`, `go-tfe`-based clients that stay within this subset |
| `/api/v1/` | Terrapod-native management API (workspaces management, runs, registry CRUD, agent pools, audit, etc.) | Web UI, the Terraform provider for Terrapod, automation |
| `/api/terrapod/v1/` | **Deprecated alias** for the above — every route, identical responses. Kept for the support window; see [`deprecations.md`](deprecations.md). | Existing integrations, and Terrapod's own runner/listener images until they are upgraded |
| `/api/tfe/v2/` | **Stable** TFE V2 subset consumed by `terraform`, `tofu` and `tfci`. Named for what it is: a compatibility layer for another product's protocol, kept out of Terrapod's own version namespace. | Terraform/OpenTofu CLI, `tfci`, `go-tfe` clients |
| `/api/v2/` | **Deprecated alias** for the TFE surface — every route, identical responses. Advertised in service discovery until v1.7.0; still served. | Existing clients, and runner images until upgraded |

Example:

```
# CLI-contract (cloud-block, state, etc.)
https://terrapod.example.com/api/tfe/v2/organizations/default/workspaces

# Terrapod-native management
https://terrapod.example.com/api/v1/workspaces
```

A handful of endpoints (e.g. `/health`, `/ready`, `/.well-known/terraform.json`, OAuth flows, `/v1/...` registry CLI protocol) live at the root for protocol-compatibility reasons.

> **`/api/terrapod/v1/` still works.** It serves the same routes as `/api/v1/`,
> from the same code, so nothing breaks if you have not migrated. Prefer
> `/api/v1/` in anything new. The one place the alias does **not** apply is the
> SSO callback URL, which your identity provider validates against its own
> allow-list — that is governed by `auth.legacy_callback_url` and explained in
> [`deprecations.md`](deprecations.md).

### Authentication

Include a Bearer token in the `Authorization` header:

```
Authorization: Bearer <api-token-or-session-token>
```

API tokens are obtained via `terraform login`, the web UI, or the token creation endpoint. Session tokens are obtained via the login flow.

### Content Type

Requests with a body should use:

```
Content-Type: application/vnd.api+json
```

Responses use `application/json` (accepted by `go-tfe`).

### Organization

Terrapod is single-organization. The literal organization name `default` is the only valid value; every API path that contains an organization segment uses `organizations/default/` verbatim. Requests to any other organization name return 404.

### Pagination

List (collection `GET`) endpoints support **optional** pagination and always return a `meta.pagination` block:

| Query param | Meaning |
|---|---|
| `page[size]` | Items per page. `>= 1` returns that page (capped at **100**). **`0` — or omitting paging entirely — returns the full list** as a single page. |
| `page[number]` | 1-indexed page to return (default `1`). Only meaningful with `page[size] >= 1`. A page past the end returns an empty `data` array, not an error. |

Every list response carries pagination metadata in Terrapod's four-key shape:

```json
{
  "data": [ /* ... */ ],
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 100,
      "total-count": 250,
      "total-pages": 3
    }
  }
}
```

Notes:

- **Absent params → full list.** Omitting `page[size]` (or sending `page[size]=0`) returns every item, so a client that just wants the whole collection can ignore paging entirely. This is a deliberate Terrapod behaviour; on `/api/tfe/v2/` the `meta.pagination` shape still matches what a `go-tfe` client expects.
- **To fetch everything robustly, page and loop** rather than relying on the absent-params default — request `page[size]=100`, then `page[number]=1,2,…` until `total-pages` is reached. go-terrapod exposes `ListAll*` helpers that do this; the web UI uses `fetchAllPages()`.
- **Unbounded-history collections are the one exception:** the runs list (`GET /api/tfe/v2/workspaces/{id}/runs`) keeps a **bounded default page (20)** instead of returning all history, but still honours `page[size]` and emits `meta.pagination` so you can page the full history.
- `total-count` is the size of the whole (RBAC-filtered) collection, not the returned page.

---

## Health Check Endpoints

### Liveness Probe

```
GET /health
```

Returns 200 if the API process is running.

**Response:**
```json
{"status": "healthy"}
```

### Readiness Probe

```
GET /ready
```

Checks database, Redis, and storage subsystems. Returns 200 if all healthy, 503 otherwise.

**Response (healthy):**
```json
{
  "status": "ready",
  "checks": {
    "database": "healthy",
    "redis": "healthy",
    "storage": "healthy"
  }
}
```

---

## Service Discovery

### Terraform Service Discovery

```
GET /.well-known/terraform.json
```

Returns service discovery document for `terraform login` and registry protocol.

**Response:**
```json
{
  "login.v1": {
    "client": "terraform-cli",
    "grant_types": ["authz_code"],
    "authz": "/oauth/authorize",
    "token": "/oauth/token",
    "ports": [10000, 10010]
  },
  "modules.v1": "/api/tfe/v2/registry/modules/",
  "providers.v1": "/api/tfe/v2/registry/providers/"
}
```

---

## Ping

```
GET /api/tfe/v2/ping
```

API version handshake. Returns TFE-compatible version headers.

**Response headers:**
```
TFP-API-Version: 2.6
TFP-AppName: Terrapod
X-TFE-Version: v202301-1
```

---

## Account

### Current User Details

```
GET /api/tfe/v2/account/details
```

Returns the authenticated user's information.

**Response:**
```json
{
  "data": {
    "id": "user-abc123",
    "type": "users",
    "attributes": {
      "username": "alice@example.com",
      "email": "alice@example.com",
      "is-service-account": false
    }
  }
}
```

---

## Organizations

### Show Organization

```
GET /api/v1/organizations/default
```

Returns organization details. Only `default` is valid.

### Entitlement Set

```
GET /api/tfe/v2/organizations/default/entitlement-set
```

Returns feature flags (all enabled for Terrapod).

---

## Workspaces

### List Workspaces

```
GET /api/v1/workspaces                                # native — every enabled engine
GET /api/tfe/v2/organizations/default/workspaces      # TFE-compatible — Terraform only
```

Supports optional [pagination](#pagination) (`page[size]`/`page[number]`; absent or `page[size]=0` returns the full list) and filtering by `search[name]` and cloud-block tags (`filter[tagged][...]`). Results are scoped to workspaces the caller can read.

The native list also takes `filter[engine]` (`terraform`, `pulumi`, …). A workspace whose engine is turned off on this deployment is absent from it, not listed and refused; turning the engine back on brings it back unchanged. The TFE-compatible list never returns a non-Terraform workspace — a `terraform` CLI cannot use one.

### Get Workspace by Name

```
GET /api/v1/workspaces/{name}                         # native — every enabled engine
GET /api/tfe/v2/organizations/default/workspaces/{name}
```

A Pulumi workspace is named `project::stack` and is read the same way (`GET /api/v1/workspaces/proj::dev`).

### Get Workspace by ID

```
GET /api/v1/workspaces/{id}                           # native — every enabled engine
GET /api/tfe/v2/workspaces/{id}                       # TFE-compatible — Terraform only
```

The native read answers **404** both for a workspace that does not exist and for one the caller cannot read, so a lookup by name reveals nothing about names the caller has no access to.

### List Engines

```
GET /api/v1/engines
```

The engines this deployment enables, as `{"data": [{"type": "engines", "id": "pulumi", ...}, {"type": "engines", "id": "terraform", ...}]}`. `terraform` is always present. An engine that is turned off is absent from the list, not listed and then refused. The web UI shows engine choices (the create form's picker and the list's engine filter) only when more than one engine is enabled, so a Terraform-only deployment shows no engine UI at all.

### Create Workspace

```
POST /api/v1/workspaces                              # native — carries `engine`
POST /api/tfe/v2/organizations/default/workspaces    # TFE-compatible — Terraform only
```

Both accept the same attributes and return the same workspace. They differ in
one respect: only the native route accepts an **`engine`**.

**Workspaces are created here, in the UI, or with the Terraform provider — never
by an engine's own CLI.** `terraform init` has always looked a workspace up and
failed if it was absent, and the same is true of `pulumi stack init`, which
refuses and names this endpoint. A CLI that could create a workspace would be
creating a platform resource with no RBAC review and no record of its origin.

**`engine`** — the execution engine family: `terraform` (the default when
omitted) or another engine the deployment enables. Distinct from
`execution-backend`, which picks the binary *within* the Terraform engine (tofu
or terraform). An engine that is disabled is refused with 422, and the message
lists the engines this deployment offers.

A **Pulumi** workspace is named `project::stack`, because that is what
`pulumi stack select default/{project}/{stack}` resolves to; a single-part name
is rejected rather than accepted and then never found by the CLI.

The TFE-compatible route is Terraform-only by design and ignores an `engine`
attribute: it is the CLI compatibility contract, and a client there cannot see a
workspace belonging to another engine.

**Auto-apply modes (`auto-apply-mode`)**

| Mode | Applies automatically when |
|---|---|
| `never` | Never — every plan waits for a human. |
| `always` | Always, on any successful plan. |
| `create` | The plan only **adds** resources. |
| `create_update` | The plan only adds resources and **updates them in place**. |

`create` and `create_update` never auto-apply a plan that **destroys or
replaces** a resource — that run stays `planned` for a human, and the run's
`auto-apply-declined-reason` says why (for example `2 destroys, 1 replace`).

Because those two modes need to know the shape of the plan, they are decided
once the plan JSON has been uploaded — a moment later than `always`, which is
decided as soon as the plan finishes. If the plan JSON never arrives, the run
is left for a human rather than applied.

`auto-apply` is retained as the boolean projection: it reads `true` for any
mode that auto-applies at all, and writing it still works (`true` → `always`,
`false` → `never`). Setting **both** `auto-apply` and `auto-apply-mode` in one
request is rejected with `422` rather than guessing which was meant.

Runs carry the decision too: `auto-apply-mode` is the mode snapshotted when the
run was created (editing the workspace mid-run cannot retroactively change how an
in-flight run decides), and `auto-apply-declined-reason` says why a conditional
mode refused this plan — for example `2 destroys, 1 replace`. It is null unless
the run was actually held.

The bulk-update endpoint (`POST /api/v1/workspaces/actions/bulk-update`)
and the autodiscovery rule template both accept `auto-apply-mode` under the same
either/or rule.

**Request body:**
```json
{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name": "my-workspace",
      "auto-apply": false,
      "auto-apply-mode": "create_update",
      "execution-mode": "agent",
      "engine": "terraform",
      "engine-version": "1.9.8",
      "resource-cpu": "1",
      "resource-memory": "2Gi",
      "labels": {
        "env": "dev",
        "team": "platform"
      },
      "vcs-repo-url": "https://github.com/org/repo",
      "vcs-branch": "main",
      "working-directory": "terraform/",
      "drift-detection-enabled": false,
      "drift-detection-interval-seconds": 86400
    },
    "relationships": {
      "vcs-connection": {
        "data": {
          "id": "vcs-abc123",
          "type": "vcs-connections"
        }
      }
    }
  }
}
```

Create accepts the same settings `PATCH` does, including `vcs-workflow`, `auto-merge`, `auto-merge-strategy`, `ai-summary-mode` and `ai-summary-context`. Before #1763 those five were **silently dropped** on create — accepted with a `201` and ignored — so a configuration asking for `apply_then_merge` quietly got `merge_then_apply`. They are now read and validated by the same rules `PATCH` uses, including `apply_then_merge`'s requirement for a VCS connection and auto-apply off.

**Required permission:** Any authenticated user can create workspaces (creator becomes owner).

<a id="workspace-write-refusals"></a>

#### Refusals on create and update

Create is open to any authenticated user and the creator becomes owner, so two
things a caller chooses in the body are grants rather than preferences. Both are
checked on **create** and on **`PATCH`**, and both answer **403**.

| Refusal | When | What to do |
|---|---|---|
| Not authorized to use VCS connection `vcs-…` | The body names a connection the caller has no claim to. Checked on create, and on update only when the connection actually **changes**. Both the `vcs-connection-id` attribute and the `vcs-connection` relationship are covered. | Ask a platform admin to set the connection's `owner-email` or `labels`, or create the workspace under someone who already has a claim. See [Authorization and repository scope](#connection-authorization-attributes). |
| Connection `vcs-…` is restricted to specific repositories and `…` is not one of them | The named connection has a non-empty `allowed-repositories` that `vcs-repo-url` does not match. Re-checked on **every** update that leaves a connection attached, since `vcs-repo-url` is separately settable. | Use a repository inside the connection's scope, or ask a platform admin to widen `allowed-repositories`. |
| This change would make the workspace match the assignment rule of variable set `…` | The attributes being set would pull in a **rule-assigned** variable set **that carries a sensitive or broker-resolved value** and is not already reaching this workspace, and the caller is not a platform admin. A rule-assigned set of plain configuration joins freely — the refusal is scoped to the reported impact, because refusing every match would close the documented self-service workflow as well as the finding. | Ask a platform admin to make the change, or to assign the set to the workspace explicitly. See [Assignment Rules](#assignment-rules). |

The variable-set refusal compares the rule-assigned sets reaching the workspace
**before and after** the pending change, so:

- **shrinking is allowed** — dropping a label that was pulling a set in is a
  de-escalation and needs no admin;
- an **unrelated edit** to a workspace that already matches is allowed; the test
  is growth, not membership;
- **global** and **explicitly-assigned** sets never count. A global set already
  reaches every workspace, and an explicit assignment was an admin's deliberate
  act on this workspace;
- a refusal is **atomic**: the change is rolled back, so a refused create leaves
  no workspace behind.

The refusal names the variable sets it would have pulled in — the names are not
secret, the values are.
### `ansible-version`

The ansible-core **line** whose execution environment this workspace's configure
operations run in — a deployment default that a workspace may override, exactly
as it overrides its engine version. Collection compatibility is a per-workspace
concern, so one version for the whole deployment would be the wrong shape.

**It governs the workspace's configure operations only, not how Terrapod reads
its inventory** (#2172). The API carries one `ansible-core`, pinned as a line in
its own image, and uses it to resolve every workspace's inventory; nothing is
installed per workspace and no operator setting chooses it, because the API's
ansible is a property of the API image. An earlier arrangement did install a
per-workspace version in the API — that is removed, and this value's only job is
to select which execution-environment image a configure runs in.

| | |
|---|---|
| **Type** | string |
| **Default** | The platform's current ansible-core **line** (`DEFAULT_ANSIBLE_LINE`), written at create time. Changing it moves only workspaces created afterwards — existing ones keep what they carry, exactly as the engine version does. Use bulk update to move a fleet. It is a line (`2.21`), not a patch, because Terrapod publishes one execution-environment image per ansible-core line and the line names the image. |
| **Empty means** | inherit the deployment default. A row predating this attribute reads back empty; a workspace created normally carries a concrete version. |
| **Accepted** | any non-empty string, subject to two checks. The deployment's pre-release policy applies, so `binary_cache.allow_prerelease: none` 422s `2.21.5rc1` and allows `2.21.5`. And a line with **no published execution environment is refused** — but only when Terrapod can determine which lines exist: the set is read from a container registry, so when it cannot be read the value is accepted rather than making a workspace edit depend on registry reachability. There is deliberately no *format* rule; `engine-version` has none either. |
| **Not resolved** | a partial is not expanded to a newest matching release, unlike `engine-version`. The value names an image tag, and Terrapod publishes one tag per line — so `2.21` is the ordinary thing to write. An exact patch is accepted and names its own line. `latest` is not a line and has no image. |
| **See also** | [`GET /api/v1/ansible/execution-environments`](#get-apiv1ansibleexecution-environments) for which lines this deployment can run. |

**A read returns the workspace's own value.** The deployment default is not
substituted in for an empty one, because a client that wrote a read straight
back would then pin every workspace to whatever the default happened to be at
read time — the same reason `oidc_audiences` reconciles only the keys a
practitioner declared.

Settable on workspace create, workspace update, bulk update, and as an
autodiscovery rule template field.

### `ansible-execution-environment`

One of the deployment's **own** execution environments, named by label, which
**overrides `ansible-version` outright** — a workspace carrying a label ignores
its line, so setting a line on such a workspace changes nothing about what runs.

A label rather than an image reference for two reasons: a workspace cannot then
name an arbitrary image, and the estate is re-pointed in one place when the
image moves. The labels come from `api.config.ansible.execution_environments`;
see [Choosing an execution environment](runners.md#choosing-an-execution-environment)
for what an image must provide and what supplying one means.

It is a **separate attribute rather than an overloaded `ansible-version`**, and
that is measured rather than aesthetic: the pre-release screen is the only rule
`ansible-version` applies, so a label passes it unchanged — and a label named
`2.21` would shadow a real ansible-core line with nothing to distinguish them.

| | |
|---|---|
| **Type** | string |
| **Default** | `""` |
| **Empty means** | no operator environment; run the built-in image for `ansible-version`. This is the ordinary case. |
| **Accepted** | any label configured on this deployment, at most 100 characters. A label that is **not** configured is always a 422 — the map is local configuration, so unlike a line there is no "cannot tell". |
| **Stored** | byte for byte. Nothing is trimmed or case-folded, because a Terraform provider writes the response back into state and a normalised value fails the apply with "Provider produced inconsistent result after apply". |

Settable on workspace create, workspace update, bulk update, and as an
autodiscovery rule template field.

### `ansible-collections`

The Ansible collections a configure installs, declared on the platform rather
than only in the configuration's own `requirements.yml`.

`ansible-core` ships no collections, so every playbook beyond the builtins
depends on content fetched at run time. That makes this a **supply-chain
declaration**, not a convenience: declared here it is visible in a plan, governed
by workspace RBAC, carried in the audit log, and settable across a fleet by bulk
update. Left only in the repository it is whatever somebody committed.

| | |
|---|---|
| **Type** | list of objects, each `{"name": "namespace.name"}` with an optional `"version"` |
| **Default** | `[]` — no collections declared, and the configuration's own `requirements.yml` is the only source |
| **Accepted** | `name` must be a Galaxy coordinate: `namespace.name`, lowercase letters, digits and underscores. `version` is any non-empty string — a pin or a range (`>=1.0.0,<2.0.0`), as in ansible's own file. A duplicate collection name is refused, as are `source` and `type` |
| **Refused, not normalised** | the list is stored exactly as declared. Nothing is lowercased, trimmed, reordered or de-duplicated, because a Terraform provider writes the server's response back into state and a reshaped value fails every apply with "Provider produced inconsistent result after apply" |
| **Ceiling** | 50 entries. Past that the list has stopped being platform configuration and the configuration's own requirements file is the right home |

**Merged OVER the configuration's own requirements, keyed on collection name.**
The repository's requirements file is installed first, then this list with
`--force`, so a workspace entry replaces the repository's build of that
collection and every other repository entry stands. The platform is the later
word — the same relationship a workspace variable has to a default committed in
the configuration.

**Why an override rather than a joint resolution.** Handed two constraints for
one collection, ansible's resolver refuses (`Requirements conflict: …`) rather
than preferring either, so a merged document cannot express "the platform wins".
Order plus `--force` can. The cost is that the two sets are not
dependency-resolved together: a workspace pin that breaks a repository
collection's own requirement is taken as the operator's declared intent.

**Collections only — roles are a different mechanism.** A collection is usually
external, so it comes through Terrapod's Galaxy surface: its own published
collections answered from the registry, upstream ones proxied, which is what lets
a runner in a restricted network install one with no route to
`galaxy.ansible.com`. A role is usually in-house, so it comes from git using the
workspace's own `git_http_auth` / `git_ssh_auth` credentials, declared in the
configuration's `requirements.yml` under `roles:` and installed alongside these.
Both kinds work either way, with one exception: a **Galaxy-hosted role** uses the
v1 roles API, which Terrapod does not serve, so in a sealed deployment use a git
source or vendor the role into a collection.

Settable on workspace create, workspace update, bulk update, and as an
autodiscovery rule template field.

### The operations a workspace has

A workspace declares which operations it has with two independent booleans.

| Attribute | Type | Default | Meaning |
|---|---|---|---|
| `plan-apply-enabled` | bool | `true` | The workspace has a plan/apply operation — the ordinary OpenTofu, Terraform or Pulumi run |
| `configure-enabled` | bool | `false` | The workspace has a configure operation — an Ansible run against the workspace's inventory |

**The defaults are the compatibility story.** Plan/apply on and configure off
means every workspace that predates these attributes behaves exactly as it did,
with no data step, and a configure operation is something an operator opts into.

**Two booleans rather than one enum or a delimited string**, because the states
are genuinely independent and all the useful combinations are reachable without
anything having to be parsed. A value that must be parsed and kept in step
across the API, the provider, MCP and the UI eventually gets mistyped into a
third meaning; a pair of booleans cannot be.

**Both false is refused with a 422** — on create, on update, and in bulk update.
A workspace with neither operation can never produce a run, so the state's only
honest meaning is "I did not mean to do that". To park a workspace, use
[Lock Workspace](#lock-workspace) — that is reversible and says what it means.
The refusal names both attributes:

```
a workspace must have at least one operation: set plan-apply-enabled or configure-enabled (or both)
```

On **update** and **bulk update** the rule is evaluated against the row the write
would produce, not against the submitted attributes alone — so turning
`plan-apply-enabled` off is accepted on a workspace that already has
`configure-enabled` set and refused on one that does not. Bulk update evaluates
each matched workspace's own merged row, which is what stops a fleet-wide change
from being legitimate for some of the matched workspaces and a silent
no-op-forever for the rest.

Both are on the **native surface only** (`/api/v1` and the deprecated
`/api/terrapod/v1` alias). They are deliberately absent from the TFE-compatible
prefix, which is engine-filtered to Terraform and never learns about the other
engines — and the name `operations` was unavailable there in any case: it is
TFE's own frozen boolean for whether a workspace uses remote operations, served
from `execution-mode`.

Settable on workspace create, workspace update, bulk update, and as autodiscovery
rule template fields. A rule's `configure-enabled` is what decides whether the
workspaces it materialises have a configure operation.

### The configure-operation attributes

These attributes name where a workspace's Ansible configuration lives and what a
configure operation does by default. They are on the **native surface only**
(`/api/v1` and the deprecated `/api/terrapod/v1` alias) and are deliberately
**not** on the TFE-compatible prefix — no `terraform`, `tofu` or `tfci`
invocation consumes them.

| Attribute | Type | Meaning |
|---|---|---|
| `config-directory` | string | The Ansible config root — `ansible.cfg`, playbooks, `roles/`, `group_vars/`, `host_vars/` — relative to the configuration version's root, with `""` meaning that root. Also the directory the resolver and the executor **run in** |
| `inventory-paths` | list of strings | The inventory sources, in order, each a file or a directory, relative to `config-directory`. Empty falls through to the `inventory` pathlist in the operator's own `ansible.cfg` |
| `default-playbook` | string | The playbook a configure runs when the run names none |
| `default-limit` | string | The default `--limit`. Empty is the whole inventory |
| `inventory-include-platform` | bool | Whether the declared inventory rows take part in resolution. Default `true`; `false` resolves the repository source alone |
| `inventory-ignore-paths` | list of strings | Paths pruned from a fetched inventory source before ansible reads it. Ansible takes every file in a directory, so this is the only way to leave one out |

**`config-directory` is an ordinary path with no null state**, exactly like
`working-directory` beside it: `""` means the configuration version's root, and
that is its default. Whether the workspace *has* a configure operation is
[`configure-enabled`](#the-operations-a-workspace-has), not the absence of a
path.

It was nullable when it shipped, with `null` standing for "this workspace has no
configure operation". That made one field answer both where the configure
operation runs and whether there is one, and left `""` and `null` as two
distinguishable values for a path whose natural default is the root it is
relative to. **Sending `null` is now a 422 naming the field, not a clear** — it
is refused rather than coerced to `""`, because a server that silently rewrites a
submitted value makes a Terraform provider's plan disagree with its result.

**The VCS binding is the workspace's own.** There is no separate binding for the
inventory: it uses `vcs-connection-id`, `vcs-repo-url` and `vcs-branch` like
everything else. Terraform and Ansible in different repositories is not
supported, so what differs between the two concerns is the **root** —
`working-directory` against `config-directory` — not the repository.

**`config-directory` is fetched whole, and that is not an optimisation to
reverse.** Measured against ansible-core 2.18.3, `group_vars` and `host_vars`
are found in exactly two places: inside the inventory directory, or at the
working directory — never merely *beside* the inventory directory, which is where
a conventional repository puts them. Narrowing the fetch to the inventory
directory therefore returns the right hosts, the right groups, exit `0` and
**every variable missing**, with nothing unparsed to raise an error.

Settable on workspace create, workspace update, bulk update, and as
autodiscovery rule template fields. See
[Ansible Inventory](ansible-inventory.md) for the model they configure.

### `engine-version`, and its older name `terraform-version`

A workspace pins the version of whichever engine it runs — OpenTofu, Terraform
or Pulumi — in one attribute, **`engine-version`**. That is the canonical name.

**`terraform-version` is the same attribute under its original name, and it is
permanent.** It is not deprecated and there is no sunset date: it is go-tfe's own
attribute name, so `tofu`, `terraform` and `tfci` send and read it on the TFE
compatibility surface. Terrapod therefore keeps both names for good, exactly as
it does for [`structured` / `hcl`](#variables) on variables.

| | |
|---|---|
| **On input** | Send either. `engine-version` wins if you send both. Sending both with **different values is a 422** rather than a silent precedence rule — a client disagreeing with itself about which version to run has a bug, and picking a winner would hide it. |
| **On output** | Both are returned, always with the same value. Read whichever your client already knows about. |
| **Where** | Workspaces, runs, autodiscovery rules, the bulk-update `update` body, and the workspace-search `filter` (which is snake_case: `engine_version`, with `terraform_version` accepted). |

An empty string is a value, not an absence: it means "whatever this deployment's
default is for that engine", resolved when the run starts. Omitting the
attribute on create takes the deployment default instead.

Partial versions are supported and resolve to the newest matching release —
`"1.12"` means `1.12.*`. Do not use HCL constraint operators (`~>`, `>=`); those
belong in a `required_version` block inside your configuration.

### Agent pool set

A workspace routes its runs to a **set** of agent pools. The set is **flat**:
a queued run is offered to every pool at once and whichever pool has a live
listener claims it first. There is no primary, no ordering preference and no
rotation — losing one pool simply means another claims the work.

Exactly-once execution is unaffected. A run is a single row claimed under
`SELECT … FOR UPDATE SKIP LOCKED`, so offering it to N pools cannot produce N
claims. On claim the run records the pool that took it, so cancellation,
job-status queries and log streaming address the cluster actually running it.

Two attributes carry this, and they are **mutually exclusive on write**:

| Attribute | Type | Meaning |
|---|---|---|
| `agent-pool-ids` | list of `apool-…` | The whole set. |
| `agent-pool-id` | `apool-…` \| `null` | On read, element 0 of the set. On write, "this workspace has exactly this one pool" — it **replaces** the set. `null` clears it. |

Sending both in one request returns **422**. `agent-pool-name` and the
`agent-pool` relationship also resolve to element 0; an `agent-pools` to-many
relationship carries the full set.

```json
{
  "data": {
    "type": "workspaces",
    "attributes": {
      "agent-pool-ids": ["apool-019e01db-...", "apool-019e02ac-..."]
    }
  }
}
```

**Required permission:** workspace `admin`, plus `pool:assign` on **every**
pool in the set — a caller may not attach a workspace to a pool they could not
have attached it to on its own.

> **Upgrading from a single pool:** `agent-pool-id` keeps working exactly as it
> did, so no client has to change. Be aware that because it replaces the set, a
> tool that manages `agent_pool_id` (an un-upgraded Terraform provider, say)
> will drop pools added elsewhere the next time it applies. Manage the set with
> `agent-pool-ids` if more than one tool touches it. The removal is
> audit-logged either way.

A workspace whose pools have **all** gone dark surfaces a
`no_live_agent_pool` health condition (distinct from `no_agent_pool`, which
means none is assigned at all) and is counted by the
`terrapod_workspaces_without_live_pool` metric — the signal to alert on, since
losing a single pool is now survivable.

### Update Workspace

```
PATCH /api/v1/workspaces/{id-or-name}                 # native — every enabled engine
PATCH /api/tfe/v2/workspaces/{id}                     # TFE-compatible — Terraform only
```

Same body format as create. Only include attributes to change. Both routes run the same validation. A rename follows the workspace's own engine: a Pulumi workspace keeps the `project::stack` shape.

**Required permission:** `admin` on the workspace.

**403 refusals:** a changed `vcs-connection-id`/`vcs-connection` the caller has no
claim to, a `vcs-repo-url` outside the connection's `allowed-repositories`, and a
change that would pull in a rule-assigned variable set. All three are shared with
create — see [Refusals on create and update](#refusals-on-create-and-update).

**Self-lockout protection:** If the request changes `labels` and the new labels would reduce the caller's own access level, the API returns **409 Conflict** with a descriptive error. Re-submit with `"force": true` in the attributes to confirm the change. Platform admins and workspace owners are immune (their access doesn't depend on labels).

### Workspace Permissions Block

All workspace responses (show and list) include a `permissions` object reflecting the authenticated user's effective permissions:

```json
{
  "permissions": {
    "can-update": true,
    "can-destroy": true,
    "can-queue-run": true,
    "can-queue-apply": true,
    "can-queue-destroy": true,
    "can-read-state-versions": true,
    "can-create-state-versions": true,
    "can-read-variable": true,
    "can-update-variable": true,
    "can-lock": true,
    "can-unlock": true,
    "can-force-unlock": true,
    "can-read-settings": true
  }
}
```

### Delete Workspace

```
DELETE /api/v1/workspaces/{id}
```

**Deleting does not delete the state.** The state blobs stay in object storage
and a delete marker records what they belonged to, so a mistaken delete is
recoverable for
`api.config.artifact_retention.deleted_workspace_retention_days` (default 30)
— see [Deleted Workspaces (undelete)](#deleted-workspaces-undelete) and
[the runbook](runbooks.md#i-deleted-a-workspace-by-mistake). After that window
the reaper removes the state permanently and it is unrecoverable.

Recovery produces a **new workspace with a new id**, so anything referencing the
old id needs repointing — it is a salvage operation, not an undo.


**Required permission:** `admin` on the workspace.

### Lock Workspace

```
POST /api/tfe/v2/workspaces/{id}/actions/lock
POST /api/v1/workspaces/{id}/actions/lock
```

**Required permission:** `plan` on the workspace.

> **Also on the native surface.** `POST /api/v1/workspaces/{id}/actions/lock`, `/actions/unlock` and `/actions/force-unlock` do the same thing for **any** engine. The `/api/tfe/v2` paths are unchanged and still Terraform-only — a workspace on another engine 404s there, as it does everywhere on that surface.

A manual lock is the CLI/UI state lock **and** an operator gate on applies: while a workspace is locked, apply-capable (plan+apply) runs **will not start** and a confirm (`POST /api/tfe/v2/runs/{id}/actions/apply`) returns **409 Conflict**. Auto-apply runs settle in `planned` and wait for an unlock rather than applying. **Plan-only runs (speculative plans, drift checks) are not blocked** — they never mutate state. Returns 409 if the workspace is already locked; the existing lock, its reason and its holder are left untouched.

The body is optional. A reason given in it is stored with the lock, together with the caller's identity (the user's email), so an operator can see why the workspace is locked and who locked it. Two body shapes are accepted:

```json
{ "reason": "maintenance window — network cutover" }
```

The `WorkspaceLockOptions` shape go-tfe sends. The UI and API clients use it.

```json
{ "ID": "3f0c6a2e-…", "Operation": "OperationTypeApply", "Info": "", "Who": "ops@laptop", "Version": "1.9.0" }
```

The state lock-info object the `terraform`/`tofu` `cloud`/`remote` backend sends. The reason is `Info` when it is non-empty, otherwise `Operation`. `ID`, when present, becomes the lock ID as before.

Blank or non-string values are ignored, and a reason is truncated to 1000 characters. The response is the workspace, with the read-only attributes set:

| Attribute | Type | Description |
|---|---|---|
| `lock-reason` | string \| null | Why the workspace is locked, as given when the lock was taken. `null` when unlocked or when no reason was given. |
| `locked-by` | string \| null | The identity that took the lock (a user's email). `null` when unlocked, or when the lock was taken by something with no user identity (a Pulumi update's lock carries the reason `pulumi update` and no holder). |

Both attributes appear on every workspace response, and are `null` whenever `locked` is `false`.

### Unlock Workspace

```
POST /api/tfe/v2/workspaces/{id}/actions/unlock
POST /api/v1/workspaces/{id}/actions/unlock
```

**Required permission:** `plan` on the workspace (own locks only).

Unlocking clears `lock-reason` and `locked-by` along with the lock.

### Force-Unlock Workspace

```
POST /api/tfe/v2/workspaces/{id}/actions/force-unlock
```

**Required permission:** `admin` on the workspace (the `workspace:force-unlock` capability).

Clears the state lock **regardless of the lock ID** — the endpoint `terraform`/`tofu force-unlock` calls. Use it to release a lock held by another user or a lock stranded when a CLI operation crashed mid-run. Idempotent: force-unlocking an already-unlocked workspace returns 200. The lock's reason and holder are cleared with it.

### Drift Detection Attributes

Workspaces support the following drift detection attributes (settable on create and update):

| Attribute | Type | Default | Description |
|---|---|---|---|
| `drift-detection-enabled` | boolean | `true` (VCS) / `false` (non-VCS) | Enable or disable automatic drift detection. Auto-enabled when a VCS connection is set |
| `drift-detection-interval-seconds` | integer | `86400` | How often to run drift detection checks (minimum: 3600 seconds / 1 hour) |
| `plan-expiry-seconds` | integer / null | `null` | Per-workspace plan-expiry TTL (#646). When set, an apply-capable run that has sat in `planned` longer than this (from plan completion) is auto-discarded and must be re-planned. `null` / `0` = disabled (default) |
| `drift-ignore-rules` | list[string] | `[]` | Glob-aware patterns silenced by the drift-result classifier (#482). Each rule is a Terraform address optionally suffixed with a dotted attribute path; `*` matches zero or more non-`.` chars (spans `[N]` indices), `[*]` matches any bracketed index. A bare address with no attribute suffix silences any change to that resource — including destroys — so use carefully. Max 50 entries, ≤ 500 chars each. Examples: `aws_iam_role.foo.tags.Environment`, `aws_autoscaling_group.workers[*].desired_capacity`, `module.eks*.argocd_cluster.*.config.tls_client_config.ca_data`. Affects drift-detection runs only — regular plan/apply is untouched. See [drift-ignore-rules.md](drift-ignore-rules.md) for the full grammar and recipes |
| `security-scan-enforcement` | string | `advisory` | IaC security-scan (Checkov/Trivy) enforcement (#1036): `off` (skip the stage), `advisory` (scan and record findings, never block apply — the default), or `enforced` (a failed/errored scan holds the run in `planning` until the finding is fixed or a workspace admin overrides it) |
| `security-scan-engine` | string | `checkov` | Which scanner(s) run: `checkov`, `trivy`, or `both` (union of findings, deduped) |
| `security-scan-severity-threshold` | string | `high` | Lowest finding severity that counts as a scan failure: `critical`, `high`, `medium`, or `low` |
| `security-scan-skip-rules` | list[string] | `[]` | Scanner rule-ids to suppress (Checkov `CKV_*` / Trivy `AVD-*`). Max 200 entries, ≤ 100 chars each |

### Runner Debug Mode

| Attribute | Type | Default | Description |
|---|---|---|---|
| `debug-mode` | boolean | `false` | Hold this workspace's **failed** runner pods open so an operator can `kubectl exec` into one (#1764). The run is reported as failed first and is final from Terrapod's side; only then does the container stay up, for at most `runners.debugLingerSeconds`. Successful runs are unaffected. See [runners.md → Debug mode](runners.md#debug-mode-inspecting-a-failed-runner-pod) for what a held pod exposes and who can reach it |

### Pull Requests From Forks

| Attribute | Type | Default | Description |
|---|---|---|---|
| `allow-fork-pr-plans` | boolean | `false` | Whether a pull request opened **from a fork** gets a speculative plan ([GHSA-gp5w-76rw-c452](https://github.com/mattrobinsonsre/terrapod/security/advisories/GHSA-gp5w-76rw-c452)). Off by default: that plan runs the pull request author's code with the workspace's full credential set — `env`-category variables, sensitive values, OpenBao/Vault-resolved values, minted git credentials and the Job's cloud workload identity — and a fork author has neither write access nor the ability to merge, so the plan is the only path by which their code reaches any of it. **Pull requests from a branch in the repository itself are unaffected and always plan.** It gates [module-impact](registry.md#module-impact-analysis) runs the same way, per consuming workspace. See [vcs-integration.md → Pull requests from forks](vcs-integration.md#pull-requests-from-forks) |

### Cloud Identity Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `oidc-audiences` | object | `{}` | The workspace's **override** of the deployment's cloud-identity audience catalogue, and its half of the opt-in for [per-workspace cloud identity](cloud-identity.md). A map keyed on the provider configuration a token is for — the bare provider type as a `provider` block writes it (`aws`, `azurerm`, `vault`), optionally with an alias (`aws.west`, where the alias is part of the key). Each value is **always a list**, even for one entry. One token is minted per key: a token audienced for two targets is replayable between them, and AWS refuses a multi-valued `aud` outright. Lookup is specific-then-general, so `vault.eu` is answered by an entry for `vault.eu` if there is one and by `vault` otherwise. **A key set here is always minted** for a run on this workspace, whether or not the run's provider graph names a provider configuration answering to it (#2108) — the graph selects from the deployment catalogue, and setting a key here is a statement that this workspace needs that token. So the key need not be a provider name: `entra` or `aks` is as valid as `azurerm`, and the token lands at `<token dir>/<key>/token`. **Merged over** `api.config.auth.oidc_issuer.audiences` per key, replacing that key's whole list — so an empty map is valid and common, and means "take the catalogue as it stands"; removing a key is the defined way to stop overriding it, and an explicitly empty list for a key is **refused** because it is neither. **This attribute returns the MERGED map, not the stored override** — so an entry the workspace does not override still appears, and a client that writes the read straight back would promote it into one. Subtract the catalogue (`GET /api/terrapod/v1/oidc/audience-defaults`) and send only what the workspace owns; the Terraform provider reconciles only the keys the practitioner declared, for exactly this reason. At most 10 keys, 10 audiences per key, 255 characters per audience and 128 per key; a key carries no whitespace and at most one `.`; a blank or duplicate audience is **refused**, not dropped. A key containing `/`, `\`, NUL or any `..` segment is **refused** as well, and that one is a security control rather than key hygiene: the key becomes a directory name (`<token dir>/<target>/token`), and because lookup splits on the first `.`, `aws./../vault` would resolve through an ordinary `aws` entry and land an AWS-audienced token at the path the operator's `vault` provider block reads. It is enforced at the workspace write (`422`), at the mint (`400`), and again in the runner before the path join — the last deliberately duplicated, because the runner is a separately versioned image. Stored byte-for-byte and never normalised: an audience is an opaque string the federation target chose. Terrapod attaches no meaning to any of them — any provider may be mapped to any audience, and the cloud's own trust policy is the only gate. Inert unless the deployment also sets `api.config.auth.oidc_issuer.enabled`. Settable on create and update, in the autodiscovery rule template, and via [bulk update](#bulk-workspace-operations). See [Per-Workspace Cloud Identity](#per-workspace-cloud-identity-oidc-federation) for the endpoints |

### Terragrunt Attributes

Workspaces support running agent-mode plans/applies through Terragrunt (settable on create and update). See [terragrunt.md](terragrunt.md) for the full feature description, including the CLI-driven path that needs no configuration.

| Attribute | Type | Default | Description |
|---|---|---|---|
| `terragrunt-enabled` | boolean | `false` | Wrap `tofu`/`terraform` with Terragrunt for agent-mode runs. The runner fetches the terragrunt binary from the pull-through binary cache, pins it to the workspace's execution backend via `TG_TF_PATH`, and reconciles the backend to local so Terrapod still owns state |
| `terragrunt-version` | string | `1.0` | Terragrunt CLI version. Partial versions (e.g. `1.0`) are resolved by the binary cache to the latest matching release; pin an exact `x.y.z` for reproducibility |

### AI Plan Summary Attributes

Workspaces carry two attributes that govern the optional AI plan-summary feature (settable on create and update). When the feature is globally disabled at the deployment level (`api.config.ai_summary.enabled: false`), these fields are stored but inert — no calls are made. See [docs/ai-plan-summary.md](ai-plan-summary.md) for the full operator guide.

| Attribute | Type | Default | Description |
|---|---|---|---|
| `ai-summary-mode` | string | `"default"` | Per-workspace override. One of `"default"` (follow the global toggle), `"enabled"` (always summarise this workspace's plans), or `"disabled"` (never summarise this workspace — overrides global). |
| `ai-summary-context` | string | `""` | Free text up to 4000 characters appended to the model's prompt as workspace-specific facts (e.g. "Fronts the vault for service X — destroying the KMS key causes a global outage."). Additive to the deployment-wide `fleet_context`. |
| `ai-policy-mode` | string | `"default"` | Per-workspace override for the AI **policy gate** (#1766). One of `"default"` (follow the deployment setting), `"enabled"`, or `"disabled"`. **`"disabled"` is the only value with an effect**, and it opts out of an **advisory** verdict only — a `mandatory` gate ignores it, so a fleet-wide blocking control cannot be switched off per workspace. `"enabled"` is accepted as a synonym for `"default"` and changes nothing: a workspace cannot opt into a gate the deployment has not enabled, and when the deployment *has* enabled it the level is already either advisory or mandatory, so there is nothing to raise. |
| `slack-channel` | string | `""` | Opt-in Slack channel (name or ID) this workspace's run notifications post to (#556) — approval requests, applies, errors, drift. Empty = silent (there is no deployment-wide fan-out). Only effective when the Slack app is enabled server-side (`api.config.slack.enabled`). See [slack-integration.md](slack-integration.md). |

422 errors:
- `ai-summary-mode` outside the enum
- `ai-summary-context` longer than 4000 characters
- `ai-summary-context` not a string

The following read-only attributes are included in workspace responses when drift detection is enabled:

| Attribute | Type | Description |
|---|---|---|
| `drift-last-checked-at` | string (RFC3339) or null | Timestamp of the last completed drift detection check |
| `drift-status` | string | Current drift status: `""` (never checked), `"no_drift"`, `"drifted"`, or `"errored"` |
| `drift-latest-run-id` | string (run-…) or null | ID of the drift run that produced the current `drift-status`. Lets the workspace-list UI link the badge straight to the run that explains the status. Cleared on a successful (non-drift) apply because the previous drift run is no longer the canonical link. Null when drift detection has never run or when the column predates v0.35.3 |

### VCS Polling Health Attributes

Read-only, present on every workspace. The pair is what makes a stalled VCS
connection detectable from the API alone — `vcs-last-polled-at` advances only on
a **successful** poll, so on its own a frozen value cannot be told apart from a
workspace that is simply not due yet.

| Attribute | Type | Description |
|---|---|---|
| `vcs-last-polled-at` | string (RFC3339) or null | Timestamp of the last **successful** poll. Null if no poll has ever succeeded |
| `vcs-last-attempted-at` | string (RFC3339) or null | Timestamp of the last poll **attempt**, successful or not. Stamped before anything in the poll can fail. Null on workspaces not polled since the upgrade that added it |
| `vcs-last-error` | string or null | The most recent poll failure, named as specifically as the provider allows — a rate limit reports the HTTP status and, when the response carries the headers, how long until the window resets. Cleared on the next successful poll |
| `vcs-last-error-at` | string (RFC3339) or null | Timestamp of `vcs-last-error` |

To alert on a stalled connection, compare the two timestamps rather than relying
on `vcs-last-error` being populated: `vcs-last-attempted-at` newer than
`vcs-last-polled-at` means the most recent attempt did not succeed.

### Lifecycle Attributes (Autodiscovery)

Workspaces created by autodiscovery carry read-only lifecycle attributes that track rename/delete/orphan reconciliation. They are included in workspace responses and surfaced by the UI as a banner on the workspace detail page and a badge on the workspace list.

| Attribute | Type | Description |
|---|---|---|
| `lifecycle-state` | string | `"active"` (normal), `"pending_deletion"` (the source directory was removed or the workspace was orphaned and the rule did not opt in to destroy — needs an explicit operator action), or `"archived"` (terminal: never-applied orphan auto-archived, or destroyed via an opt-in `destroy` rule, or a superseded speculative rename duplicate) |
| `lifecycle-reason` | string | Human-readable explanation of the current state (e.g. `directory 'accounts/x' removed on 'main'`, `origin PR #14 closed unmerged; never applied — auto-archived`). Empty for `active` workspaces |
| `autodiscovery-pr-number` | integer or null | The PR that created the workspace, while it is still speculative. Cleared (graduated) once that PR merges; `null` for non-autodiscovered workspaces |

The owning autodiscovery rule's `on-directory-delete` policy (`flag` default, or opt-in `destroy`) governs what happens when a tracked directory is removed — see [autodiscovery.md](autodiscovery.md). A rename of a tracked directory moves the existing workspace in place (state and history preserved); it never destroys, even on a `destroy` rule.

### State Divergence Flag

Workspaces also expose a read-only `state-diverged` boolean. It is set to `true` when the runner reports it could not upload state after a successful apply (the apply ran against the real provider, but the corresponding state version did not land in Terrapod), so Terrapod's view of the workspace state and the real-world infrastructure may have drifted. The UI surfaces this as a banner on the workspace detail page. Clear it by running a fresh apply or by manually uploading a state version that matches reality.

```json
"state-diverged": false
```

### Health Conditions

Every workspace response carries a read-only `health-conditions` array,
recomputed on every request rather than stored, so a condition disappears as
soon as whatever caused it does. An empty array means
nothing is wrong. The UI renders it as banners on the workspace detail page and
as badges on the workspace list.

```json
"health-conditions": [
  {
    "code": "state_diverged",
    "severity": "error",
    "title": "State may not match reality",
    "detail": "The last apply completed but the state upload failed …"
  }
]
```

`code` is the stable identifier to match on; `title` and `detail` are prose for
a person and may be reworded. `severity` is `error` or `warning`.

| Code | Severity | Raised when |
|---|---|---|
| `state_diverged` | `error` | The last apply completed but the state upload failed, so the stored state may not match reality. Mirrors the `state-diverged` flag above |
| `no_agent_pool` | `warning` | The workspace is in agent execution mode with no agent pool assigned, so runs queue indefinitely |
| `no_live_agent_pool` | `error` | The workspace is in agent execution mode and none of its assigned pools currently has a listener sending heartbeats. Skipped rather than guessed when liveness cannot be determined — a false "no runner" banner is worse than a missing one |
| `vcs_error` | `error` | The most recent VCS poll failed; `detail` is the error itself. Cleared by the next successful poll — see [VCS Polling Health Attributes](#vcs-polling-health-attributes) |
| `drifted` | `warning` | Drift detection is enabled and the last drift run found changes between the stored state and the real infrastructure |
| `drift_errored` | `warning` | Drift detection is enabled and the last drift run failed |

New codes are added as new conditions are detected, so treat the list as open:
match the codes you handle and pass anything else through with its `title` and
`detail`.

### List VCS Refs (Terrapod Extension)

```
GET /api/v1/workspaces/{id}/vcs-refs
```

Returns branches, tags, and the default branch for a VCS-connected workspace. Used by the UI to populate the VCS ref picker when queueing runs.

**Required permission:** `read` on the workspace.

**Response:**
```json
{
  "branches": [
    {"name": "main", "sha": "abc123..."},
    {"name": "feature-x", "sha": "def456..."}
  ],
  "tags": [
    {"name": "v1.0.0", "sha": "789abc..."}
  ],
  "default-branch": "main"
}
```

Returns 422 if the workspace is not VCS-connected or the VCS connection is inactive.

---

## State Versions

### List State Versions

```
GET /api/tfe/v2/workspaces/{id}/state-versions
GET /api/v1/workspaces/{id}/state-versions
```

**Required permission:** `read` on the workspace.

> **State reads answer on both surfaces.** Every engine Terrapod runs has state, so `GET /api/v1/workspaces/{id}/state-versions`, `/current-state-version`, `GET /api/v1/state-versions/{id}` and `/download` serve a workspace on any engine. The `/api/tfe/v2` paths stay Terraform-only.
>
> The state *write* pair (`POST .../state-versions` then `PUT /state-versions/{id}/content`) is the `go-tfe` upload protocol and remains TFE-only. A Pulumi stack's state is published by its own update-complete path, or uploaded by hand with `POST /api/v1/workspaces/{id}/state-versions/actions/upload`, which takes `pulumi stack export` output.

### Current State Version

```
GET /api/tfe/v2/workspaces/{id}/current-state-version
GET /api/v1/workspaces/{id}/current-state-version
```

**Required permission:** `read` on the workspace.

For **agent-mode runs** reading another workspace's state via `data "terraform_remote_state"` (runner-token principals), authorization is by the producer-controlled consumer allowlist instead of per-user RBAC — see [Cross-Workspace Remote-State Consumers](#cross-workspace-remote-state-consumers) and [the composition guide](remote-state.md).

### Create State Version

```
POST /api/tfe/v2/workspaces/{id}/state-versions
```

**Request body:**
```json
{
  "data": {
    "type": "state-versions",
    "attributes": {
      "serial": 1,
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "lineage": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}
```

**Required permission:** `write` on the workspace.

### Show State Version

```
GET /api/tfe/v2/state-versions/{id}
GET /api/v1/state-versions/{id}
```

### Download State

```
GET /api/tfe/v2/state-versions/{id}/download
GET /api/v1/state-versions/{id}/download
```

Returns a redirect to a presigned URL for the raw state file.

**Required permission:** `plan` on the workspace.

For **agent-mode runs** reading another workspace's state via `data "terraform_remote_state"` (runner-token principals), authorization is by the producer-controlled consumer allowlist instead of per-user RBAC — see [Cross-Workspace Remote-State Consumers](#cross-workspace-remote-state-consumers).

### Upload State Content

```
PUT /api/tfe/v2/state-versions/{id}/content
```

Binary upload of raw state bytes. No auth required (presigned-style -- the state version UUID acts as a capability token). This matches `go-tfe` behavior.

### Upload JSON State Content

```
PUT /api/tfe/v2/state-versions/{id}/json-content
```

Accepted and discarded (placeholder for future use).

### State Version Response Format

State version responses include a `created-by` attribute (email of the user who created it, or null for runner-created states) and a `run` relationship linking to the run that produced the state:

```json
{
  "data": {
    "id": "sv-...",
    "type": "state-versions",
    "attributes": {
      "serial": 1,
      "lineage": "...",
      "md5": "...",
      "size": 1234,
      "created-at": "2026-01-01T00:00:00Z",
      "created-by": "user@example.com"
    },
    "relationships": {
      "run": {
        "data": { "id": "run-...", "type": "runs" }
      }
    }
  }
}
```

### Delete State Version (Terrapod Extension)

```
DELETE /api/v1/state-versions/{id}/manage
```

Deletes a non-current state version. The current (highest serial) version cannot be deleted.

**Required permission:** `admin` on the workspace.

Returns 204 on success, 409 if attempting to delete the current version.

### Rollback State Version (Terrapod Extension)

```
POST /api/v1/state-versions/{id}/actions/rollback
```

Creates a new state version with the content of the specified older version. The new version gets serial = max existing + 1. This is a "copy forward" rollback — no versions are deleted, history is preserved. The `serial` inside the copied state file is set to the new version's serial, so the next apply counts on from it rather than from the old version and does not collide with an existing serial.

**Required permission:** `write` on the workspace.

Returns 201 with the new state version.

### Upload State Manually (Terrapod Extension)

```
POST /api/v1/workspaces/{id}/state-versions/actions/upload
```

Upload a raw state JSON file. Serial is auto-assigned (max existing + 1). Useful for state surgery workflows.

**Required permission:** `write` on the workspace.

**Request body:** Raw state JSON (Content-Type: application/json).

Returns 201 with the new state version.

---

## Runs

### Create Run

```
POST /api/tfe/v2/runs
```

**Request body:**
```json
{
  "data": {
    "type": "runs",
    "attributes": {
      "message": "Triggered from API",
      "engine": "terraform",
      "is-destroy": false,
      "auto-apply": false,
      "plan-only": false,
      "target-addrs": ["aws_instance.web"],
      "replace-addrs": [],
      "refresh-only": false,
      "refresh": true,
      "allow-empty-apply": false
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-abc123",
          "type": "workspaces"
        }
      }
    }
  }
}
```

**Required permission:** `plan` for plan-only runs, `write` for apply runs.

#### Run concurrency: serialization & auto-discard

Apply-capable (plan+apply) runs are **serialized per workspace** — only one executes at a time. When a newer apply-capable run is queued for a workspace:

- **Older un-applied apply-capable runs are auto-discarded** so a stale plan can't later apply outdated config: a `planned` run awaiting confirmation transitions to `discarded`, and `pending`/`queued` runs transition to `canceled` (message: `Superseded by run <id>`).
- An **in-flight** run (`confirmed`/`applying`) is **never** superseded — committed applies finish on their own terms; the newer run waits until it reaches a terminal state.

**Plan-only runs are exempt** — speculative PR plans, CLI `plan`, and drift checks never mutate state, so they run concurrently and neither supersede nor are superseded. (Speculative PR runs are still superseded per-PR by the VCS poller on a new commit.)

This is enforced server-side regardless of run source (VCS, CLI/API, UI), so the same guarantees hold for `terraform`/`tofu` CLI-driven runs as for VCS-driven runs.

#### Runs held at a gate: `blocked-by`

A mandatory policy set, an enforced security scan, a mandatory run task, or a mandatory AI policy gate can stop a run. The read-only **`blocked-by`** attribute names the gate holding it: `run-task`, `policy`, `security-scan` or `ai-policy` (checked in that order), or `null` for any run not held.

**A held run is not necessarily in `planning`.** Run tasks fire at three boundaries (#1837), and the run's status tells you which one is holding it — do not write a client that assumes `planning`:

| Boundary | Status while held | Notes |
|---|---|---|
| `pre_plan` (run task) | `queued` | Looks like a run waiting its turn. No plan exists yet, so there is nothing to discard. |
| post-plan (all four gates) | `planning` | Until 2.0 — see below. The case the rest of this section describes. |
| `pre_apply` (run task) | `planned` | Looks like a run awaiting a human. Already discardable by the ordinary route. |

A **post-plan** hold specifically:

- the run's plan reports `status: finished`, so a CLI waiting on the plan log returns;
- the run is **discardable** (`actions.is-discardable: true`) unless it is plan-only, and a newer apply-capable run supersedes it as it would a `planned` run;
- it is released by an override (policy, security scan or AI policy) or a passing run task, which the reconciler picks up on its next tick. Kubernetes cleaning up the finished plan Job does not error it.

`ai-policy` is the one gate that can hold a run before there is anything to decide: its verdict is produced in the API after the plan JSON is uploaded, not by the runner before plan-result, so a mandatory gate waits for it rather than failing the run for evidence that does not exist yet. See [ai-plan-summary.md → Policy gate](ai-plan-summary.md#policy-gate).

In the Terraform Enterprise vocabulary (#1704) — `api.config.runs.tfe_post_plan_decisions: true`, the default from 2.0, or the request header `X-Terrapod-Post-Plan-Decisions: tfe` — a held run instead reports `status` as `post_plan_running` (post-plan tasks still running, or an AI policy verdict still being produced), `post_plan_awaiting_decision` (a mandatory task failed) or `policy_override` (a mandatory policy set, an enforced scan, or a landed AI policy deny); `blocked-by` is unchanged. The `policy-checks` and `task-stages` relationships then carry `data` (the run's [policy checks](#policy-checks) and task stages), and `GET /api/tfe/v2/runs/{id}?include=task_stages` returns the stages and their `task-results` in `included`. `X-Terrapod-Post-Plan-Decisions: legacy` asks for the 1.x answer. See [post-plan-decisions.md](post-plan-decisions.md).

#### Stale-plan guards: state drift (#647), cloud identity drift (#1901) & expiry (#646)

Beyond supersede (a *newer run* case), three guards protect against applying a plan that no longer reflects reality. All three resolve an apply-capable `planned` run to `discarded` and surface the reason in the run's **`discard-reason`** attribute; confirming a stale plan returns **409** (re-plan required). Plan-only / drift / speculative runs are exempt.

- **State-version drift (#647, always on)** — a plan is snapshotted against the workspace's state serial when it starts. If the current state serial advances before the plan is applied — another apply, a CLI `state push`, a rollback, a manual upload — the plan is stale and is auto-discarded (`discard-reason: state changed since plan (serial N -> M)`). This runs even in agent mode, where the server drives the apply and there is no client to catch it. A first apply (no prior state) has no baseline and is never stale.
- **Cloud identity drift (#1901)** — when the [per-workspace cloud identity](cloud-identity.md) the run would present has moved since its plan was reviewed, because the deployment's audience catalogue or the workspace's `oidc-audiences` override changed (`discard-reason: cloud identity configuration changed since plan (aws, vault.eu)`, naming the targets). Scoped to the targets the run **actually minted for**, not the whole merged map, so one catalogue edit does not refuse every pending apply in the fleet; a target the catalogue has *gained* since the plan is deliberately not a cause, because the apply would present the same identity the plan did. The runner's mint path refuses the same mismatch per target, but only inside a Job and after `init` — this fires before anything is scheduled. Never fires for a workspace that mints nothing.
- **Time-based expiry (#646, per-workspace, off by default)** — when a workspace sets `plan-expiry-seconds`, a plan older than that TTL (from completion) is auto-discarded by a periodic sweep and at confirm time (`discard-reason: plan expired after {ttl}s`).

They are evaluated in the order listed — state drift, then cloud identity drift, then expiry.
Whichever reason fires first wins, and all three compose with supersede.

#### Configuration version resolution

The `configuration-version` relationship is optional. Resolution rules:

- **Explicit CV in the request body** → used as-is.
- **No CV + workspace has a VCS connection** → Terrapod fetches the latest commit (or the branch/tag from `vcs-ref`) and creates a fresh CV automatically.
- **No CV + non-VCS workspace** → falls back to the **latest fully-uploaded, non-speculative CV** for the workspace. This is the path the UI's "Queue Plan" button takes.
- **No CV + non-VCS workspace + no upload has ever succeeded** → `422 Unprocessable Entity` with detail `"Workspace has no uploaded configuration. Upload one via 'tofu plan' / 'tofu apply' (CLI), or POST a configuration version + tarball before queueing a run."`. The same response covers the misconfigured-workspace edge case where `vcs_connection_id` is set but `vcs_repo_url` is empty.

The CLI plan/apply flow always supplies a CV (it uploads one first), so it's unaffected by the fallback.

#### Optional Run Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `target-addrs` | array of strings | `[]` | Resource addresses to target (equivalent to `-target` CLI flag) |
| `replace-addrs` | array of strings | `[]` | Resource addresses to force replacement (equivalent to `-replace` CLI flag, plan phase only) |
| `refresh-only` | boolean | `false` | Refresh-only plan — reconcile state without planning changes (equivalent to `-refresh-only`) |
| `refresh` | boolean | `true` | Whether to refresh state before planning. Set to `false` to skip refresh (equivalent to `-refresh=false`) |
| `allow-empty-apply` | boolean | `false` | Allow apply even when the plan has no changes (equivalent to `-allow-empty-apply`). **Terraform/OpenTofu only** — `pulumi up` carries out whatever the preview produced, empty or not, so setting it `true` on a Pulumi workspace is refused with 422 rather than stored and ignored. The other run options are not engine-specific: Pulumi reads `target-addrs`/`replace-addrs` as `--target`/`--replace` URNs and `refresh-only`/`refresh` as `pulumi refresh` / `--refresh=false`. |
| `vcs-ref` | string | `""` | Branch, tag, or SHA to fetch code from instead of the workspace's tracked branch. Only valid on VCS-connected workspaces. **Runs with a non-default ref are always plan-only** — the server enforces this regardless of the `plan-only` attribute value |
| `save-plan` | boolean | `false` | A saved-plan run — `terraform plan -out=FILE`. See below |

### Saved-plan runs (`terraform plan -out=FILE`)

`save-plan: true` creates a run that is apply-capable but whose apply is
**deferred**. That is the one thing it does differently, and it is the whole
feature: an ordinary run awaiting confirmation holds its workspace from the
moment it plans, so nothing else can plan behind it. A saved-plan run does not.
It plans immediately, holds nothing, and takes the workspace's single apply slot
only when someone confirms it — which is what makes keeping a plan file around
for a while meaningful rather than an outage.

Terrapod has no separate "workspace lock" for this to skip. `workspace.locked`
is the CLI/manual state lock and is never set by run activity; the lock a run
takes is its place in the per-workspace serialization, and that is what a
saved-plan run defers.

What follows from the deferral:

- **A newer run does not discard it.** Ordinarily a newer apply-capable run
  supersedes older unapplied ones. A saved plan is exempt: someone is holding
  that file, and a colleague queueing a run must not silently invalidate it.
- **It still goes stale.** Exemption from supersede is why the state check
  matters more, not less. Confirming a saved plan whose workspace state has
  moved since it planned is refused and the run discarded, exactly as for any
  other plan — so a deferred apply can never apply against state it did not see.
- **Confirming is refused while another run holds the workspace**, with a 409
  naming the run in the way. Not queued (`terraform apply FILE` would block with
  no way to say why) and not superseding (that would discard someone else's
  planned run to make room for a plan made before theirs).

Refused with a 422 in three cases, rather than accepted and quietly turned into
something else:

| Combination | Why |
|---|---|
| `save-plan` + `plan-only` | A plan-only run can never be applied, so the file would promise nothing |
| `save-plan` + a speculative configuration version | Speculative configurations force plan-only — the same contradiction by another door |
| `save-plan` on a VCS-connected **agent** workspace | Applying the saved plan would be a CLI apply, which those workspaces reserve for the VCS integration and the UI. Refused at plan time rather than after the operator holds a file they can never apply |

The attribute round-trips on the run, so a client reading a run back sees what
it asked for.

### Run Response Attributes (Drift Detection)

Run objects include the following drift detection attributes in responses:

| Attribute | Type | Description |
|---|---|---|
| `is-drift-detection` | boolean | `true` if the run was created by the drift detection scheduler |
| `has-changes` | boolean or null | Whether the plan detected infrastructure changes. `null` if the plan has not completed yet |
| `pulumi-bind-plan` | boolean or null | Whether this run's update performs exactly the operations its preview showed (#1553). `null` for any engine but Pulumi, which has no such distinction |

Drift detection runs are always plan-only and are not counted in the workspace's normal run queue.

### Run Response Attributes (Resource Profile / OOM)

Run objects include peak resource usage + an abnormal-exit signal so the UI (and external clients) can surface memory pressure without operators having to grep pod logs. All five attributes are `null` / `""` for runs that pre-date the feature or never started a Job.

| Attribute | Type | Source | Description |
|---|---|---|---|
| `resource-cpu` | string | Workspace setting (snapshot) | CPU request applied to the Job (K8s quantity, e.g. `"1"`, `"500m"`). Limit is `2×` this |
| `parallelism` | integer | Workspace setting (snapshot) | Concurrent operations the engine performs — `-parallelism` for terraform/tofu. Default `10`, minimum `1`, maximum `256` |
| `pulumi-bind-plan` | boolean | Workspace setting | Pulumi workspaces only (#1553): save the preview's plan and bind the update to it (`preview --save-plan` / `up --plan`). Default `false` — the preview saves nothing and the update is a plain `pulumi up`. Off by default because Pulumi's update plans are still experimental upstream. Refused (422) with `true` on any other engine |
| `resource-memory` | string | Workspace setting (snapshot) | Memory request applied to the Job (K8s quantity, e.g. `"2Gi"`). Limit is `2×` this |
| `ee-resource-cpu` | string | Workspace setting (snapshot, **resolved**) | CPU request for the Ansible execution-environment sidecar. Snapshotted already resolved — the workspace's value if it set one, otherwise the deployment default — so a finished run records the size it actually asked for. Empty on every plan and apply |
| `ee-resource-memory` | string | Workspace setting (snapshot, **resolved**) | Memory request for the same container. Limit is `2×` this |
| `ee-image` | string | Resolved at run creation | The Ansible execution environment this run used, as a full image reference. Recorded because the built-in tags **move** — a line's image is rebuilt when upstream patches it — so without this a finished run could not be identified afterwards. Empty on every plan and apply, and an empty value is what renders no sidecar at all |
| `peak-memory-bytes` | integer or null | Runner (cgroup v2) | Peak resident memory observed during the run — `/sys/fs/cgroup/memory.peak` |
| `peak-cpu-usec` | integer or null | Runner (cgroup v2) | Cumulative CPU time consumed by the run, microseconds — `usage_usec` from `/sys/fs/cgroup/cpu.stat`. **Captured but not surfaced in the UI** — see note below |
| `runner-exit-code` | integer or null | Runner | Runner script's exit code captured at exit. `null` if the trap didn't fire (e.g. SIGKILL) |
| `runner-exit-reason` | string | Listener (K8s) | Raw K8s `container.state.terminated.reason` (e.g. `"OOMKilled"`, `"Error"`, `"Completed"`). `""` if not observed |
| `runner-exit-status` | string | Reconciler (typed bucket) | Stable typed value: `""` (unknown / not yet observed), `"clean"`, `"oom"`, `"killed"`, `"error"`. The UI keys on this; reason is shown for context |

Two independent capture paths feed these fields:

- **Runner path** — `POST /api/v1/runs/{run_id}/resource-profile` from the runner's EXIT trap with `peak_memory_bytes` / `peak_cpu_usec` / `exit_code`. Fires for any catchable exit (success, plan errored, OPA failed, SIGTERM during apply).
- **Listener path** — when a Job fails, the listener reads `container.state.terminated.{reason, exit_code}` and POSTs them on the job-status report. The reconciler maps them to `runner_exit_status`.

OOM (`exit 137 + reason "OOMKilled"`) is uncatchable, so the runner path never fires on OOM — the listener path is the only signal. Both paths converge on the same five DB columns; whichever signal arrives wins. `runner-exit-status` is set **only** by the reconciler (single source of truth for typed bucketing) and is what drives the UI's OOM badge + the typed error message ("Runner OOM-killed (peak memory N.NN Gi). Workspace resource_memory is …. Increase resource_memory + retry.").

See [runners.md — Memory Pressure & OOM Visibility](runners.md#memory-pressure--oom-visibility-430) for the operator-facing tuning workflow.

### Run Response Attributes (Agent Pool)

Which agent pool has a run, and which pools could have claimed it. With multi-pool
workspace routing (#1085) a queued run is offered to every pool in the workspace's set
at once and whichever has a live listener claims it first — so "where did this actually
execute?" is not answerable from the workspace's configuration alone.

| Attribute | Type | Description |
|---|---|---|
| `agent-pool-id` | string or null | The pool that has the run. At creation this is element 0 of the workspace's pool set; **on claim it is rewritten to the pool that actually took the run**, so on a finished run it is where the run executed. `null` for local-execution runs, and for agent runs whose pool has since been deleted |
| `candidate-agent-pool-ids` | array of string | Every pool that could have claimed the run, snapshotted at run creation and preserved (only re-ordered, winner first) across the claim |

The `agent-pool` relationship carries the same id as `agent-pool-id` and is the canonical
link form; the attribute is kept alongside it.

> **Note the difference from a workspace.** On a workspace, `agent-pool-id` is always a
> projection of `agent-pool-ids[0]` and carries no routing preference. On a run it is the
> *claimant*. Likewise `candidate-agent-pool-ids` is deliberately named apart from the
> workspace's `agent-pool-ids`: the workspace attribute is the live configured set, while
> the run attribute is a point-in-time snapshot that does not move when the workspace is
> later re-pointed at different pools.

### Show Run

```
GET /api/tfe/v2/runs/{run_id}
```

#### Apply status on the run

A run's response carries a nested `apply` sub-resource whose
`attributes.status` is what `go-tfe` — and therefore `tofu`/`terraform` — reads
to decide what happened to an apply. Terrapod reports these values:

| `apply.status` | Meaning |
|---|---|
| `pending` | The run has not reached its apply phase |
| `running` | The apply is in progress |
| `finished` | The apply completed successfully |
| `errored` | The apply was dispatched and did not complete successfully |
| `unreachable` | The apply was never dispatched — the plan failed, was discarded, or the run never got that far |
| `canceled` | The run was canceled or discarded |

**`errored` means "the apply was dispatched and did not succeed", which is not
the same as "the engine ran".** The timestamp this is derived from is set when
the apply is *dispatched*, so a run whose runner Job never produced a running
pod — an image that could not be pulled, a cluster with no room, a listener
that died mid-launch — also reports `errored`, even though it provably mutated
nothing. Automation that treats `errored` as "state may be partially applied"
is therefore over-cautious in that case rather than wrong; there is no stored
signal that distinguishes the two, and inventing one would be a schema change.

> **Changed in v1.10.4 / v1.9.4.** Before those releases *every* failed apply
> reported `unreachable`, i.e. "the apply never ran", including applies that
> ran and failed. If you have automation that branches on `unreachable` to mean
> "safe to re-run without inspecting state", re-read it: that value is now
> reserved for applies that genuinely were not dispatched.
>
> **`tofu` and `terraform` are unaffected.** Neither reads this sub-resource's
> status: both call only the apply's log endpoint, and neither references the
> `unreachable` constant at all. The affected population is third-party
> `go-tfe` automation that calls `Applies.Read` itself.

### List Workspace Runs

```
GET /api/tfe/v2/workspaces/{id}/runs
```

Newest first. Because run history grows without bound, this endpoint keeps a **bounded default page** (`page[size]` default 20, max 100) rather than returning everything — the one exception to the "absent → full list" [pagination](#pagination) convention. It honours `page[size]`/`page[number]` and always returns `meta.pagination`, so you can page the full history.

### Confirm Run (Approve Apply)

```
POST /api/tfe/v2/runs/{run_id}/actions/apply
```

**Required permission:** `write` on the workspace.

### Discard Run

```
POST /api/tfe/v2/runs/{run_id}/actions/discard
```

**Required permission:** `write` on the workspace.

### Cancel Run

```
POST /api/tfe/v2/runs/{run_id}/actions/cancel
```

**Required permission:** `write` on the workspace.

### Retry Run

```
POST /api/v1/runs/{run_id}/actions/retry
```

Creates a new run from a terminal run (applied, errored, canceled, discarded) using the same workspace, configuration version, VCS metadata, and settings. A plan-only run left at `planned` can also be retried. The new run keeps the original's kind: a retried plan-only run is plan-only, and a retried destroy run is still a destroy. Returns a 409 if the run is not in a retryable state.

**Required permission:** what queuing that run would need — `run:plan` for a plan-only run, `run:apply` for an apply run, `run:apply-destroy` for a destroy run (the workspace permissions block reports these as `can-queue-run`, `can-queue-apply` and `can-queue-destroy`).

### Workspace Events (SSE)

```
GET /api/v1/workspaces/{workspace_id}/runs/events
```

Server-Sent Events stream for real-time workspace updates. The stream emits events whenever a run changes state **or has its own fields written outside a transition**, the workspace is locked/unlocked, workspace settings are updated, or a new state version is created. Used by the web UI workspace detail page for live updates without polling.

**Event types:**

| Event | Trigger |
|---|---|
| `run_status_change` | Run transitions to a new state |
| `run_updated` | A run's own fields changed **without** a state transition — carries `changed`, naming what moved (`plan-json` for the resource counts, `cost-estimate` for the cost totals, `resource-profile` for the runner's peaks and exit status). The runner uploads all three *after* the result POST that drove the transition, so a consumer that refetches only on `run_status_change` renders a run whose numbers have not arrived yet |
| `log_updated` | A fresh log artifact landed in storage — carries `phase` (`plan` or `apply`). The authoritative final log is uploaded after the run has already turned terminal, so this is what tells a consumer to come back for the tail |
| `workspace_lock_change` | Workspace is locked or unlocked (includes `locked` boolean) |
| `workspace_updated` | Workspace settings are modified |
| `state_version_created` | New state version is uploaded |
| `workspace_variable_change` | A workspace variable is created, updated, or deleted |
| `workspace_notification_change` | A notification configuration is created, updated, or deleted |
| `workspace_run_task_change` | A run task is created, updated, or deleted |
| `run_trigger_change` | A run trigger to/from this workspace is added or removed (published to **both** the source and destination workspace channels, so inbound edges appear live) |
| `remote_state_consumer_change` | A remote-state consumer grant to/from this workspace is added or removed (published to **both** the producer and consumer channels) |

The stream sends `: keepalive` comments every ~1 second. Events are JSON-encoded in `data:` fields. The web UI workspace detail page re-fetches the active tab on receipt of its corresponding event.

**Required permission:** `read` on the workspace.

### Workspace List Events (SSE) (Terrapod Extension)

```
GET /api/v1/workspace-events
```

Server-Sent Events stream for the workspace list page. Emits events whenever a workspace changes (run status, lock, settings, state). The web UI uses this to refresh the workspace list without polling.

**Required permission:** any authenticated user to subscribe — but **each event is
filtered against the subscriber's own `workspace:read`**, so a stream only carries
workspaces that principal can see.

The filter is new in 2.0 (GHSA-mc7f-xmq4-jgvw). This is one global channel
carrying every workspace's id and coarse status, so before it any authenticated
user learned of the existence and state of every workspace in the deployment.
A decision is cached per connection for 30 seconds, so a role change is felt
within that window rather than at the next reconnect; an unresolvable workspace
(deleted, or a transient database error) is treated as unreadable. The web UI is
unaffected — it reloads the list on any event and ignores the payload, so a
dropped event is a reload that would have found nothing changed.

### Plan Details

```
GET /api/v1/runs/{run_id}/plan
```

Returns plan metadata and log download URL. When the runner has uploaded a structured plan (`-out=tfplan` → `terraform show -json tfplan`), the response also carries a `json-output` attribute pointing at `/api/tfe/v2/plans/{run_id}/json-output`.

A **Pulumi** run uploads a preview digest to the same place (#1560), built from the engine events its preview writes:

```json
{
  "engine": "pulumi",
  "change_summary": {"create": 2, "update": 1, "same": 9},
  "has_changes": true,
  "steps": [{"op": "create", "urn": "urn:pulumi:dev::shop::aws:s3/bucket:Bucket::assets",
             "type": "aws:s3/bucket:Bucket"}],
  "steps_truncated": false
}
```

The digest deliberately carries each step's operation, URN and type and nothing else — the engine's events also hold every resource's old and new state, which is where a stack's secrets are. `steps` is capped (`steps_truncated` says when), while `change_summary` is exact however large the preview. Both shapes fill the same `resource-additions` / `resource-changes` / `resource-destructions` / `resource-replacements` / `resource-imports` attributes, so the change badges, conditional auto-apply and the AI summary read one shape whatever produced it. Pulumi's `replace` fills `resource-replacements`; its paired `create-replacement` and `delete-replaced` are not counted again.

### Plan JSON Output

```
GET /api/tfe/v2/plans/{plan_id}/json-output
```

Returns the structured JSON representation of the plan, as produced by `terraform show -json tfplan`. Useful for downstream tooling that wants to consume the resource changes without parsing the human-readable log. Responds **302** to a presigned object-storage URL.

The endpoint is mounted at `/api/tfe/v2/` because `go-tfe` and Terraform's `cloud` block expect it there. Returns **404** if the runner never uploaded the JSON output (older runs, runs that errored before the plan completed).

**Required permission: `state:read` on the workspace — the `plan` tier, the same
as downloading raw state.** The structured plan is a far richer artifact than the
human-readable log it sits beside: it carries each resource's **resolved
attribute values**, the root `variables` with their values (sensitive ones
included), and `prior_state.values` — the whole state in cleartext, resource
secrets and all. Terraform marks sensitive values in the plan rather than
removing them, and Terrapod stores and serves the plan as the engine produced it.

**Changed in 2.0 (GHSA-gwwq-5v7q-h3f4).** This endpoint used to need only
`run:read`, so it sat in the `read` preset — which handed a read-only principal
exactly what the `state:read` gate and the sensitive-variable masking exist to
withhold. If you rely on a `read`-only principal fetching plan JSON (a downstream
tool, a dashboard), raise that principal to `plan` before upgrading; a `read`-tier
caller now gets **403**. TFE does not grant structured plan output at its read
tier either.

Two things that remain true whatever tier you grant:

- **The `plan` tier is still a real grant.** On a workspace whose plans carry
  secrets, the label-based role that grants `state:read` is the control. There is
  no separate switch for this endpoint, and there is no redacted variant: a
  second, weaker-but-plausible plan artifact would be one more thing to keep
  correct for ever. (The AI channel does redact, because a third party receives
  the document there — a different reason that does not generalise.)
- **Keep secrets out of resource arguments.** What puts a value in the plan is
  its being an argument of a resource, not which variable category delivered it.
  A credential a provider reads from its own environment variable never becomes a
  resource attribute, so it never reaches the plan; the same secret interpolated
  into a resource argument does, whichever category carried it.

The run page's **Impact graph** (`GET /api/v1/runs/{run_id}/impact-graph`) stays
at `run:read`: it is derived server-side and carries resource addresses, types,
planned actions and dependency edges — no attribute values.

### Impact Graph

```
GET /api/v1/runs/{run_id}/impact-graph
```

Returns a compact plan **dependency + blast-radius graph** derived server-side from the run's stored JSON plan output — the data behind the run page's **Impact graph** tab. Nodes are the resources in the plan (coloured by planned action: create / update / replace / delete / no-op); edges are the dependencies between them, reconstructed by walking the plan's configuration module tree with cross-module `var`/output binding (so edges span module boundaries, and per-instance `for_each` fan-out is captured). Each node carries its module path so the UI can cluster and label by module.

### Run Compliance Report

```
GET /api/v1/runs/{run_id}/compliance-report
```

Returns an audit-ready compliance report for a single run. Combines OPA policy set evaluation outcomes, security scanning findings (Checkov/Trivy), post-plan decisions, and calculates an overall compliance verdict (`COMPLIANT`, `NON_COMPLIANT`, `OVERRIDDEN`, or `PENDING_REVIEW`).

Requires `run:read` capability on the run's workspace.

### Workspace Compliance Report

```
GET /api/v1/workspaces/{workspace_id}/compliance-report[?limit=50&format=json|csv]
```

Returns an aggregate compliance report across recent runs for a workspace, with a breakdown by verdict. Supports CSV export when `format=csv` is supplied.

`limit` bounds the sample (default 50, maximum 500), so the report states both
`total-runs-evaluated` — the size of the sample — and `total-runs-in-workspace`,
what it was drawn from. Read `compliance-rate-percent` against both: a rate over
the last 50 of 500 runs is not a rate over the history.

`compliance-rate-percent` is `null`, not `100.0`, when nothing was evaluated. A
workspace that has never run is unevaluated rather than compliant, and reporting
a perfect score for it would be indistinguishable from a genuine clean sweep.

Requires `run:read` capability on the workspace.

Deriving the graph on the server (rather than shipping the raw, possibly multi-MB plan JSON to the browser) keeps the payload small and works uniformly through the BFF in every storage backend — unlike `json-output`, whose presigned redirect isn't browser-reachable with the filesystem backend.

**Response:** `{"data": {"type": "impact-graphs", "attributes": {"nodes": [...], "edges": [...], "meta": {"terraform_version": "...", "counts": {...}}}}}`

**Required permission:** `read` on the workspace. Returns **404** when the run produced no JSON plan output.

### Security Scan (#1036)

The deterministic Checkov/Trivy IaC security-scan result for a run — the structural twin of the OPA policy endpoints. See [security-scanning.md](security-scanning.md) for the feature guide; the per-workspace config attributes (`security-scan-*`) are documented in the workspace attributes table above.

```
GET  /api/v1/runs/{run_id}/security-scan                     # read the result (workspace read)
POST /api/v1/runs/{run_id}/actions/override-security-scan    # override a blocking scan (workspace admin)
```

**GET** returns `{"data": <resource>|null, "meta": {"summary": {...}}}`. `data` is `null` when the workspace has scanning off or the run wasn't scanned; for a run whose engine is never scanned (Pulumi, until #1569), `meta.not-evaluated-reason` says why. The resource `attributes` are: `engine`, `enforcement-level`, `severity-threshold`, `outcome` (`passed`/`failed`/`errored`), `findings` (list of `{engine, rule_id, severity, title, resource, file, line, guideline}`), `summary` (`{total, blocking, by_severity, …}`), `error`, `overridden-by`, `overridden-at`, `created-at`. `meta.summary` carries a compact `{status, outcome, engine, total, blocking}` for the badge (`status` = `blocked` | `advisory-failed` | `passed`). Requires `read` on the workspace.

**POST override** marks a failed/errored result overridden and, when the run is still held in `planning` by an enforced scan, re-drives it immediately (mirrors the policy override). Requires **admin** on the workspace; audit-logged. Prefer fixing the finding or adding a skip rule.

The runner protocol (runner-token, run_id-scoped) — `GET .../security-scan-config` and `POST .../security-scan-results` — is internal to the runner and mirrors the OPA `policy-bundle`/`policy-results` pair; the enforcement level and severity threshold are re-resolved **server-side from the workspace** on results POST, never trusted from the runner body.

### AI Policy Gate (#1766)

The AI plan summary's optional post-plan gate — the third structural sibling of the OPA policy and security-scan endpoints. See [ai-plan-summary.md → Policy gate](ai-plan-summary.md#policy-gate) for the feature guide; the per-workspace override (`ai-policy-mode`) is in the workspace attributes table above.

```
GET  /api/v1/runs/{run_id}/ai-policy                     # read the verdict (workspace read)
POST /api/v1/runs/{run_id}/actions/override-ai-policy    # release a held run (workspace admin)
```

**GET** returns `{"data": <resource>|null, "meta": {...}}`. The resource `attributes` are: `enforcement-level` (`advisory`/`mandatory`), `risk-threshold`, `outcome` (`passed`/`failed`/`errored`), `verdict` (`{decision: "allow"|"deny", reasons: [{criterion, detail}]}`), `risk-level`, `error`, `overridden-by`, `overridden-at`, `created-at`. `meta` carries the resolved `enforcement-level` and `blocking`, plus `not-evaluated-reason` when no verdict is recorded.

`data` is `null` for four different reasons and `meta` distinguishes them, because a held run legitimately sits in the last one: the gate is off, the engine is not ruled on (Pulumi — see below), the token budget is spent, or the verdict has simply not landed yet.

**`outcome: errored` BLOCKS under a mandatory gate rather than passing.** The gate fails closed: a verdict that could not be reached is not approval, so an empty `verdict` never reads as a clean pass. `error` distinguishes a spent daily token budget from a model fault, because the two call for different responses.

**POST override** marks the verdict overridden and, when the run is still held in `planning`, re-drives `complete_plan` immediately (mirrors the policy and scan overrides). Requires **admin** on the workspace; audit-logged. It also releases a run held with **no verdict recorded** — the summariser never ran, or failed before ruling — writing an explicit no-verdict override (`outcome: overridden`, `verdict: null`, an `error` saying the gate never ruled) rather than a forged pass, so an auditor can tell the two apart.

Unlike the other two gates there is **no runner protocol**: the verdict is produced in the API by the summariser, which is why a mandatory gate holds the run until it arrives instead of failing it. A Pulumi run is reported as not evaluated and never held — its preview digest is capped, and a gate ruling over a truncated resource list could allow a plan whose offending resource fell off the end.

### Estate Graph

```
GET /api/v1/estate-graph
```

Returns the **whole-estate topology graph** behind the [Estate topology](estate-topology.md) page: every workspace the caller can read (nodes of kind `workspace`, carrying their raw `labels`, `pool`, and in-degree) plus the registry `module` nodes they use, wired by three edge kinds — `remote-state` (consumer → producer), `run-trigger` (source → destination), and `uses-module` (module → workspace).

The result is **RBAC-filtered**: only workspaces the caller can read appear, and an edge or module is included only when it touches a visible workspace — so the estate view never discloses a workspace (or a dependency on one) the caller couldn't otherwise see. The response is deliberately **label-agnostic** (each workspace ships its raw labels); the grouping axis is chosen client-side, because the platform enforces no labelling convention.

**Response:** `{"data": {"type": "estate-graphs", "attributes": {"nodes": [...], "edges": [...], "meta": {"counts": {"workspaces": N, "modules": N, "edges": N}}}}}`

**Required permission:** any authenticated user (content is filtered by per-workspace read access).

### State Graph

```
GET /api/v1/workspaces/{workspace_id}/state-graph[?state_version=sv-...]
```

Returns the **single-workspace resource dependency graph** behind the [State Resource Graph](state-resource-graph.md) tab: one `resource` node per resource address in the workspace's Terraform state (each carrying `type`, `mode` (`managed`/`data`), `module`, `provider`, and in-degree), wired by `depends-on` edges derived from the `dependencies` Terraform records per resource. Defaults to the workspace's current (highest-serial) state version; `?state_version=sv-...` renders an older one.

`meta.versions` lists every state version (for the picker) and `meta.state_version` names the one rendered. Very large states are capped at `meta.max_nodes` (2,000); `meta.truncated` and `meta.total_resources` report this honestly. A workspace with no state (or a version whose content was never uploaded) returns an empty graph, not an error.

**Response:** `{"data": {"type": "state-graphs", "attributes": {"nodes": [...], "edges": [...], "meta": {"counts": {"resources": N, "edges": N}, "truncated": false, "total_resources": N, "max_nodes": 2000, "versions": [...], "state_version": {...}}}}}`

**Required permission:** `state:read` on the workspace (the graph is derived from the secret-bearing state blob, so it requires the same access as downloading raw state).

**Engine-aware (#1568).** A Pulumi workspace's graph is built from its deployment: one node per resource, addressed by URN, carrying the resource `type`, its package as `provider`, and `mode` of `managed` (a provider resource) or `component` (a grouping the program declares). Edges come from each resource's `dependencies`, plus its `parent` where that parent is a real resource — the root `pulumi:pulumi:Stack` is neither drawn nor linked, being the stack itself rather than infrastructure and the parent of everything in it. The response shape is identical for both engines.

### State Outputs

```
GET /api/v1/workspaces/{workspace_id}/state-outputs
```

Returns the workspace's **current state outputs**, for either engine: a Pulumi stack's live on the root `pulumi:pulumi:Stack` resource inside its deployment, a Terraform state's at the top level.

**Sensitive values are masked**, arriving as the literal string `"(sensitive)"` — the reader learns the output exists without this becoming a way to read secrets. Pulumi's are recognised by its own ciphertext envelope; Terraform's by the `sensitive` flag the state records.

A workspace with no state yet, a version whose content was never uploaded, or a state declaring no outputs returns `{"outputs": {}}` — not an error.

**Response:** `{"data": {"type": "state-outputs", "attributes": {"outputs": {"<name>": <value>}, "state_version": "sv-...", "serial": N}}}`

**Required permission:** `state:read` on the workspace, the same trust as the state graph and for the same reason.

### AI Architecture Critique (Terrapod Extension)

State-based, whole-system critique (#1036 Part 2). Reviews the workspace's deployed system **as it exists** — inferred from its current Terraform state (+ the resource graph, the deterministic cost estimate, and the deterministic security-scan findings) and critiqued across resilience / security / cost / well-architected. Distinct from the per-run [Plan Summary](#plan-summary), which reviews a *change*. Enabled by the independent `ai_architecture` config, which is **off by default** — the surface self-gates to 404 until an operator turns it on. It is deliberately a separate switch from `ai_summary`: the critic reads whole-workspace **state**, so enabling it sends resource attributes to the configured model endpoint.

```
GET  /api/v1/workspaces/{workspace_id}/architecture-critique
POST /api/v1/workspaces/{workspace_id}/architecture-critique/regenerate
```

`GET` returns the critique for the workspace's current state version: `{"data": {"type": "architecture-critiques", "attributes": {"status": "ready|pending|skipped|errored", "risk-level": "low|medium|high|critical", "architecture": {...}, "findings": [{"severity", "category", "title", "detail", "resource-address"|"resource_address", "recommendation", "grounded_in"}], "deferred": [...], "state-serial": N, ...}}}`. Returns **404** when the feature is disabled, the workspace has no state, the workspace runs an engine the critic does not read (it reads Terraform state — see [AI Architecture Critique](architecture-critique.md)), or no critique has been generated for the current state yet. `POST .../regenerate` queues a fresh critique (202) and mutates no infrastructure.

**Required permission:** `state:read` on the workspace (the critique reasons over the secret-bearing state, so it requires the same access as downloading raw state).

**SSE:** progress rides the existing per-workspace [run-events channel](#workspace-events-sse) as `architecture_critique_pending` / `architecture_critique_ready` / `architecture_critique_skipped` / `architecture_critique_errored`.

**Auto-generation:** a critique is enqueued automatically when a new **state version's content** is uploaded (after an apply, or a manual state push), best-effort and idempotent per state serial — so the current state always has an up-to-date critique without a manual trigger. `POST .../regenerate` forces a fresh one.

**Consumers:** go-terrapod (`GetArchitectureCritique` / `RegenerateArchitectureCritique`), the MCP tool `terrapod_workspace_architecture_critique` (read; inherits `state:read`), the Terraform provider **data source** `terrapod_architecture_critique`, and the workspace **Architecture** tab in the web UI. See [architecture-critique.md](architecture-critique.md).

### Plan Summary

```
GET /api/v1/runs/{run_id}/plan-summary
```

Returns the AI-generated plan summary (or failure analysis on errored plans) when the optional `ai_summary` feature is enabled and a summary has been produced for the run. See [docs/ai-plan-summary.md](ai-plan-summary.md) for the operator-side setup.

**Required permission:** `read` on the workspace.

`plan_id` accepts either `plan-{uuid}` (the canonical form, matching what's returned in the `plans` relationship of a Run) or a bare run UUID.

**Responses:**
- **200 OK** — the workspace has a summary row for this run. See response shape below.
- **404 Not Found** — no summary row exists. Either the feature is globally disabled, the workspace opted out (`ai-summary-mode: disabled`), or the summariser hasn't run yet. The UI treats 404 as "no AI surface" and renders nothing.

**Response shape:**

```json
{
  "data": {
    "id": "plan-summary-<uuid>",
    "type": "plan-summaries",
    "attributes": {
      "kind": "plan_summary",
      "status": "ready",
      "description": "Adds a single root-level output named `marker` ...",
      "risk-level": "low",
      "risk-factors": [
        {
          "severity": "low",
          "title": "Output-only addition",
          "detail": "The plan only introduces the `marker` output ...",
          "resource_address": "output.marker"
        }
      ],
      "model": "bedrock/us.anthropic.claude-opus-4-8",
      "input-tokens": 1335,
      "output-tokens": 171,
      "error-message": "",
      "created-at": "2026-06-01T12:00:00Z",
      "updated-at": "2026-06-01T12:00:30Z"
    },
    "relationships": {
      "plan": { "data": { "id": "plan-<uuid>", "type": "plans" } },
      "run":  { "data": { "id": "run-<uuid>",  "type": "runs"  } }
    }
  }
}
```

**Attribute reference:**

| Attribute | Type | Description |
|---|---|---|
| `kind` | string | `"plan_summary"` (successful plan → change description + risk assessment) or `"failure_analysis"` (plan-phase errored → root-cause + suggested fixes). |
| `status` | string | `"pending"` (handler running), `"ready"` (model returned a parseable response), `"skipped"` (workspace disabled or daily budget hit — see `error-message`), or `"errored"` (model call failed — see `error-message`). |
| `description` | string | Markdown body. For `kind=plan_summary`, ~600 words describing the proposed changes. For `kind=failure_analysis`, root-cause explanation. |
| `risk-level` | string | One of `"low"`, `"medium"`, `"high"`, `"critical"`. Reflects blast radius + reversibility, not novelty. |
| `risk-factors` | array of object | Each item carries `severity` (same enum as `risk-level`), `title` (max 120 chars), `detail` (max 600 chars), optional `resource_address` (terraform address), and optional `category` (one of `security` / `reliability` / `cost` / `operations` / `scalability` / `change` / `other`). The `category` tag is present on the grounded design-review factors that the summary additionally surfaces when the workspace has security scanning and/or cost estimation enabled (Checkov/Trivy findings are the ground truth for `security`, the cost estimate for `cost`); the classic change-risk factors leave it empty. For `kind=failure_analysis` these are suggested fixes ordered most-likely-to-resolve first. |
| `model` | string | LiteLLM model string used for this summary (e.g. `bedrock/us.anthropic.claude-opus-4-8`). |
| `input-tokens` / `output-tokens` | integer | Telemetry counts reported by the upstream provider. |
| `error-message` | string | Populated only for `status=errored` or `status=skipped`. Empty for `ready`. |

**Real-time updates:** the per-workspace SSE channel (`GET /api/v1/workspaces/{id}/runs/events`) emits one of five lifecycle events as the summary progresses (#463):

| Event | Fires when |
|---|---|
| `plan_summary_pending` | Handler dispatched (or operator clicked Regenerate). UI shows a placeholder. |
| `plan_summary_ready` | Initial summary landed; refetch to render. |
| `plan_summary_errored` | Handler/model failure; refetch to render the error. |
| `plan_summary_skipped` | Runner died abnormally / workspace opted out / daily budget hit. |
| `plan_summary_message_posted` | A chat follow-up turn landed (carries `message_id`). Refetch the transcript. |

All five payloads carry `{run_id, workspace_id}` at minimum. The UI re-fetches the summary on any of them. For VCS-driven runs, the per-workspace PR/MR status comment is edited in place to include the summary content when it lands.

The **AI cost estimate** (#871 — the optional AI layer over the data-only cost estimate, riding this same `ai_summary.enabled` switch + per-workspace mode) emits its own lifecycle events on the same per-workspace channel: `cost_summary_pending`, `cost_summary_ready`, `cost_summary_errored`, `cost_summary_skipped` (workspace opted out / daily budget hit / no estimate), and `cost_summary_message_posted` (a cost-chat follow-up turn landed — carries `message_id`; refetch the transcript). Each carries `{run_id, workspace_id}`. Its primary output is estimates for resources the pricesheet couldn't price; the authoritative figures stay on the data-only cost-estimate endpoint, and every AI dollar amount is tagged `source: "ai-estimate"`, never summed into the deterministic total.

When the workspace has security scanning and/or cost estimation enabled, the same plan summary additionally emits **grounded design-review risk factors** — ordinary `risk-factors[]` items tagged with a `category` (`security` / `reliability` / `cost` / `operations` / `scalability` / `change` / `other`), with the deterministic Checkov/Trivy findings as the ground truth for `security` and the cost estimate as the ground truth for `cost`. This is additive: with those signals off, the summary behaves exactly as before, and there is no separate endpoint or SSE event — it is one AI analysis per run, delivered through the existing `plan_summary_*` lifecycle above.

### Regenerate Plan Summary

```
POST /api/v1/runs/{run_id}/plan-summary/regenerate
```

Re-fires the AI summary handler for a run. Anyone with workspace `read` can regenerate — the call doesn't mutate infrastructure. Bypasses the 5-minute auto-dedup so operator clicks always go through; budget gating still applies handler-side.

**Required permission:** `read` on the workspace.

**Responses:**
- **202 Accepted** — pending row upserted and trigger enqueued. Response shape matches the GET above with `status=pending`.
- **409 Conflict** — run is in a state with no summarisable output yet (still planning, or apply-phase errored).
- **503 Service Unavailable** — AI summary is globally disabled (`api.config.ai_summary.enabled: false`).

### List Plan-Summary Chat Messages

```
GET /api/v1/runs/{run_id}/plan-summary/messages
```

Full transcript of the AI plan-summary chat thread in chronological order. The initial structured summary lives on the parent `PlanSummary` row (`description` + `risk-factors`); this endpoint returns ONLY the conversational follow-ups. The UI renders `message[0]` from the parent summary and appends these.

**Required permission:** `read` on the workspace.

**Responses:**
- **200 OK** with an array (possibly empty) of `plan-summary-messages` resources.
- **404 Not Found** — no initial summary exists for this run.
- **409 Conflict** — the initial summary is still `pending` or `errored`. Can't chat against an unready summary.

```json
{
  "data": [
    {
      "id": "plan-summary-message-<uuid>",
      "type": "plan-summary-messages",
      "attributes": {
        "role": "user",
        "content": "How long will the RDS update take?",
        "model": "",
        "input-tokens": 0,
        "output-tokens": 0,
        "error-message": "",
        "created-at": "2026-06-01T12:01:00Z"
      }
    },
    {
      "id": "plan-summary-message-<uuid>",
      "type": "plan-summary-messages",
      "attributes": {
        "role": "assistant",
        "content": "An in-place RDS modify with `apply_immediately = false` typically completes during the next maintenance window…",
        "model": "bedrock/us.anthropic.claude-sonnet-4-6",
        "input-tokens": 14823,
        "output-tokens": 412,
        "error-message": "",
        "created-at": "2026-06-01T12:01:14Z"
      }
    }
  ],
  "meta": { "count": 2 }
}
```

### Post Plan-Summary Chat Message

```
POST /api/v1/runs/{run_id}/plan-summary/messages
Content-Type: application/vnd.api+json

{ "data": { "attributes": { "content": "..." } } }
```

Posts a user follow-up + returns the synchronous assistant reply. Authorisation is read-on-workspace — anyone who can see the run can chat in the thread (GitHub PR conversation semantics, not per-user threads).

**Required permission:** `read` on the workspace.

**Responses:**
- **201 Created** — the response body is the assistant turn (same shape as the GET list entries). The persisted user turn is visible via the next GET call.
- **400 Bad Request** — empty body or body > 32 KiB.
- **409 Conflict** — initial summary not `ready`, or this run already has `followup_max_messages_per_run` user turns. The user-turn counter is **server-tracked, not advisory**.
- **429 Too Many Requests** — daily AI token budget exhausted.
- **503 Service Unavailable** — chat globally disabled (`followup_max_messages_per_run: 0`) or workspace opted out.
- **502 Bad Gateway** — model HTTP / parse failure. The user turn is still persisted in the transcript, and a separate errored assistant row is recorded — so a reload shows the failure cleanly.

The model call uses the same cacheable prefix as the initial summary (provider prompt caching serves the prefix hit). See [docs/ai-plan-summary.md#follow-up-chat-463](ai-plan-summary.md#follow-up-chat-463) for the operator-side caps + provider matrix.

### Apply Details

```
GET /api/v1/runs/{run_id}/apply
```

Returns apply metadata and log download URL.

---

## Cross-Workspace Remote-State Consumers

Producer-controlled allowlist of workspaces authorized to read this workspace's state via `data "terraform_remote_state"`. Default is empty (not shared) — secure by default. All mutations require **admin/write on the producer** (the state owner). Independent of run triggers — see [the composition guide](remote-state.md).

When a runner-token principal (agent-mode run) hits `/api/tfe/v2/workspaces/{id}/current-state-version` or `/api/tfe/v2/state-versions/{id}/download` for another workspace, authorization is by this allowlist instead of per-user RBAC. User / API-token principals (CLI, UI, automation) continue through the existing per-user RBAC path.

### List Consumers

```
GET /api/v1/workspaces/{id}/remote-state-consumers?filter[remote-state-consumer][type]=outbound
```

`outbound` (default) — workspaces this workspace shares its state to (this workspace is the producer).
`inbound` — workspaces whose state this workspace is authorized to read (this workspace is the consumer).

**Required permission:** `read` on the workspace.

### Authorize a Consumer

```
POST /api/v1/workspaces/{producer_id}/remote-state-consumers
```

**Request body:**
```json
{
  "data": {
    "relationships": {
      "consumer": {"data": {"id": "ws-CONSUMER", "type": "workspaces"}}
    }
  }
}
```

**Required permission:** `admin` on the **producer** workspace. A consumer team cannot self-grant.

Errors: `422` self-reference; `409` already authorized; `422` over the per-producer cap.

### Replace Consumer Set (Declarative)

```
PUT /api/v1/workspaces/{producer_id}/remote-state-consumers
```

Idempotent declarative replace of the producer's full consumer set in one atomic transaction. Supports the Terrapod provider's set-valued attribute. Body: `{"data": [{"type": "workspaces", "id": "ws-..."}, ...]}`.

**Required permission:** `admin` on the producer.

### Show Consumer Grant

```
GET /api/v1/remote-state-consumers/{id}
```

**Required permission:** `read` on the producer.

### Revoke a Consumer Grant

```
DELETE /api/v1/remote-state-consumers/{id}
```

**Required permission:** `admin` on the producer. A consumer cannot self-revoke.

### Consumer Grant Response Attributes

| Attribute | Description |
|---|---|
| `producer-workspace-name` | Name of the producer workspace |
| `consumer-workspace-name` | Name of the consumer workspace |
| `created-at` | RFC3339 timestamp the grant was created |
| `created-by` | Identity that created the grant |

Plus relationships `producer` and `consumer` (both `workspaces`-typed).

---

## Run Triggers

Run triggers create cross-workspace dependency chains. When a source workspace completes an apply, all downstream workspaces with an inbound trigger automatically get a new run queued.

### Create Run Trigger

```
POST /api/v1/workspaces/{id}/run-triggers
```

**Request body:**
```json
{
  "data": {
    "relationships": {
      "sourceable": {
        "data": {
          "id": "ws-source-workspace-id",
          "type": "workspaces"
        }
      }
    }
  }
}
```

**Required permission:** `admin` on the destination workspace, **and `read` on
the source workspace**.

The source-side check is new in 2.0 (GHSA-mc7f-xmq4-jgvw). Without it the
destination grant bounded nothing about which workspaces could be named as a
source, so a user holding `admin` on one workspace of their own could post
arbitrary ids and read the answer — an existence-and-name oracle over the whole
fleet. A source the caller cannot read is reported as **404 Workspace not
found**, identical to an id that does not exist: a 403 would confirm the
workspace is there, which is the thing being withheld.

**Validation:**
- Source and destination must be different workspaces
- No duplicate triggers for the same pair
- Maximum 20 source workspaces per destination

**Example:**
```bash
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -X POST \
  https://terrapod.example.com/api/v1/workspaces/ws-abc123/run-triggers \
  -d '{
    "data": {
      "relationships": {
        "sourceable": {
          "data": {"id": "ws-def456", "type": "workspaces"}
        }
      }
    }
  }'
```

### List Run Triggers

```
GET /api/v1/workspaces/{id}/run-triggers?filter[run-trigger][type]=inbound|outbound
```

- `inbound`: triggers where this workspace is the destination (what triggers runs here?)
- `outbound`: triggers where this workspace is the source (what does my apply trigger?)

The `filter[run-trigger][type]` parameter is required (422 if missing).

**Required permission:** `read` on the workspace.

**Example:**
```bash
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://terrapod.example.com/api/v1/workspaces/ws-abc123/run-triggers?filter[run-trigger][type]=inbound"
```

### Show Run Trigger

```
GET /api/v1/run-triggers/{id}
```

**Required permission:** `read` on the destination workspace.

### Delete Run Trigger

```
DELETE /api/v1/run-triggers/{id}
```

**Required permission:** `admin` on the destination workspace.

**Example:**
```bash
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -X DELETE \
  https://terrapod.example.com/api/v1/run-triggers/rt-abc123
```

---

## Configuration Versions

A workspace's uploaded source archives are also browsable from the UI — workspace detail → Configurations tab. The list highlights the current configuration with a `current` badge and supports download + side-by-side diff between any two versions.

![Workspace Configurations](images/workspace-configurations.png)

### Create Configuration Version

```
POST /api/tfe/v2/workspaces/{id}/configuration-versions
```

**Request body:**
```json
{
  "data": {
    "type": "configuration-versions",
    "attributes": {
      "auto-queue-runs": true
    }
  }
}
```

**Response includes:** `upload-url` attribute with a presigned URL for uploading the tarball.

**Required permission:** `write` on the workspace.

### Upload Configuration

```
PUT <upload-url>
Content-Type: application/octet-stream

<tarball bytes>
```

No auth required (presigned URL).

### Show Configuration Version

```
GET /api/tfe/v2/configuration-versions/{cv_id}
```

Returns a single CV's metadata.

### List Configuration Versions

```
GET /api/tfe/v2/workspaces/{id}/configuration-versions
```

Newest first. Supports `page[size]` (default 20, max 100) and `page[number]`.

**Response includes** `meta.current-id` — the CV id consumed by the most recent successful apply, or `null` if none. The UI uses this to badge the current row.

**Required permission:** `read` on the workspace.

### Download Configuration Version (Terrapod extension)

```
GET /api/v1/configuration-versions/{cv_id}/download
```

Streams the tarball bytes back as `application/x-tar` with a `Content-Disposition: attachment` header. Bearer auth.

**Status codes:**
- 200 — streaming tarball
- 404 — CV doesn't exist or caller lacks `read`
- 409 — CV exists but bytes haven't been uploaded yet
- 410 — CV row exists but tarball was swept by retention

**Required permission:** `read` on the owning workspace.

### Mint Download Ticket (Terrapod extension)

```
POST /api/v1/configuration-versions/{cv_id}/download-ticket
```

Mints a short-lived, single-resource HMAC ticket the browser can paste into a plain `<a href>` to stream a download natively to the user's save dialog. **Opt-in** — the default download path above is the simple Bearer-auth flow; tickets exist because plain navigation can't carry an `Authorization` header.

**Request body** (optional):
```json
{"data": {"attributes": {"ttl-seconds": 300}}}
```

TTL defaults to 300 s, hard-capped at 1800 s. Negative or zero values fall back to the default.

**Response:**
```json
{
  "data": {
    "type": "download-tickets",
    "attributes": {
      "ticket": "dlticket:cv:{uuid}:...",
      "url": "/api/v1/configuration-versions/download-by-ticket/dlticket:cv:...",
      "expires-at": "2026-05-07T12:34:56Z"
    }
  }
}
```

**Required permission:** `read` on the owning workspace (same gate as the direct download).

### Download by Ticket (Terrapod extension)

```
GET /api/v1/configuration-versions/download-by-ticket/{ticket}
```

Streams the tarball — no `Authorization` header. The ticket is the auth: HMAC-SHA256 over the resource id, expiry, and minter email, signed with the same key class as runner tokens. Single-resource (a CV-X ticket cannot fetch CV-Y); short TTL bounds replay.

**Status codes:**
- 200 — streaming tarball
- 401 — malformed, expired, or bad-signature ticket
- 410 — CV bytes swept by retention since mint

### Diff Configuration Versions (Terrapod extension)

```
POST /api/v1/configuration-versions/diff
```

Compares two CVs in the same workspace and returns per-file unified diffs.

**Request body:**
```json
{
  "data": {
    "attributes": {
      "from-id": "cv-...",
      "to-id":   "cv-..."
    }
  }
}
```

**Response shape:**
```json
{
  "data": {
    "type": "configuration-version-diffs",
    "attributes": {
      "from-id": "cv-...",
      "to-id":   "cv-...",
      "files": [
        {"path": "main.tf", "type": "modified", "diff": "@@ ... @@"},
        {"path": "vars.tf", "type": "added",    "diff": "..."},
        {"path": "old.tf",  "type": "removed",  "diff": "..."},
        {"path": "logo.png","type": "binary-changed"}
      ],
      "oversized": ["modules/big.zip"],
      "total-files-changed": 4
    }
  }
}
```

**Limits:** per-file 1 MiB (oversized files report only their path), per-pair 32 MiB total (refused with 413 if exceeded). Binary files (NUL byte in first 8 KiB) report only `binary-changed`.

**Status codes:**
- 200 — diff returned
- 404 — either CV missing or caller lacks `read`
- 409 — either CV not yet uploaded
- 410 — bytes swept by retention
- 413 — combined size exceeds the per-pair cap
- 422 — missing ids or cross-workspace request

**Required permission:** `read` on the workspace (both CVs must belong to the same workspace).

---

## Labels

Read-only labels browser (Terrapod extension). All endpoints are RBAC-filtered: results only include labels carried by entities the caller has at least `read` on for that entity's permission model. Editing labels still happens on each entity's own edit page — there is no labels-admin surface.

### List Label Keys

```
GET /api/v1/labels
```

Returns all label keys in use across readable workspaces, modules, providers, and pools, with per-type counts.

**Response shape:**
```json
{
  "data": [
    {"key": "team", "value-count": 4, "by-type": {"workspaces": 12, "modules": 2, "providers": 0, "pools": 1}}
  ]
}
```

### List Values for a Key

```
GET /api/v1/labels/{key}
```

Returns distinct values for `key`, each with per-type counts. Empty `data` is a valid response.

### List Entities for a Label

```
GET /api/v1/labels/{key}/{value}
```

Returns entities tagged with exactly `key=value`, grouped by type.

**Response shape:**
```json
{
  "data": {
    "workspaces": [{"id": "ws-...", "name": "..."}],
    "modules":    [{"id": "mod-...", "name": "...", "provider": "..."}],
    "providers":  [{"id": "prov-...", "namespace": "...", "name": "..."}],
    "pools":      [{"id": "pool-...", "name": "..."}]
  }
}
```

---

## Variables

### List Workspace Variables

```
GET /api/tfe/v2/workspaces/{id}/vars
```

**Required permission:** `read` on the workspace. Sensitive values are never returned.

### Create Variable

```
POST /api/tfe/v2/workspaces/{id}/vars
```

**Request body:**
```json
{
  "data": {
    "type": "vars",
    "attributes": {
      "key": "AWS_REGION",
      "value": "eu-west-1",
      "category": "env",
      "sensitive": false,
      "apply-only": false,
      "description": "AWS region for provider"
    }
  }
}
```

`category` is one of `terraform`, `env`, `git_http_auth`, or `git_ssh_auth`. In agent mode all are delivered to the runner Job via a per-run Kubernetes Secret (never plaintext in the Job spec), and the runner dispatches the delivery on the workspace's engine. (In local execution mode the CLI handles variables itself.)

`terraform` is **the engine's own parameter channel**, not Terraform's alone. Every engine has exactly one — Terraform's input variables, Pulumi's stack config, Ansible's extra vars — and they are the same role, so they are the same category; only the delivery differs. A Terraform run renders the values into a generated `terrapod.auto.tfvars` (honouring `structured`); a Pulumi run sets each with `pulumi config set` against the run's stack, after the stack is selected and before the `pre_plan` hook, with the key passed through **verbatim** — an unqualified `region` is namespaced to the project by the CLI, and an explicit `aws:region` is left alone. On Pulumi, `sensitive` makes it a real secret (`--secret`), so the stack's secrets provider encrypts it and the engine renders it as `[secret]` in the preview, the event log and any state it reaches; `structured` becomes `--path`, so `outer.inner` sets a nested value. It overwrites a committed `Pulumi.<stack>.yaml` key of the same name, leaves keys it does not set alone, and a key that cannot be set **fails the run**. See [Pulumi → Stack configuration](pulumi.md#stack-configuration).

**Two names, one category.** It is stored as `native` — the honest name for a channel that is not Terraform's alone — and the surface you ask decides how it comes back. The TFE-compatible surface (`/api/tfe/v2` and its `/api/v2` alias) returns `terraform` and always will, because `tfci` and `go-tfe` hold that as a constant; `/api/v1` returns `native`. On input, `terraform`, `native` and `pulumi_config` are all accepted anywhere and mean the same thing, so a request written against any of them keeps working. This is the arrangement `structured` already has with `hcl`.

The consumers accept both too, so which name you hold never has to depend on which prefix you read. `go-terrapod` exposes `SameCategory` and uses it wherever a category is compared — `GetVariableByKey` finds the same row whether you ask for `terraform` or `native`. The `terrapod_variable` and `terrapod_variable_set_variable` provider resources accept either and keep the spelling you wrote, so a configuration saying `native` does not drift against a server answering `terraform` (which, on an attribute that forces replacement, would propose destroying and recreating the variable on every plan). Only a genuine change of category — to `env`, say — is reported as drift.

The **UI** names it in the words of the engine you are looking at: a Terraform or OpenTofu workspace shows **Terraform**, a Pulumi workspace shows **Pulumi config**, and a variable set — which is org-scoped and reaches workspaces of either kind — shows **Native**, because there is no single engine whose word would be right. The stored value is the same in all three.

`env` vars are injected via `secretKeyRef`. The two `git_*_auth` categories carry credentials for private git module sources — the `key` is a host/URL pattern and the `value` a JSON credential; they are always forced `sensitive` and consumed by the runner's git-auth phase before `init` (see [Module Source Auth](module-auth.md)), not by terraform/tofu directly.

`structured` marks a value as a typed expression rather than a plain string. What that
means is the engine's: for a Terraform run a raw HCL expression (list, object, number,
bool) rather than a quoted string; for a Pulumi run a nested config path. **`hcl` is the same flag under its original name and is accepted and
returned indefinitely**, because `tfci` and `go-tfe` send and read it; responses carry
both keys and they always agree. Supplying both with *different* values is a `422`
rather than a silent precedence rule — a client that disagrees with itself about
whether a value is typed has a bug worth surfacing.

<a id="apply-only-variables-api"></a>

`apply-only` (boolean, default `false`) **withholds the variable from a plan and
delivers it only to an apply**, so a credential only the apply needs is not in
the environment of a plan — which executes the configuration's code, including a
pull request's. It is accepted on create and on `PATCH`, returned on every read,
and settable on a variable-set variable too (below).

| Phase | What it receives |
|---|---|
| `plan` | Only variables with `apply-only: false`. A key that has *only* an apply-only row is **absent**, not present-and-empty. |
| `apply` | Every variable, with an apply-only row shadowing a standard row of the same key **within its own precedence tier**. |

**A different value per phase is two variables with the same `key`**, one of them
flagged — so a key may appear twice on one workspace (or twice in one variable
set) provided the two rows differ in `apply-only`. The uniqueness constraint is
`(workspace, key, apply-only)`; a genuine duplicate, same key and same flag, is
still refused with `409`.

Precedence is otherwise unchanged — priority variable set > workspace variables >
non-priority variable set — and the shadowing is **within a tier, never across
the chain**: a priority set's standard row still beats a workspace apply-only
row, so a workspace owner cannot escape a platform-mandated value on an apply.

`apply-only` is independent of `sensitive` and of `category`: it says *which
phase receives this value*, not how secret it is, and an apply-only variable is
stored and audited exactly like any other, and covered by the same opt-in
[app-layer encryption](encryption-at-rest.md) when that is enabled. Marking a `git_http_auth`
or `git_ssh_auth` credential apply-only withholds it from the plan's `init`,
which is rarely what is wanted. Full semantics:
[Cloud Identity → Apply-only variables](cloud-identity.md#apply-only-variables).

**Required permission:** `write` on the workspace.

### One category, whatever the engine

There is no engine-specific variable category, and there used to be. `terraform`
(stored as `native`) is every engine's parameter channel; `env` and the two
`git_*_auth` categories apply whatever engine runs. So a variable cannot sit in
a category its workspace's engine will never read, and the two signals that
reported that state — a variable's `applies-to-engine` attribute and the
workspace's `variables_not_consumed` health condition — are **gone**. Both were
consolation for a shape that should not have existed.

Nothing reports config that a program was handed and never read: no engine
offers that signal.

### Update Variable

```
PATCH /api/tfe/v2/workspaces/{id}/vars/{var_id}
```

### Delete Variable

```
DELETE /api/tfe/v2/workspaces/{id}/vars/{var_id}
```

**Required permission:** `write` on the workspace.

---

## Variable Sets

### List Variable Sets

```
GET /api/tfe/v2/organizations/default/varsets
```

### Create Variable Set

```
POST /api/tfe/v2/organizations/default/varsets
```

**Required permission:** Platform `admin`.

### Variable Set Variables

```
GET    /api/tfe/v2/varsets/{varset_id}/relationships/vars
POST   /api/tfe/v2/varsets/{varset_id}/relationships/vars
PATCH  /api/tfe/v2/varsets/{varset_id}/relationships/vars/{var_id}
DELETE /api/tfe/v2/varsets/{varset_id}/relationships/vars/{var_id}
```

A variable-set variable carries the same attributes as a workspace variable —
`key`, `value`, `category`, `hcl`, `sensitive`, `value-source`, `description` —
and the same [`apply-only`](#apply-only-variables-api) boolean, with the same
meaning and the same default of `false`. Its uniqueness constraint is
`(variable set, key, apply-only)`, so one set may hold a standard and an
apply-only row for the same key and a true duplicate is still `409`.

The shadowing stays inside the set's own precedence tier: an apply-only row in a
**priority** set beats that set's standard row on an apply, while a priority
set's standard row still beats a workspace apply-only row. See
[Cloud Identity → How it interacts with
precedence](cloud-identity.md#how-it-interacts-with-precedence).

### Variable Set Workspace Assignments

```
POST   /api/tfe/v2/varsets/{varset_id}/relationships/workspaces
DELETE /api/tfe/v2/varsets/{varset_id}/relationships/workspaces
```

**Required permission:** Platform `admin`.

<a id="vault-value-source"></a>

### OpenBao/Vault Value Source

A variable's `value-source` is `static` (the default — `value` is the literal)
or `vault`, where `value` holds a JSON reference to a secret in OpenBao (or
HashiCorp Vault), resolved at run time. The value source is named `vault` for
both servers:

```json
{
  "data": {
    "type": "vars",
    "attributes": {
      "key": "NETBOX_TOKEN",
      "category": "env",
      "value-source": "vault",
      "value": "{\"mount\":\"secret\",\"path\":\"apps/netbox\",\"field\":\"apitoken\"}"
    }
  }
}
```

The reference takes `mount`, `path` and `field`; optionally `vault` (which
configured instance), `engine` (`kv2` default, or `dynamic`), `method` (`GET`
default, or `POST`) and `data` (a body for `POST` engines). The `path` omits
kv-v2's `data/` segment — Terrapod adds it.

An optional `file` object delivers the value as a file instead:
`"file": {"name": "gcp/adc.json"}` writes it to
`/var/run/terrapod/files/gcp/adc.json`, and `"file": {"name": "~/.aws/credentials"}`
to `/home/runner/.aws/credentials`. `name` defaults to the variable key. The
variable's delivered value becomes the file's absolute path, for `env` and
`terraform` variables alike. A name must be a relative path of
`[A-Za-z0-9._-]` segments (no `.`, `..` or empty segment, at most 255
characters), and a `~/` name may not target a path the runner manages.

The file's content is exactly one of:

| Key | Content |
|---|---|
| `field` (on the reference) | That field. With `"file": {"encoding": "base64"}` it is base64-decoded first; the result must be UTF-8 text. |
| `file.template` | A logic-less template over the secret, at most 16 KiB: `{{ name }}`, `{{ map.key }}`, filters `json`, `base64decode`, `trim`, `lines`, `indent N`, and `{{ _lease.ttl }}` / `_lease.renewable` / `_lease.expires_at` when the response has a lease. No `field`. |
| `file.format` | `json` (the whole data map) or `env` (`KEY="value"` lines); `file.fields: [...]` selects a subset. No `field`. |

`file` is refused with `422` together with `structured` (or its alias `hcl`),
on a `static` value source, with any unknown key (`mode` is reserved), when more than one of `field`,
`file.template` and `file.format` is given, for a template syntax error or an
unknown filter, for `fields` without `format`, and for `encoding` with a
template or format. An unknown template name, invalid base64, non-UTF-8 decoded
bytes, two variables at one path, a rendered file over 256 KiB, or OpenBao/Vault files
totalling over 768 KiB in one run error the run. Variables naming the same
secret share one read per run, so fields of one dynamic credential always
match — including every field a template uses. Details:
[Delivering as a file](vault.md#delivering-as-a-file),
[Templates, formats and encoding](vault.md#templates-formats-and-encoding).

A vault-sourced variable is **always sensitive**, but the API returns its
`value` rather than masking it: the stored value is a path, not a secret. The
secret it points at is resolved per run and never persisted, returned or
logged. A malformed reference is rejected at write time with `422`; one that
cannot be resolved **fails the run** rather than delivering nothing.

Applies to variable-set variables too, so an OpenBao/Vault-backed credential can be
defined once and applied to many workspaces.

```
GET /api/v1/vault/availability
```

Reports whether the value source is configured and which instances exist, so a
client can offer it only where it will work. Returns instance **names** only —
never addresses, namespaces or auth configuration. Any authenticated user may
call it, since anyone who can write a variable needs to pick an instance.

<a id="vault-diagnostics"></a>

#### OpenBao/Vault diagnostics

```
GET /api/terrapod/v1/admin/vault
```

The sampled status of each configured instance. It needs platform `admin` or
`audit`. It is read from a sample the `vault_status` scheduler task takes every
60 seconds, never by contacting the server on the request. A collection of
`vault-instance-statuses`, one per configured instance, with `id` set to the
instance name:

```json
{"data": [{"id": "default", "type": "vault-instance-statuses", "attributes": {
   "name": "default", "default": true, "address": "https://openbao:8200", "namespace": "",
   "auth-method": "kubernetes", "auth-mount": "kubernetes", "auth-role": "terrapod",
   "tls-trust": "instance-ca", "reachable": true, "initialized": true, "sealed": false,
   "standby": false, "version": "1.18.0", "health-error": null,
   "login-ok": true, "login-error": null, "ttl-seconds": 1740,
   "checked-at": "2026-09-15T10:00:00Z",
   "last-error": {"class": "VaultDenied", "at": "2026-09-15T09:12:03Z",
     "message": "variable 'NETBOX_TOKEN': OpenBao/Vault denied 'secret/apps/netbox' on instance 'default'. …"}}}],
 "meta": {"pagination": {…},
   "vault": {"enabled": true, "sampled-at": "2026-09-15T10:00:00Z", "unavailable-reason": null}}}
```

`tls-trust` is `instance-ca`, `global-bundle`, `default` or `skip-verify`.
Every probe field is `null` when unknown (not sampled yet, or not attempted:
a sealed server is never logged in to), which is not the same as `false`. With
the value source off, `data` is empty and `meta.vault.enabled` is `false`.
`unavailable-reason` is `not sampled yet` or `cache unreachable` when there is
no usable sample.

```
POST /api/terrapod/v1/workspaces/{workspace_id}/vault-reference-checks
POST /api/terrapod/v1/varsets/{varset_id}/vault-reference-checks
```

Checks a reference without resolving it. The workspace form needs `var:write`
on the workspace; the variable-set form needs platform admin. Limited to 20
checks a minute per user (`429` with `Retry-After`). The body carries
`reference` (a reference object, or its JSON string) or `variable-id` (a
stored vault-sourced variable), plus an optional `key`, which a file name
defaults to:

```json
{"data": {"type": "vault-reference-checks",
  "attributes": {"reference": {"mount": "secret", "path": "apps/netbox", "field": "apitoken"}}}}
```

A reference that does not parse is a `200` result with `parses: false`, not an
error. `404` means an unknown workspace, variable set or variable; `422` means
a body with neither `reference` nor `variable-id`, or a variable whose source
is not `vault`. Nothing is stored, and the `id` only tells two answers apart:

```json
{"data": {"id": "vrc-…", "type": "vault-reference-checks", "attributes": {
   "ok": false, "vault-enabled": true, "parses": true, "parse-error": null,
   "instance": "default", "instance-known": true, "engine": "kv2",
   "read-path": "secret/data/apps/netbox", "path-allowed": true,
   "readable": true, "capabilities": ["read", "list"], "required-capabilities": ["read"],
   "keys": ["apitoken", "url"], "fields-present": true, "missing-fields": [],
   "notes": [],
   "checks": [{"name": "parses", "status": "pass", "detail": ""},
              {"name": "instance", "status": "pass", "detail": ""},
              {"name": "path-allowed", "status": "pass", "detail": ""},
              {"name": "readable", "status": "pass", "detail": ""},
              {"name": "fields-present", "status": "pass", "detail": ""}]}}}
```

`checks` runs in order and stops at the first `fail`. A step's `status` is
`pass`, `fail`, `skipped` or `unknown`, where `unknown` means the server could not
answer. `readable` comes from `sys/capabilities-self`, which reads nothing at
the path. `keys` holds key **names**, for kv-v2 only; it is `null` for a
dynamic engine, which a check never reads because a read mints a credential,
and `null` for a caller without `run:plan`. `notes` holds codes:
`dynamic-not-read`, `keys-need-plan-permission`, `local-execution` and
`vault-disabled`. See
[OpenBao/Vault → Diagnostics](vault.md#diagnostics).

Full setup, including the server-side policy and role: [OpenBao/Vault](vault.md).

### Assignment Rules

A variable set can select workspaces by their attributes instead of being bound
to each one by hand. Set `assignment-rule` on create or update:

```json
{
  "data": {
    "attributes": {
      "name": "prod-credentials",
      "assignment-rule": { "labels": { "env": "prod" } }
    }
  }
}
```

The rule accepts the workspace bulk-update selector's *attribute* dimensions --
`labels`, `name_prefix`, `name_glob`, `execution_backend`,
`execution_mode`, `terraform_version`, `agent_pool_id`, `vcs_connection_id`,
`owner_email`, `drift_status`, `locked`, `has_vcs` -- all AND-combined.
Membership is re-evaluated on every run, so a workspace that later matches picks
the set up without being touched, and one that stops matching stops receiving it.

Rejected with `422`: an unparseable rule; a non-object rule; `all: true` (use
`global`, which already means every workspace); `workspace_ids` (that is
explicit assignment, and would produce a rule whose membership never
re-evaluates); a rule on a set that is already `global`; and a rule whose
dimensions are all blank -- `{"name_prefix": ""}` selects nothing meaningful and
would otherwise match every workspace.

A rule that no longer parses matches **nothing** rather than everything, so a
filter dimension removed in a later version cannot silently widen a scoped
credential set to the whole estate.

<a id="labels-are-not-a-credential-trust-boundary"></a>

#### Labels are not a credential trust boundary

**An assignment rule selects on attributes a workspace's own owner controls.**
Labels, name, execution mode, engine version, agent pool, VCS connection and the
rest are all settable by whoever has `admin` on the workspace — and workspace
creation is open, with the creator becoming owner. So a rule is a convenient way
to describe a fleet; it is **not** an authorization check, and a variable set has
no per-set permissions for one to appeal to.

Treat a rule-scoped set exactly as widely trusted as the attribute it selects on.
Specifically:

- **Do not** rely on a label to keep a credential away from someone who can
  create or administer a workspace. If the set holds something only one team may
  have, assign it to that team's workspaces **explicitly**, or keep it in those
  workspaces' own variables.
- **Review the rule, not just the membership**, when you add a credential to an
  existing set. The blast radius is "every workspace that can be made to match",
  which is larger than "every workspace that matches today".

Terrapod enforces the one invariant it can without an entitlement to consult: a
caller who is **not** a platform admin may not make a workspace match a
rule-assigned set **that holds a sensitive or broker-resolved value** and that it
does not already match. A rule-assigned set of plain configuration joins freely. That covers workspace create and
workspace `PATCH` — the paths where the attributes are chosen — and is a **403**;
see [Refusals on create and update](#refusals-on-create-and-update). It is a
behaviour change: a non-admin who previously created workspaces that joined a
rule-scoped set now needs an admin to make the change, or an explicit assignment.
Shrinking is always allowed, as is any edit to a workspace that already matches.
(GHSA-49q6-pm68-3xgw)

### Association Views

Read-only views of which workspaces a set reaches, and which sets reach a
workspace. Both report *how* each association arose -- `explicit`, `global`, or
`rule` -- because only an explicit one can be unbound.

```
GET /api/v1/varsets/{varset_id}/relationships/workspaces
GET /api/v1/workspaces/{workspace_id}/varsets
```

`workspace-count` on the variable set itself counts only explicitly-assigned
workspaces; for a global or rule-based set it is not the whole answer, and these
views are.

**Required permission:** platform `admin` for the varset-side view;
`workspace:read` for the workspace-side view.

---

## Registry -- Modules

### CLI Protocol (for terraform init)

```
GET /api/tfe/v2/registry/modules/{namespace}/{name}/{provider}/versions
GET /api/tfe/v2/registry/modules/{namespace}/{name}/{provider}/{version}/download
```

### Terrapod-native Management API

```
GET  /api/v1/registry-modules
POST /api/v1/registry-modules
GET  /api/v1/registry-modules/private/default/{name}/{provider}
DELETE /api/v1/registry-modules/private/default/{name}/{provider}
PUT  /api/v1/registry-modules/private/default/{name}/{provider}/versions/{version}/upload
DELETE /api/v1/registry-modules/private/default/{name}/{provider}/versions/{version}
```

**Submodules.** Create, `PATCH …/{name}/{provider}` and `PATCH …/{name}/{provider}/vcs` accept an optional `subdirectory`: the path within the module's repository to publish it from, for a submodule (see [Submodules](registry.md#submodules-a-module-in-a-subdirectory)). It needs a `vcs-repo-url`; a path with `..`, `.` or empty segments is refused with `422`, and a repository subdirectory that is already registered with `409`. Modules report it as the `subdirectory` attribute, `""` for a module at the repository root. On `PATCH …/vcs`, omitting it leaves it unchanged; removing the repository clears it.

**Autodiscovery.** To find the modules in a repository — the root and any submodules — and register them in bulk, use [Module Autodiscovery Rules](#module-autodiscovery-rules).

**Naming a VCS connection is authorized.** Module creation is open to any
authenticated user, and a VCS-sourced module names a connection plus an arbitrary
`vcs-repo-url` that the registry poller then clones with that connection's
credential. So create, `PATCH …/{name}/{provider}` and `PATCH …/{name}/{provider}/vcs`
all check the caller's claim to the connection and answer **403** without one, on
the same four claims the workspace paths use — see
[Authorization and repository scope](#connection-authorization-attributes).
### Module Version Interface

```
GET /api/v1/registry-modules/private/default/{name}/{provider}/{version}/interface
```

Returns the version's extracted `inputs[]` and `outputs[]`, and `interface-error`: `null` when the interface was read, otherwise a short, display-safe reason it could not be (a corrupt archive, or each root `.tf` file that failed to parse). When it is set, empty or partial `inputs` do **not** mean the module declares no variables. Each entry of a module's `version-statuses` carries the same `interface-error`. See [When the interface cannot be read](registry.md#when-the-interface-cannot-be-read). **Required permission:** `read` on the module. `404` when interface extraction is disabled or the version does not exist.

### Update Module

```
PATCH /api/v1/registry-modules/private/default/{name}/{provider}
```

**Required permission:** `admin` on the module.

**Self-lockout protection:** If the request changes `labels` and the new labels would reduce the caller's own access level, the API returns **409 Conflict**. Re-submit with `"force": true` in the attributes to confirm.

### Module Permissions Block

All module responses (show and list) include a `permissions` object:

```json
{
  "permissions": {
    "can-update": true,
    "can-destroy": true,
    "can-create-version": true
  }
}
```

### Version Upload (Streamed)

```
PUT /api/v1/registry-modules/private/default/{name}/{provider}/versions/{version}/upload
```

A single streamed `PUT` of the gzipped module source tarball. The version
is created **implicitly on upload** — there is no separate create step and
no presigned URL. The server extracts the module interface (inputs and
outputs) — the response's `interface-error` attribute is `null` when that
succeeded and a short reason when it did not — and triggers impact runs on any linked workspaces (see
[Module Impact Analysis](#registry----modules) and the workspace-links
section below).

**Required permission:** `write` on the module (the owner has `admin`).

**A published version is immutable, and the server enforces that** (new in 2.0,
GHSA-mhhr-896g-4p33). Re-uploading a version that already holds bytes answers
**409 Conflict** and stores nothing. It used to upsert and replace them in place
— and module consumers do not hash-lock, so every workspace pinned to that
version silently picked up different source on its next init. Publish a new
version instead; if a published one genuinely has to go, delete it first (that is
`registry:admin`, and audited).

Completing a version whose first attempt failed is still allowed: a row that
never reached `uploaded` is a resumed publish, not an overwrite, so a failed
upload does not strand the version number. The VCS tag poller has its own path
and is unaffected — a **moved tag** deliberately updates its version in place,
because there the tag rather than the version is the author's statement.

**Tooling:** the [`terrapod-publish`](registry-publishing.md) CLI packages
the source directory and performs this upload.

> **Removed in the client-signed model:** the previous
> `POST .../versions` create-then-upload-to-presigned-URL flow has been
> **removed** in favour of the single streamed `PUT` above.

### Workspace Links (Module Impact Analysis)

```
GET    /api/v1/registry-modules/private/default/{name}/{provider}/workspace-links
POST   /api/v1/registry-modules/private/default/{name}/{provider}/workspace-links
DELETE /api/v1/registry-modules/private/default/{name}/{provider}/workspace-links/{link_id}
```

**Required permission:** `admin` on the module (create/delete), `read` on the module (list).

**Terraform provider resource:** `terrapod_module_workspace_link`

---

## Registry -- Providers

### CLI Protocol (for terraform init)

```
GET /api/tfe/v2/registry/providers/{namespace}/{type}/versions
GET /api/tfe/v2/registry/providers/{namespace}/{type}/{version}/download/{os}/{arch}
```

The download response advertises the **publisher's own** GPG public key
in `signing_keys.gpg_public_keys`. Terrapod never re-signs a provider — the
signature `terraform init` verifies is the one the publisher produced at
publish time (see [Publishing a Version](#publishing-a-version-client-signed)).

### Terrapod-native Management API

```
GET  /api/v1/registry-providers
POST /api/v1/registry-providers
GET  /api/v1/registry-providers/private/default/{name}
DELETE /api/v1/registry-providers/private/default/{name}
GET  /api/v1/registry-providers/private/default/{name}/versions
DELETE /api/v1/registry-providers/private/default/{name}/versions/{version}
```

### Publishing a Version (Client-Signed)

Provider publishing is **client-signed, direct, and streamed**. The
publisher computes `SHA256SUMS` over the platform zips and GPG-signs it
with its own key; the server verifies that signature against a
**registered** GPG public key and never re-signs. The version is created
**implicitly on the first upload** — there is no separate create-version
or finalize step.

Uploads must happen in this exact order:

```
PUT /api/v1/registry-providers/private/default/{name}/versions/{version}/shasums
PUT /api/v1/registry-providers/private/default/{name}/versions/{version}/shasums.sig
PUT /api/v1/registry-providers/private/default/{name}/versions/{version}/platforms/{os}/{arch}
```

1. **`PUT .../shasums`** — the raw `SHA256SUMS` manifest (one
   `{sha}  {zipname}` line per platform).
2. **`PUT .../shasums.sig`** — the detached GPG signature over the
   manifest. **The server verifies it against a registered GPG key here
   (the trust gate).** Returns **422** if the key isn't registered or the
   signature doesn't verify. Binaries are refused until this succeeds.
3. **`PUT .../platforms/{os}/{arch}`** (one per platform) — each zip is
   streamed to disk and its SHA checked against the signed manifest.
   Returns **422** on a SHA mismatch, or if the signature has not yet been
   verified.

**Required permission:** `write` on the provider (the owner has `admin`).

**Tooling:** the [`terrapod-publish`](registry-publishing.md) CLI performs
these three uploads (in order) and does all packaging, hashing, and GPG
signing client-side. The server never re-signs — the
[download response](#cli-protocol-for-terraform-init) advertises the
publisher's own public key in `signing_keys.gpg_public_keys`.

> **Removed in the client-signed model:** the previous presigned-URL
> flow — `POST .../versions` (create version) and
> `POST .../versions/{version}/platforms` (create platform, returning a
> presigned upload URL) — has been **removed**. There is no
> server-side re-signing and no presigned-URL or finalize step for
> provider versions. Use the three streamed `PUT` endpoints above.

### Update Provider

```
PATCH /api/v1/registry-providers/private/default/{name}
```

**Required permission:** `admin` on the provider.

**Self-lockout protection:** If the request changes `labels` and the new labels would reduce the caller's own access level, the API returns **409 Conflict**. Re-submit with `"force": true` in the attributes to confirm.

### Provider Permissions Block

All provider responses (show and list) include a `permissions` object:

```json
{
  "permissions": {
    "can-update": true,
    "can-destroy": true,
    "can-create-version": true
  }
}
```

### GPG Keys

| Endpoint | Permission |
|---|---|
| `GET /api/v1/gpg-keys` | Any authenticated caller |
| `GET /api/v1/gpg-keys/{id}` | Any authenticated caller |
| `POST /api/v1/gpg-keys` | `registry:admin` |
| `POST /api/v1/gpg-keys/{id}/revoke` | `registry:admin` |
| `DELETE /api/v1/gpg-keys/{id}` | `registry:admin` |

**The read/write split is deliberate.** The reads return public key material —
the same bytes `terraform init` receives in every provider download response —
so gating them would protect nothing while removing the ability to check which
keys an instance trusts. A *registration* is the opposite: it adds a trust
anchor, and every provider version signed by that key becomes installable by
every runner on the instance.

**The writes were open before v1.4.0** (authentication alone sufficed), so a
service token that registers keys now needs a role granting registry admin —
see [registry-publishing.md](registry-publishing.md#1-register-the-publishers-gpg-public-key).
Grant it with `registry_permission = "admin"` and **no** `allow_names` or
`allow_labels`: a role scoped to part of the registry cannot register a key,
because a key is not scoped to part of the registry. Denied requests return
`403 Requires registry:admin capability on the GPG key store`.

The **public** key registered here is the trust anchor for client-signed
provider publishing: `PUT .../shasums.sig` is verified against it. Register
a key before publishing a provider (or use the `terrapod_gpg_key` provider
resource). See [Publishing to the Private Registry](registry-publishing.md).

**Revoke a key** (`.../gpg-keys/{id}/revoke`) — POST an owner-issued revocation
certificate (the armored output of `gpg --gen-revoke`) as the
`revocation-certificate` attribute. Terrapod verifies it is a valid **self**
key-revocation for the registered key, then stores the revoked key so **all**
provider and runner signature verification fails closed for it — a revoked
signing key can no longer verify anything, even already-published artifacts it
signed. The key stays registered (auditable) rather than being deleted. Returns
422 if the certificate is not a genuine self-revocation for the key. (Signature
verification honors revocation without shelling out to `gpg`; #640.)

---

## Agent Pools

### Pool Response Attributes

| Attribute | Type | Notes |
|---|---|---|
| `name` | string | Unique pool name |
| `description` | string | Free text, `""` when unset |
| `labels` | object | Label map used for pool RBAC |
| `owner-email` | string / null | Owner gets `admin` on the pool |
| `created-at` / `updated-at` | RFC3339 | |
| `status` | string | `online` if at least one listener could take work, `degraded` if every live listener has an expired certificate, else `offline` |
| `listener-count` | integer | Listener **identities** that could take work — derived from the same predicate as `status`, so the two can never disagree. A listener that heartbeats with an expired certificate 401s every authenticated call and is not counted |
| `listener-pod-count` | integer | **Pods** backing those listeners. Replicas of one Deployment share a listener identity, so a redundant pair reports `listener-count: 1` and `listener-pod-count: 2`. **Omitted entirely when unknown** — a listener on a pre-0.19.0 image does not report its pod name, and reporting zero would read as an outage. `0` is meaningful: the listener tracks pods and none are currently heartbeating |
| `permission` | string | The calling user's resolved permission on this pool (`read`, `write`, `admin`) |

`status` and both counts are present on the list and show endpoints; they are
omitted from create/update responses, which do not fetch listeners.

### List Pools

```
GET /api/v1/agent-pools
```

### Create Pool

```
POST /api/v1/agent-pools
```

**Request body:**
```json
{
  "data": {
    "type": "agent-pools",
    "attributes": {
      "name": "aws-prod",
      "description": "Production AWS runners"
    }
  }
}
```

**Required permission:** Platform `admin`.

### Show Pool

```
GET /api/v1/agent-pools/{id}
```

### Delete Pool

```
DELETE /api/v1/agent-pools/{id}
```

### Pool Tokens

```
POST /api/v1/agent-pools/{id}/authentication-tokens
GET  /api/v1/agent-pools/{id}/authentication-tokens
```

### Listener Join

```
POST /api/v1/agent-pools/join
```

Registers a listener using a join token. The token identifies the pool — no pool ID needed in the URL. No Bearer auth required; the join token in the body IS the credential.

**Request body:**
```json
{
  "join_token": "<raw-token>",
  "name": "my-listener"
}
```

**Response:** listener ID, pool ID, X.509 certificate, private key, CA certificate.

If a listener with the same name already exists, its certificate is reissued (handles pod restarts).

**Legacy endpoint** (still supported):
```
POST /api/v1/agent-pools/{pool_id}/listeners/join
```

### Listener Heartbeat

```
POST /api/v1/listeners/{id}/heartbeat
```

### Listener Certificate Renewal

```
POST /api/v1/listeners/{id}/renew
```

### Listener Run Polling

```
GET /api/v1/listeners/{id}/runs/next
```

Returns the next queued run for this listener.

**`vault-files`** (added in v1.7.0) carries the [OpenBao/Vault](vault.md)
secrets a variable asked to be delivered as files: a list of
`{name, path, secret_key, value}`, which the listener writes into the run's
existing per-run Secret and mounts read-only. The variable's own value is the
file's path, so the secret itself never travels in `terraform-vars` or
`env-vars`. A listener older than 1.7 ignores the attribute, and the run then
fails with a variable naming a file that was never written — so upgrade
listeners before using file delivery, as
[Vault → Older listeners](vault.md#older-listeners) sets out. Like every other
attribute on this endpoint, it is part of the frozen runner/listener wire
contract.

### Listener Runner Token

```
POST /api/v1/listeners/{id}/runs/{run_id}/runner-token
```

Generates a short-lived HMAC-signed runner token scoped to the specified run. Called by the listener after claiming a run.

**Request body (optional):**
```json
{
  "ttl": 3600,
  "phase": "plan"
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `ttl` | integer | `runners.tokenTTLSeconds` (default 3600) | Requested token lifetime in seconds. Clamped to `runners.maxTokenTTLSeconds` (default 7200) — the response's `expires_in` reports the clamped value. **Must be a positive integer**: anything else is `422`, including a boolean. A non-positive `maxTokenTTLSeconds` no longer means *no cap* — it falls back to the shipped default with a warning, so an unbounded runner token cannot be configured by accident |
| `phase` | string | — | The Job's phase, `plan` or `apply`. Bound into the token so it cannot drive the other phase's endpoints (GHSA-xmrf-hxq9-m59m, new in 2.0). Omitted or unrecognised mints an unphased token |

**Response:**
```json
{
  "token": "runtok:{run_id}:{phase}:{ttl}:{timestamp}:{hmac_sig}",
  "expires_in": 3600,
  "phase": "plan"
}
```

Two token forms exist and **both are accepted indefinitely**:

```
runtok:{run_id}:{phase}:{ttl}:{timestamp}:{hmac_sig}   # a phase claimed
runtok:{run_id}:{ttl}:{timestamp}:{hmac_sig}           # no claim
```

Field count distinguishes them. A request that sends no `phase` gets the second
form and `"phase": null` — which is what a listener image older than the claim
produces, and it keeps working: an absent claim is read as "no claim", so the
phase checks are skipped rather than failing. `phase` is echoed in the response
so a listener can tell whether the server bound one. Both parts of the wire are
additive, so neither upgrade order breaks a run. Which endpoints check the claim
is set out in
[runners.md → Per-phase auth Secret](runners.md#per-phase-auth-secret).

**Auth:** Listener certificate.

### Listener Status Update

```
PATCH /api/v1/listeners/{id}/runs/{run_id}
```

Reports run status changes (planning, planned, applying, configuring, applied, errored).

**`configuring` is native-only, and `applied` means applied *and* configured.** A run that
carries an Ansible configure operation sits in `configuring` between `applying` and
`applied`, so run triggers, notifications and drift — all of which key off `applied` — fire
once the whole run is done rather than once the infrastructure half is.

On the frozen `/api/tfe/v2` surface `configuring` **folds to `applying`**, because `go-tfe`
switches on a fixed status set and cannot be given a value it was not compiled with. That is
not a loss of information for a CLI: from `terraform`'s or `tofu`'s side the configure is
part of the apply — its log is concatenated onto the apply log, the apply sub-resource reads
`running` throughout, and the terminal status the CLI finally reads is the composite result.
`/api/v1` returns the real value, which is what the UI, the provider and the MCP tools read.

A failed apply is never followed by a configure, so a run that errors in the apply reports
the apply's own result.

---

## VCS Connections

### List Connections

```
GET /api/v1/vcs-connections
```

### Create Connection

```
POST /api/v1/vcs-connections
```

**GitHub example:**
```json
{
  "data": {
    "type": "vcs-connections",
    "attributes": {
      "name": "my-github",
      "provider": "github",
      "github-app-id": 12345,
      "github-installation-id": 67890,
      "github-account-login": "my-org",
      "github-account-type": "Organization",
      "private-key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
      "webhook-secret": "optional-per-connection-secret"
    }
  }
}
```

> `webhook-secret` (optional, both providers) is **write-only** — it is never
> returned; the response carries `has-webhook-secret` (boolean) instead. When
> set, this connection's inbound webhooks are validated against it: GitHub
> deliveries are HMAC-SHA256 verified, GitLab deliveries are matched against
> the `X-Gitlab-Token` header (timing-safe). GitHub falls back to the global
> `vcs.github.webhook_secret` when the per-connection secret is absent. On
> `PATCH`, supply a non-empty value to rotate, an explicit empty string to
> clear, or omit the key to leave it untouched.

**GitLab example:**
```json
{
  "data": {
    "type": "vcs-connections",
    "attributes": {
      "name": "my-gitlab",
      "provider": "gitlab",
      "token": "glpat-xxxxxxxxxxxxxxxxxxxx"
    }
  }
}
```

**Required permission:** Platform `admin`.

<a id="connection-authorization-attributes"></a>

#### Authorization and repository scope

Read-write, on every connection in the create, update, list and show responses.
They decide **who** may point a workspace or registry module at this connection
and **where** it may be pointed. None of the three is a secret — the credential
is, and that is still write-only. (GHSA-v8g7-pqrj-8mcm)

| Attribute | Type | Description |
|---|---|---|
| `owner-email` | string | The connection's owner, who may name it. `""` when unset. |
| `labels` | object | Key-value labels. A caller whose roles reach them may name the connection — the same allow/deny evaluation every labelled resource gets. Validated on create as well as update, so a reserved label key cannot be accepted on one path and then trap the connection on the other. |
| `allowed-repositories` | array of strings | Glob patterns this connection may be pointed at. **Empty means any repository the credential can reach** — narrowing is opt-in, so an upgraded deployment is unchanged until an operator sets it. |

A connection may be named by a platform admin, by its `owner-email`, by a caller
whose roles reach its `labels`, or by a caller who already owns a workspace using
it. Anything else is **403**. Patterns in `allowed-repositories` are matched
against both the full URL as stored and the `owner/name` path with any `.git`
suffix removed, so `platform-team/*` and
`https://github.example.com/platform-team/*` both work; `*` crosses `/`, and
patterns are case-sensitive. Full semantics, including every point the
allowlist is enforced at, are in
[VCS integration → Naming a VCS connection is authorized](vcs-integration.md#naming-a-vcs-connection-is-authorized).

On `PATCH` each of the three is applied only when its key is **present**:
omitting one leaves it alone, and an explicitly empty value clears it — so
`"allowed-repositories": []` means "allow any repository again".

A `labels` value that is not an object, and an `allowed-repositories` that is not
a list of strings, are both rejected with `422`. So is a **reserved** label key,
and so is an `allowed-repositories` whose entries are all blank — that one matters
because blanks are stripped, and an empty list means *any* repository, so silently
dropping them would answer `200` having made the connection **wider** than it was.
Send `[]` when you mean "any". Reserved keys are listed under
[RBAC → Reserved Label Keys](rbac.md#reserved-label-keys) and there is no reason
to send one.

### Show Connection

```
GET /api/v1/vcs-connections/{id}
```

#### API budget and consumption attributes

Read-only, on every connection in both the list and show responses. They report
the provider allowance and how fast it is being spent. Everything here is derived
from rate-limit headers providers already return, so it costs no extra API calls
— and is an observation as of the last call Terrapod made, not a live query.

| Attribute | Type | Description |
|---|---|---|
| `rate-limit` | integer \| null | Total budget the provider reports. `null` when the server reports no rate limit at all |
| `rate-limit-remaining` | integer \| null | Requests left in the current window. `0` (exhausted) and `null` (not reported) are different — do not conflate them |
| `rate-limit-resource` | string \| null | Metered resource (GitHub meters `core`, `search` and `graphql` separately) |
| `rate-limit-reset-at` | RFC3339 \| null | When the budget refills |
| `rate-limit-observed-at` | RFC3339 \| null | When the reading was taken |
| `calls-per-hour` | integer \| null | Calls counted over the rate window |
| `rate-window-minutes` | integer \| null | Width of that window (60) |
| `seconds-to-reset` | integer \| null | Seconds until the budget refills |
| `saturation` | string \| null | `idle` \| `comfortable` \| `tight` \| `will_exhaust` \| `exhausted` |
| `exhausts-in-seconds` | integer \| null | Projected seconds until the budget runs out at the current rate; `null` when it will not |
| `top-consumers` | array | `{name, kind, calls}`, descending. `kind` is `workspace`, `module`, `policy-set`, or the subsystem when a call has no owning entity |
| `label-totals` | array | `{label, key, value, calls}`, descending — calls attributed to consumers carrying each label |
| `budget-window-seconds` | integer \| null | How long the provider's allowance refills over, inferred from the reset distance. **Do not assume an hour** — GitHub meters 5,000/hour, GitLab.com 2,000/minute. Scale `calls-per-hour` to this before reading it as a share of `rate-limit`. Null when no budget is reported. |
| `consumers-window-total` | integer | Total calls across **all** consumers over the window `top-consumers` covers. Each entry's share divides by this; dividing by `calls-per-hour` mixes bases. |

**`saturation` is the attribute to act on, not `rate-limit-remaining`.** The
budget refills on a fixed window, so the remaining count reads healthy right
after a reset however fast it is being spent; the verdict compares projected
spend over the rest of the window against what is actually left. See
[VCS integration → Reading the consumption indicator](vcs-integration.md#reading-the-consumption-indicator).

### Update Connection

```
PATCH /api/v1/vcs-connections/{id}
```

Partial update — only the attributes you include are changed. Notes:

- `provider` is **immutable**. A different provider is a different connection; delete and recreate to change it (sending a different `provider` returns `422`).
- Credentials (`private-key` for GitHub, `token` for GitLab) are **write-only**: they are never returned, and are only rotated when you send a non-empty value. Omit them to change the name/server-url/status without touching the stored credential.
- Editable: `name`, `server-url`, `status` (`active`/`disabled`), the GitHub App identifiers (`github-app-id`, `github-installation-id`, `github-account-login`, `github-account-type`), and the three authorization attributes `owner-email`, `labels` and `allowed-repositories` (see [Authorization and repository scope](#connection-authorization-attributes)). Changing `github-installation-id` to one already used by another connection returns `422`.

```json
{
  "data": {
    "type": "vcs-connections",
    "attributes": { "name": "renamed", "server-url": "https://github.example.com/api/v3" }
  }
}
```

**Required permission:** Platform `admin`.

### Delete Connection

```
DELETE /api/v1/vcs-connections/{id}
```

---

## Autodiscovery Rules

Connection-scoped rules that auto-create workspaces when a PR or default-branch push touches a path matching `pattern`. See [Autodiscovery](autodiscovery.md) for the full feature doc.

All endpoints require `admin` role.

### List Rules

```
GET /api/v1/autodiscovery-rules
```

### Create Rule

```
POST /api/v1/autodiscovery-rules
```

**Request body** (every attribute except `name`, `vcs-connection-id`, `repo-url`, `pattern` is optional):

```json
{
  "data": {
    "type": "autodiscovery-rules",
    "attributes": {
      "name": "monorepo",
      "vcs-connection-id": "vcs-019e0e7b-...",
      "repo-url": "https://github.com/myorg/monorepo",
      "branch": "main",
      "pattern": "accounts/*/**/*.tf",
      "ignore-patterns": ["modules/**"],
      "name-template": "ws-{path}",
      "enabled": true,
      "execution-mode": "agent",
      "execution-backend": "tofu",
      "agent-pool-id": "apool-019e01db-...",
      "engine-version": "1.13",
      "resource-cpu": "1",
      "resource-memory": "2Gi",
      "auto-apply": false,
      "on-directory-delete": "flag",
      "labels": {"managed-by": "monorepo-autodiscover"},
      "owner-email": "platform@example.com"
    }
  }
}
```

Returns `201` with the created rule, or `409` if a rule with that name already exists for the connection.

> **Reserved label keys:** `labels` is validated like any other label write — reserved keys (`status`, `owner`) are rejected with `422`. This is enforced at rule create/update so the rule can't materialise workspaces that later become uneditable.

### Show Rule

```
GET /api/v1/autodiscovery-rules/{id}
```

### Update Rule

```
PATCH /api/v1/autodiscovery-rules/{id}
```

Same body shape as create; only the attributes you include are updated.

### Delete Rule

```
DELETE /api/v1/autodiscovery-rules/{id}
```

Workspaces auto-created by this rule keep working — their `autodiscovery-rule-id` foreign key is set to NULL.

### Preview (dry-run)

Walk the repo and return exactly which workspaces a rule *would* create against the current state of the tracked branch, with no side effects. Used by the admin UI's "Preview" modal.

```
GET  /api/v1/autodiscovery-rules/{id}/preview      # preview a saved rule
POST /api/v1/autodiscovery-rules/preview           # preview an unsaved rule (same attributes body as Create)
```

Each entry reports `workspace_name`, `working_directory`, `collision` (the row would no-op — a workspace is already bound to that directory or the derived name is taken), and `existing_autodiscovered` (the no-op is a reuse of a workspace this same rule already materialised). Returns `413` if the VCS provider truncated the repo tree (repo too large to scan in one pass).

### Scan (on-demand materialise)

```
POST /api/v1/autodiscovery-rules/{id}/scan
```

Runs the same walk as Preview but actually creates the workspaces (idempotent, collision-safe). Force-enables the rule for the duration of the call so an explicit operator action doesn't silently no-op on a disabled rule. New workspaces are seeded with the tracked-branch HEAD as their last-seen commit, so the first real plan+apply fires when the branch next advances (e.g. the PR merge) — not immediately against a branch where the directory doesn't exist yet.

### Rule templating (run tasks / notifications / var files)

These are editable in the UI under **Admin → Autodiscovery**, alongside the rule's other workspace-template fields.

`POST`/`PATCH` rule bodies accept further attributes that are **materialised onto every workspace the rule creates**, so autodiscovered workspaces are fully configured at creation:

- `var-files` — list of var-file paths.
- `run-task-templates` — list of run-task specs (same shape as the bulk-update `run-tasks`, below): `{name, url, hmac-key?, stage, enforcement-level?, enabled?}`.
- `notification-templates` — list of notification specs: `{name, destination-type, url?, token?, triggers?, email-addresses?, enabled?}`.
- `execution-hook-templates` — list of [execution hook](execution-hooks.md) ids (`hook-<uuid>`) associated with every created workspace (#672).

- `security-scan-enforcement` / `security-scan-engine` / `security-scan-severity-threshold` / `security-scan-skip-rules` — [security scanning](security-scanning.md) for every created workspace (#1763). Unlike on a workspace, `enforced` is always accepted here: a rule has no engine, so everything it creates is a Terraform/OpenTofu workspace, which is exactly what can be scanned.
- `ai-summary-mode` / `ai-summary-context` — the AI plan-summary opt-in and its free-text context for every created workspace (#1763).
- `ai-policy-mode` — the AI **policy gate** per-workspace override for every created workspace. `disabled` opts out of an advisory verdict only, and a mandatory deployment-wide gate ignores it; `enabled` is a synonym for `default` and has no effect (#1766).
- `terragrunt-enabled` / `terragrunt-version`, `vcs-workflow`, `auto-merge` / `auto-merge-strategy`, `drift-detection-enabled` / `drift-detection-interval-seconds`, `drift-ignore-rules`, `plan-expiry-seconds` and `slack-channel` — the remaining per-workspace settings (#1763). `drift-detection-enabled` defaults **true** here, unlike the workspace column, because every autodiscovered workspace is VCS-connected.
- `debug-mode` — hold failed runner pods open for every created workspace (#1764). Defaults **false**, as on a workspace: a rule can materialise hundreds of workspaces, and this one is worth turning on deliberately.
- `allow-fork-pr-plans` — let a pull request opened from a fork plan on every created workspace. Defaults **false**, matching the workspace column rather than overriding it the way `drift-detection-enabled` does: an operator who decides fork pull requests should plan has to say so, and a rule is how they say it once for every directory the repository grows later. Without it, enabling the setting in bulk holds only until autodiscovery creates the next workspace — which reads as the setting not working. See [vcs-integration.md → Pull requests from forks](vcs-integration.md#pull-requests-from-forks).

These use the **identical spec shape** as the bulk-update endpoint, so a run task defined once can be applied to existing workspaces (bulk-update) *and* auto-applied to future ones (this template). The same pairing holds for the scan and AI-summary settings, and their values are validated by the same rules the workspace endpoint uses — so a rule cannot template a setting the workspace API would reject.

---

## Module Autodiscovery Rules

Rules that find the modules (the root and any submodules) in one repository, or in every repository of an org, group or repository-name pattern, and register them in the private registry. See [Module autodiscovery](registry.md#module-autodiscovery) for how a rule behaves over time.

All endpoints require the platform `admin` role. Rule ids are `modrule-<uuid>`, and a raw UUID is accepted too. `vcs-connection-id` accepts `vcs-<uuid>` or a raw UUID.

### List Rules

```
GET /api/v1/module-autodiscovery-rules
```

Newest first, with the standard `meta.pagination` block.

### Create Rule

```
POST /api/v1/module-autodiscovery-rules
```

**Request body** (only `name`, `vcs-connection-id`, `repo-url` and `pattern` are required):

```json
{
  "data": {
    "type": "module-autodiscovery-rules",
    "attributes": {
      "name": "management-groups",
      "vcs-connection-id": "vcs-019e0e7b-...",
      "repo-url": "https://github.com/myorg/terraform-azurerm-management-groups",
      "branch": "main",
      "pattern": "**/*.tf",
      "ignore-patterns": ["modules/legacy/**"],
      "name-template": "mg-{leaf}",
      "provider": "azurerm",
      "vcs-tag-pattern": "v*",
      "enabled": true,
      "labels": {"team": "platform"},
      "owner-email": "platform@example.com"
    }
  }
}
```

| Attribute | Notes |
|---|---|
| `name` | Unique per VCS connection. |
| `vcs-connection-id` | The connection whose credentials read the repository. |
| `repo-url` | What to scan: one repository (`https://github.com/myorg/terraform-aws-vpc`), an org or group (`https://github.com/myorg`), or a pattern over one org or group's repositories (`https://github.com/myorg/terraform-*`, glob characters in the last segment only). Classified when saved and reported as `target-kind`; see [What a rule looks at](registry.md#module-autodiscovery). |
| `branch` | Empty means each repository's default branch. |
| `pattern`, `ignore-patterns` | Gitignore-style globs over `.tf` / `.tf.json` file paths. Each matching file's directory is a module. A pattern ending in `/` is refused, because it can only match a directory. |
| `name-template` | Literal text plus the placeholders `{repo}`, `{path}`, `{leaf}`, `{root}` and `{owner}` (the repository's owner or group). Empty means the repository's module name plus the submodule's last segment. |
| `provider` | Lowercase letters, digits and hyphens. Empty means taken from a `terraform-<provider>-<name>` repository name. |
| `vcs-tag-pattern` | Copied onto each registered module. Empty means `v*`. |
| `enabled` | A boolean; default `true`. While enabled, directories that appear on the tracked branch are registered automatically. |
| `labels`, `owner-email` | Copied onto each registered module. `owner-email` must be an email address, or empty. |

Saving registers nothing: use [Scan](#scan-register-modules) to register what's already in the repository.

Returns `201` with the created rule. `409` means a rule with that name already exists for the connection.

`422` covers:
- a missing required attribute;
- a connection id that isn't a UUID, or that doesn't exist;
- a `repo-url` that names nothing on the connection: a repository or group that doesn't exist, a host other than the connection's, another GitHub account than the one the App is installed on, three or more path segments on GitHub, or glob characters outside the last segment;
- a pattern or ignore pattern ending in `/`;
- `ignore-patterns` that isn't a list of strings;
- a `name-template` with any other placeholder, a format spec, or any other brace;
- an invalid `provider`;
- `enabled` that isn't a boolean (the string `"false"` included);
- an `owner-email` that isn't an email address;
- a reserved label key.

`502` means the VCS provider could not be asked while classifying `repo-url`; retry. A pattern that matches no repository yet is accepted.

**Rule attributes** in responses:
- `name`
- `vcs-connection-id`, as `vcs-<uuid>`
- `repo-url` (as entered), `branch`, `pattern`, `ignore-patterns`, `enabled`
- `target-kind`: read-only; `repository`, `namespace` (an org or group) or `pattern`. Fixed when the rule is saved; it changes only when `repo-url` or `vcs-connection-id` does.
- `name-template`, `provider`, `vcs-tag-pattern`, `labels`
- `owner-email`: `""` when none
- `first-scan-at`: `null` until the rule's first poll or scan (for an org-wide rule, its baseline)
- `last-scanned-sha`: the tracked branch's head at the last scan; `""` for an org-wide rule, whose heads are per repository
- `last-enumerated-at`: when an org-wide rule last completed a listing of its repositories, or `null`
- `last-error`: why the rule's last poll could not do all its work (its target was deleted, the listing failed or stopped at the repository cap, or the API quota ran low), or `""`
- `created-at`, `updated-at`

Each rule also has a `vcs-connection` relationship and a `links.self`.

### Show Rule

```
GET /api/v1/module-autodiscovery-rules/{id}
```

### Update Rule

```
PATCH /api/v1/module-autodiscovery-rules/{id}
```

Same body shape as create; only the attributes you include change, validated the same way. A changed `repo-url` or `vcs-connection-id` is classified again, as on create; so is re-saving the same `repo-url` of a rule with a `last-error`. Changing `repo-url`, `vcs-connection-id`, `branch`, `pattern` or `ignore-patterns`, or setting `enabled` to `true` on a disabled rule, starts the rule afresh: what it had seen no longer describes what it claims, so its per-repository state is cleared and the next poll records a new baseline rather than registering every directory the old rule never claimed. Register those with a [scan](#scan-register-modules).

### Delete Rule

```
DELETE /api/v1/module-autodiscovery-rules/{id}
```

Returns `204`. The modules the rule registered stay registered.

### Preview (dry-run)

```
GET  /api/v1/module-autodiscovery-rules/{id}/preview   # a saved rule
POST /api/v1/module-autodiscovery-rules/preview        # an unsaved rule (same body as Create)
```

Registers nothing. A single-repository rule reads its repository live. An org-wide saved rule is served from what the last poll found, with no VCS calls, a page of repositories at a time (`page[size]`, `page[number]`, with `meta.pagination`); `?repository=<path-or-url>` reads that one repository live instead (`404` when it isn't one of the rule's repositories; `422` on a single-repository rule when it names another repository). An unsaved org-wide rule reads one page of repositories live (`page[size]` at most 25, default 10); a repository that cannot be read is reported in `repositories`, not as a failed preview.

Returns a `module-autodiscovery-rule-previews` document with:
- `ref`: the branch it read; `""` for a stored org-wide preview;
- `files-walked`;
- `target-kind`: as on the rule;
- `entries[]`: one per candidate directory, root first, grouped by repository;
- `repositories[]`: one per repository on this page, including ones with no candidates, each with `repository` (the path), `repo-url`, `ref`, `status` (`active`, `archived`, `empty`, `no-branch`, `out-of-scope`, `covered` or `error`), `origin` (`baseline` or `new`) and `error`;
- `listing-complete`: `false` when an org-wide listing stopped at the repository cap, so some repositories are not shown.

Each entry has:
- `repository` and `repo-url`: the repository the directory is in;
- `subdirectory`: `""` for the root;
- `name` and `provider`: as a scan would register them;
- `registered-as`: the `{name, provider}` of the module already registered from that directory, or `null`;
- `collision`: `true` when the name and provider belong to another module, or when another unregistered candidate derives the same name;
- `missing-provider`: `true` when no provider could be worked out.

Errors:
- `422`: a repository URL that can't be parsed, or an unknown VCS provider.
- `502`: the VCS provider can't be reached, returned no default branch, or refused to list the tree (a missing branch, a revoked token); the detail carries the provider's error.
- `413`: the provider truncated the repository's tree, so it's too large to scan in one pass.

### Scan (register modules)

```
POST /api/v1/module-autodiscovery-rules/{id}/scan
```

With no body, registers every candidate. To register a chosen subset of a single-repository rule, send:

```json
{"data": {"attributes": {"subdirectories": ["", "modules/create"]}}}
```

An org-wide rule registers from what the last poll found, with no VCS calls, and takes `selections` instead: the repositories to register from (a path or URL), each with optional `subdirectories` (omitted means all of that repository's candidates). At most 200 repositories per request. A single-repository rule accepts `selections` naming its one repository too.

```json
{"data": {"attributes": {"selections": [
  {"repository": "myorg/terraform-aws-vpc"},
  {"repository": "myorg/terraform-aws-dns", "subdirectories": ["modules/zone"]}
]}}}
```

With no body, an org-wide rule registers every current candidate of every repository, which in a large org can be many modules.

Registered modules are VCS-sourced, carry their `subdirectory`, and take the rule's branch, tag pattern, labels and owner. Their tags are polled on the next registry poll. A scan works whether or not the rule is enabled. Everything it saw counts as seen, so automatic registration will never later pick up a candidate you left out.

Returns a `module-autodiscovery-rule-scans` document with:
- `ref` and `files-walked` (`""` and `0` for an org-wide rule);
- `modules-registered`: the count;
- `modules[]`: each with `id`, `name`, `provider`, `subdirectory`, `repository` and `repo-url`;
- `skipped[]`: each with `subdirectory` and a `reason` (`already-registered`, `name-taken` or `missing-provider`), plus `repository` and `repo-url` for an org-wide rule;
- `repositories-scanned`: how many repositories it registered from.

Returns `422` when a listed subdirectory isn't one of the rule's candidates, `subdirectories` or `selections` is malformed, a selection names a repository that isn't the rule's or has no candidates to register, or `subdirectories` is sent to an org-wide rule. Everything is checked before anything is registered. The repository errors are the same as for Preview.

### Rule Repositories

```
GET /api/terrapod/v1/module-autodiscovery-rules/{id}/repositories
```

The repositories the rule looks at, by path, each with the state its polls keep: one for a single-repository rule once it has been polled, one per listed repository for an org-wide rule. Read-only, and separate from the rule so the rule stays small. `filter[status]=<status>` narrows by status. Paginated in the database (`page[size]` up to 100, `page[number]`, `meta.pagination`); with no `page[size]` the whole list is returned.

Each `module-autodiscovery-rule-repositories` item (`id` `modrepo-<uuid>`, with a `rule` relationship) has:
- `repository`: the path (`owner/repo`, or `group/subgroup/project`), and `repo-url`;
- `vcs-repo-id` and `default-branch`;
- `origin`: `baseline` (it existed at the rule's baseline, so nothing registers until it is scanned) or `new` (created afterwards, so its modules register automatically);
- `status`: `active`, `archived` (kept, not scanned), `empty`, `no-branch`, `out-of-scope` (left the rule's target; its modules stay), `covered` (a single-repository rule on the connection names it) or `error`;
- `last-scanned-sha`, `seen-subdirectories`;
- `candidates[]`: `{subdirectory, name, provider}` as the last poll found them;
- `last-skips[]`: `{subdirectory, reason}` from the last registration;
- `previous-paths[]`: `{path, url}` before a rename or transfer, oldest first;
- `repo-created-at`, `first-seen-at`, `last-checked-at`, `next-check-at`: RFC3339 or `null`;
- `failure-count` and `last-error`: consecutive failed reads (they back off) and the last reason.

---

## Bulk Workspace Operations

Terrapod-native, **admin only**. Server-side selection + atomic fleet updates (#318).

### Search

```
POST /api/v1/workspaces/actions/search
```

Resolve a structured filter to the matching workspaces — no side effects (the discovery half of the bulk workflow).

```json
{ "filter": {
    "labels": {"team": "foundations"},
    "name-prefix": "terrapod-testing-",
    "execution-backend": "terraform",
    "agent-pool-id": "apool-...", "vcs-connection-id": "vcs-...",
    "owner-email": "...", "drift-status": "...", "locked": false, "has-vcs": true,
    "workspace-ids": ["ws-..."],
    "all": false } }
```

Dimensions are **AND-combined** (narrower = safer). An empty/omitted `filter` is a `422` (typo guard); matching the whole fleet requires explicit `"all": true`. Returns `{matched, workspaces:[...]}`.

### Bulk Update

```
POST /api/v1/workspaces/actions/bulk-update
```

Apply `update` to every workspace matching `filter`, in a **single all-or-nothing transaction**.

```json
{ "filter": { "labels": {"team": "foundations"} },
  "update": {
    "engine-version": "1.13",
    "execution-backend": "tofu",
    "auto-apply": false,
    "agent-pool-id": "apool-...",
    "resource-cpu": "1", "resource-memory": "2Gi",
    "var-files": ["envs/prod.tfvars"],
    "labels": {"reviewed": "2026-q2"},
    "security-scan-enforcement": "enforced",
    "security-scan-engine": "checkov",
    "security-scan-severity-threshold": "high",
    "security-scan-skip-rules": ["CKV_AWS_24"],
    "ai-summary-mode": "enabled",
    "ai-summary-context": "payments estate; PCI in scope",
    "ai-policy-mode": "disabled",
    "oidc-audiences": {"aws": ["sts.amazonaws.com"]},
    "debug-mode": true,
    "terragrunt-enabled": true, "terragrunt-version": "0.67.4",
    "trigger-prefixes": ["infra/net"],
    "vcs-workflow": "merge_then_apply",
    "auto-merge": true, "auto-merge-strategy": "squash",
    "plan-expiry-seconds": 3600,
    "drift-detection-enabled": true, "drift-detection-interval-seconds": 86400,
    "drift-ignore-rules": ["aws_instance.web.tags[\"LastSeen\"]"],
    "slack-channel": "#platform",
    "pulumi-bind-plan": false,
    "run-tasks": [
      { "name": "opa-policy-check", "url": "http://opa:8080/webhook",
        "hmac-key": "secret", "stage": "post_plan", "enforcement-level": "mandatory" }
    ],
    "notification-configurations": [
      { "name": "slack-prod", "destination-type": "slack",
        "url": "https://hooks.slack.com/...", "triggers": ["run:errored"] }
    ]
  },
  "dry_run": true }
```

Semantics:

- **Validated once up front** — field enums, `labels` reserved-key check, run-task/notification specs, and agent-pool existence + caller pool-`write` RBAC on **every** pool named. Any error ⇒ `422`, **zero mutation**.
- **Agent pools** accept either `agent-pool-id` (one pool, replacing the set) or `agent-pool-ids` (the set) — the same mutually-exclusive pair as the workspace endpoints; both in one `update` ⇒ `422`.
- **`security-scan-enforcement` is checked against the matched set**, not just the payload. Checkov and Trivy read Terraform plan JSON, so a Pulumi workspace has nothing to scan and accepts only `off`. Setting `advisory` or `enforced` across a match set containing one ⇒ `422` naming the offenders, with **zero mutation** — a mixed-engine match set is the normal case, and the alternative is every apply on those workspaces held waiting for a scan result that cannot arrive. Narrow the filter to exclude them.
- **Every settable per-workspace setting is reachable here** (#1763). A source-introspection gate requires each `Workspace` column to be wired up, permanently exempt with a reason, or a recorded gap — so a new setting cannot be silently missing.
- **All settings use the same rules as the single-workspace `PATCH`** (enum values, the 200-entry skip-rule cap, the 4000-character context cap, the drift-rule character set), so bulk update never accepts a value the workspace endpoint rejects. Booleans are type-checked, never coerced: `"false"` is refused rather than read as `true`.
- **Two more settings are checked against the matched set**, for the same reason as `security-scan-enforcement`:
  - `vcs-workflow: apply_then_merge` needs a VCS connection and auto-apply off on **every** matched workspace — the apply runs before the PR merges, so auto-applying would apply from a branch nobody approved. Turning auto-apply off in the same request is allowed, mirroring the `PATCH` path.
  - `pulumi-bind-plan` applies only to Pulumi workspaces; setting it across a match set containing another engine ⇒ `422`, rather than recording a setting that does nothing.
- `run-tasks` / `notification-configurations` **upsert by `(workspace, name)`**: created if absent, updated in place if present (so re-running with a changed `url` rotates it across the fleet).
- **All-or-nothing**: the whole batch commits or nothing does. `dry_run` (default `true`, not enforced) runs the identical code path and rolls back — the preview is exactly what apply would do, with provably zero side effects.
- **Triggers no runs** — pure config write; the change lands on each workspace's next normal run. Reversible (it only writes settings rows). **One qualification, for `oidc-audiences` only:** writing it triggers nothing, but a run already sitting in `planned` on a matched workspace is auto-**discarded** the next time anyone tries to confirm it, by the cloud-identity staleness guard above — the identity it would present is no longer the one its plan was reviewed under. So a fleet-wide audience edit can invalidate every pending apply across the matched set at once. That is the guard working as designed (it fails before the apply rather than at the cloud's token exchange mid-apply), but it is a side effect of a "pure settings write", so plan the edit for a quiet moment and expect to re-plan. Nothing is applied, and no run is queued.
- Per-workspace audit entries.

Response: dry-run `{dry_run:true, matched, would_change:[{id,name,diff}], unchanged}`; apply `{dry_run:false, matched, applied, changes, unchanged, errors:[]}`; any failure ⇒ `409`/`422` and **nothing applied**.

---

## VCS Events (Webhooks)

### GitHub Webhook Receiver

```
POST /api/v1/vcs-events/github
```

Validates HMAC-SHA256 signature and triggers an immediate poll cycle. The webhook secret must match the connection's own `webhook-secret`, falling back to the global `TERRAPOD_VCS__GITHUB__WEBHOOK_SECRET`.

### GitLab Webhook Receiver

```
POST /api/v1/vcs-events/gitlab
```

Validates the `X-Gitlab-Token` header (timing-safe comparison against the connection's `webhook-secret`) and triggers an immediate poll cycle. Handles `Push Hook`, `Tag Push Hook`, and `Merge Request Hook` events; other event types are acknowledged and ignored. A `Tag Push Hook` additionally triggers an immediate **module tag** poll, so a new module version publishes within seconds rather than waiting for `vcs.module_poll_interval_seconds`. Like GitHub, webhooks are an **optional accelerator** — the background poller still picks up changes within `vcs.poll_interval_seconds` if no webhook is configured.

---

## Roles

### List Roles

```
GET /api/v1/roles
```

Returns built-in and custom roles.

**Required permission:** Platform `admin` or `audit`.

### Create Role

```
POST /api/v1/roles
```

**Request body (capability authoring — recommended):**
```json
{
  "data": {
    "type": "roles",
    "attributes": {
      "name": "developer",
      "description": "Development workspace access",
      "capabilities": ["workspace:read", "run:read", "run:plan", "var:read"],
      "allow-labels": {"env": "dev"},
      "allow-names": [],
      "deny-labels": {},
      "deny-names": []
    }
  }
}
```

A role's grant is its **`capabilities`** set — a list of `resource:verb` tokens (e.g. `run:plan`, `run:apply`, `run:apply-destroy`, `workspace:delete`, `var:write`, `state:read`) and **the single stored source of truth for enforcement** (#585). Capabilities express grants the old hierarchical levels could not — for example `run:plan` *without* `run:apply` ("plan but not apply"). Only tokens in the grantable set are accepted; `platform:*` and unknown tokens are rejected with `422`.

**Request body (level shorthand — convenience):** you may instead send the four permission-level fields and the server **expands them into capabilities** on write:
```json
{
  "data": {
    "type": "roles",
    "attributes": {
      "name": "developer",
      "workspace-permission": "write",
      "pool-permission": "read",
      "registry-permission": "read",
      "catalog-permission": "use",
      "allow-labels": {"env": "dev"}
    }
  }
}
```
- `workspace-permission` (`read`/`plan`/`write`/`admin`), `pool-permission` (`read`/`write`/`admin`), `registry-permission` (`read`/`write`/`admin`, modules + providers) default to `read`; `catalog-permission` (`none`/`read`/`use`/`admin`) defaults to `none` (opt-in, no `everyone` floor).
- The levels are **not persisted**. On a create/update they are expanded into `capabilities`; on a **PATCH**, a level field replaces only that axis's capabilities, preserving granular capabilities on the other axes.
- If both `capabilities` and level fields are sent, **`capabilities` wins** (the levels are ignored).

**Response:** every roles response includes the stored `capabilities` list **and** a derived, read-only permission-level summary (`workspace-permission`, `pool-permission`, `registry-permission`, `catalog-permission`) computed from the capabilities — each is the matching preset name, or the literal `"custom"` when the capability set matches no preset. Consumers that write levels must tolerate reading back `"custom"`.

**Required permission:** Platform `admin`.

### Show Role

```
GET /api/v1/roles/{name}
```

### Update Role

```
PATCH /api/v1/roles/{name}
```

### Delete Role

```
DELETE /api/v1/roles/{name}
```

Built-in roles cannot be deleted.

### Role attribute: `allow-all`

`allow-all: true` makes the role's allow side match **every resource on every
axis**, including ones created later. Deny rules still take precedence, and it
does not raise the role's permission level. It exists because label and name
rules are exact-match (no wildcards), so the alternative was a shared label on
every workspace — where a workspace created without it silently falls outside
the role. Defaults to `false`; every pre-existing role keeps exactly the reach
it had.

### Resource Access (who can reach this)

```
GET /api/v1/workspaces/{id}/access
GET /api/v1/agent-pools/{id}/access
GET /api/v1/registry-modules/{id}/access
GET /api/v1/registry-providers/{id}/access
GET /api/v1/catalog-items/{id}/access
```

The inverse of the role preview. `admin` or `audit`; read-only and unpaged
(roles are few).

```json
{
  "data": {
    "type": "resource-access",
    "id": "ws-...",
    "attributes": {
      "resource": {"id": "ws-...", "kind": "workspaces", "name": "prod-api",
                   "labels": {"env": "prod"}, "owner-email": "team@example.com"},
      "axis": "workspace",
      "role-count": 1,
      "roles": [
        {"role": "sre", "verdict": "allowed", "reason": "allow-label:env=prod",
         "capabilities": ["run:apply", "..."], "notes": ["has-owner"],
         "held-by": ["alice@example.com"]}
      ],
      "denied-roles": [
        {"role": "contractors", "verdict": "denied", "reason": "deny-name",
         "capabilities": []}
      ],
      "platform-paths": ["platform-admin", "platform-audit", "owner"]
    }
  }
}
```

`platform-paths` names access that exists **independently of any role** —
`platform-admin`, `platform-audit`, `owner`, `everyone-floor`,
`catalog-clamped`. A caller that reports only `roles` will understate who can
reach the resource.

### Preview Role Reach

```
POST /api/v1/roles/preview
GET  /api/v1/roles/{name}/preview
```

Which workspaces a role grants on, and why. `admin` or `audit`; read-only.

`POST` previews an **unsaved** role body — the same attributes a create takes
(`allow-labels`, `allow-names`, `deny-labels`, `deny-names`, and either
`capabilities` or the level shorthand) — so the admin UI can show the match
while a rule is being typed. Nothing is persisted, and a body a create would
reject is rejected here too (`422`).

`GET` previews a saved role. A built-in role returns `422`: `admin` and `audit`
grant through the platform path on every workspace, so a label-reach figure for
them would be misleading rather than useful.

Paged with `page[size]` (default 25, max 100) and `page[number]`. **The counts
span the whole fleet, not the returned page.**

The response carries an `axes` block keyed `workspace` / `pool` / `registry` /
`catalog`: a role's rules are matched the same way whatever they are matched
against, so one rule reaches agent pools, registry modules and providers, and
catalog items as readily as workspaces. Capabilities in each block are sliced
to that axis. The workspace axis is also promoted to the top level as
`workspaces` / `denied`, since it is what most callers want.

```json
{
  "data": {
    "type": "role-previews",
    "id": "sre",
    "attributes": {
      "granted-count": 47,
      "denied-count": 3,
      "matched-count": 50,
      "denied-truncated": false,
      "workspaces": [
        {
          "id": "ws-...",
          "name": "prod-api",
          "labels": {"env": "prod"},
          "owner-email": "team@example.com",
          "verdict": "allowed",
          "reason": "allow-label:env=prod",
          "capabilities": ["run:apply", "run:plan", "..."],
          "notes": ["has-owner"]
        }
      ],
      "denied": [
        {
          "id": "ws-...",
          "name": "prod-locked",
          "verdict": "denied",
          "reason": "deny-label:sealed=yes",
          "capabilities": []
        }
      ]
    }
  }
}
```

`verdict` is `allowed` or `denied`; `reason` names the responsible rule.
`notes` name access paths independent of this role — `has-owner`,
`everyone-floor`, `catalog-clamped` — see
[`rbac.md` → Seeing What a Role Reaches](rbac.md#seeing-what-a-role-reaches).

---

## Role Assignments

### List Assignments

```
GET /api/v1/role-assignments
```

**Required permission:** Platform `admin` or `audit`.

### Set Roles for User

```
PUT /api/v1/role-assignments
```

**Request body:**
```json
{
  "data": {
    "type": "role-assignments",
    "attributes": {
      "provider-name": "local",
      "email": "alice@example.com",
      "roles": ["developer", "sre-reader"]
    }
  }
}
```

**Required permission:** Platform `admin`.

### Remove Single Assignment

```
DELETE /api/v1/role-assignments/{provider}/{email}/{role}
```

---

## Authentication Tokens

Authentication tokens come in three **kinds** (`kind` attribute):

| Kind | Who creates | Effective permissions | Bound to |
|---|---|---|---|
| `interactive` | anyone (default) | the owner's full live roles | the owner |
| `service_bound` | anyone | **intersection** of the token's `pinned-roles` and the owner's live roles, per resource | the owner — and the token is **rejected if the owner hasn't logged in within `auth.bound_token_idle_days`** (default 7) |
| `service_detached` | admins only | the token's `pinned-roles` as an **absolute** scope | nobody (unbound) — survives any single person leaving |

A `service_bound` token can never exceed its owner's access (the intersection caps it) and stops working when the owner is offboarded — see [authentication.md](authentication.md) and the offboarding runbook in [runbooks.md](runbooks.md). `service_detached` is the path for critical machine-to-machine automation.

**Response attributes**: `description`, `kind`, `bound-to` (null for detached), `created-by`, `pinned-roles` (service tokens only; null for interactive), `token-type`, `created-at`, `rotated-at`, `last-used-at`, `expires-at`, `lifespan-hours`, and `token` (the raw secret — present only in create/rotate responses). Service tokens always carry an expiry, capped by `auth.service_token_max_ttl_hours` (default 8760 / 1 year).

### Create Token

```
POST /api/v1/users/{user_id}/authentication-tokens
```

Request attributes: `description`, `kind` (default `interactive`), `lifespan_hours`, `pinned_roles` (service kinds). `service_detached` is admin-only (`403` otherwise) and is created unbound regardless of `{user_id}`.

### List Own Tokens

```
GET /api/v1/users/{user_id}/authentication-tokens
```

Never includes detached tokens (they are unbound).

### List All Tokens (admin)

```
GET /api/v1/admin/authentication-tokens[?kind={kind}]
```

Admin-only. Optional `kind` filter (`interactive` / `service_bound` / `service_detached`); a valid-but-empty kind returns `[]`, not an error.

### Show Token

```
GET /api/v1/authentication-tokens/{id}
```

### Re-tag Token (change kind)

```
PATCH /api/v1/authentication-tokens/{id}
```

`interactive` ↔ `service_bound` is owner-or-admin. Converting **to/from** `service_detached` is admin-only and unbinds/rebinds the token. Request attributes: `kind`, `pinned_roles`.

### Rotate Token

```
POST /api/v1/authentication-tokens/{id}/actions/rotate
```

Mints a fresh secret (returned once in `token`) and resets the expiry clock; the old secret stops working immediately. Surfaced as a "Rotate" action on service tokens in the UI.

### List Expiring Service Tokens

```
GET /api/v1/authentication-tokens/expiring
```

Service tokens within `auth.token_expiry_warning_days` (default 14) of expiry, **scoped to the caller**: own bound service tokens for everyone, plus all detached tokens for admins. Drives the in-app expiry banner — no user is warned about another user's bound tokens.

### Revoke All Tokens for a User (admin)

```
POST /api/v1/admin/authentication-tokens/actions/revoke-all
```

Admin-only urgent-offboarding lever. Body `{"email": "..."}`; revokes every token bound to that identity and returns `{"data": {"email": ..., "revoked": N}}`. Detached tokens are unbound and unaffected.

### Delete Token

```
DELETE /api/v1/authentication-tokens/{id}
```

---

## Run Artifacts (Runner)

Authenticated endpoints for runner Jobs to download inputs and upload outputs. All endpoints require a runner token (`Authorization: Bearer runtok:...`) scoped to the specified `run_id`.

Since 2.0 (GHSA-xmrf-hxq9-m59m) a token is also scoped to its **phase** and to
the time its run is **live**:

- An endpoint that belongs to one phase refuses a token from the other with
  **403**. Plan phase: `PUT plan-log`, `PUT plan-file`, `PUT lock-file`,
  `PUT plan-json-output`, `PUT plan-artifacts`, `PUT cost-estimate`, the
  `onboarding-*` uploads, `POST plan-result`, and the policy + security-scan
  runner protocol. Apply phase: `GET plan-file`, `GET lock-file`,
  `GET plan-artifacts`, `PUT apply-log`, `PUT state`, `PUT pulumi-deployment`,
  `POST state-diverged`, `POST apply-result`. Both: `GET config`, `GET state`,
  `GET pulumi-deployment`, `POST resource-profile`.
- A token whose run has reached a terminal state — or has been deleted — fails
  **authentication** (401), on every runner-reachable surface including the
  binary cache, the provider mirror, the package-cache proxy and the container
  registry.
- A token carrying no phase claim passes every phase, because that is what a
  listener older than the claim mints. See
  [Listener Runner Token](#listener-runner-token).

### Download Config Archive

```
GET /api/v1/runs/{run_id}/artifacts/config
```

Returns 302 redirect to presigned storage URL for the configuration tarball.

### Download State

```
GET /api/v1/runs/{run_id}/artifacts/state
```

Returns 302 redirect to presigned storage URL for the current workspace state.

### Download Plan File

```
GET /api/v1/runs/{run_id}/artifacts/plan-file
```

Returns 302 redirect to presigned storage URL for the plan binary file.

### Upload Plan Log

```
PUT /api/v1/runs/{run_id}/artifacts/plan-log
Content-Type: application/octet-stream
```

Upload raw plan log bytes. Returns 204 on success.

### Upload Plan File

```
PUT /api/v1/runs/{run_id}/artifacts/plan-file
Content-Type: application/octet-stream
```

Upload plan binary file. Returns 204 on success.

### Upload Apply Log

```
PUT /api/v1/runs/{run_id}/artifacts/apply-log
Content-Type: application/octet-stream
```

Upload raw apply log bytes. Returns 204 on success.

### Upload State

```
PUT /api/v1/runs/{run_id}/artifacts/state
Content-Type: application/octet-stream
```

Upload new state after apply. Returns 204 on success.

### Download a Pulumi Deployment

```
GET /api/v1/runs/{run_id}/artifacts/pulumi-deployment
```

Pulumi workspaces only (#1576). Returns 200 with `{"version": 3, "deployment": ...}`, the body `pulumi stack import` reads: the stack's current deployment with its secrets in plaintext and no `secrets_providers` block. `deployment` is `null` for a stack with no state. The `X-Terrapod-State-Serial` header carries the serial of the state version it was read from, or `0`. Returns 409 when the stored secrets are sealed by a provider Terrapod holds no key for, and 404 for a workspace that is not Pulumi.

### Upload a Pulumi Deployment

```
PUT /api/v1/runs/{run_id}/artifacts/pulumi-deployment?base-serial={serial}
Content-Type: application/json
```

Pulumi workspaces only (#1576). The body is `pulumi stack export --show-secrets` output. Terrapod seals the secrets with its own key and stores the result as the next state version, linked to the run. `base-serial` is the serial the download reported; if the stack has moved on since, the upload is refused with 409. A retry of an upload that already landed returns 200. Also returns 400 for a body with sealed secrets or no `deployment`, and 409 for a plan-only run. Returns 204 on success.

### Download Plan Artifacts

```
GET /api/v1/runs/{run_id}/artifacts/plan-artifacts
```

Returns 302 redirect to presigned storage URL for the plan-phase workspace-diff tarball. Used by the apply phase to restore files generated during plan (e.g. `data.archive_file` outputs, `null_resource` local-exec scratch) into the apply Job's fresh workspace. Returns 404 if the run was produced by a pre-v0.34.0 runner (no plan-artifacts uploaded). The apply phase tolerates 404 — it logs an error and proceeds.

### Upload Plan Artifacts

```
PUT /api/v1/runs/{run_id}/artifacts/plan-artifacts
Content-Type: application/x-tar
Content-Length: <bytes>
```

Upload the plan-phase workspace-diff tarball. The body is the diff (`post_plan - post_init`) of files plan created, excluding `tfplan`, `.terraform.lock.hcl`, and `.terraform/terraform.tfstate` (handled by other endpoints). An empty tar is always uploaded — even when plan generated no new files — so the apply-side contract is "404 means upload genuinely failed", not "no new files".

The body is streamed to an ephemeral tempfile on the API pod's PVC and forwarded to object storage; nothing is fully buffered in RAM. Maximum tarball size is `runners.planArtifactsMaxBytes` (default 256 MiB; minimum 10240 bytes). Both the `Content-Length` header and the streamed length are enforced — oversize uploads receive HTTP 413.

Returns 204 on success.

### Record Resource Profile

```
POST /api/v1/runs/{run_id}/resource-profile
Content-Type: application/json
```

Called by the runner entrypoint at exit (EXIT trap, fires on every catchable termination — clean success, plan errored, OPA failed, SIGTERM during apply). Captures cgroup-v2 peak memory + cumulative CPU + the runner script's exit code.

Body (all fields optional — the runner sends whatever it could read):

```json
{
  "peak_memory_bytes": 1500000000,
  "peak_cpu_usec": 42000000,
  "exit_code": 1,
  "failure_reason": "Error: Unsupported argument (on main.tf line 3)"
}
```

- `peak_memory_bytes` — from `/sys/fs/cgroup/memory.peak`
- `peak_cpu_usec` — `usage_usec` from `/sys/fs/cgroup/cpu.stat`
- `exit_code` — script's actual exit status
- `failure_reason` — sent only with a non-zero `exit_code`: why the run failed, in a line or two. For a failed `init`, `plan` or `apply` it is tofu's own `Error:` summaries (at most three, each with its `on <file> line <n>` location, never a diagnostic's detail lines); for any other failure it is the runner's last logged error (a failed hook, an unusable configuration archive, a crash). The API strips ANSI and other control characters, caps it at 2,000 characters, and stores it as the run's `error-message`, which the reconciler then keeps, followed by `Runner exited with code N` (#1631). Ignored with a zero `exit_code`, and on a run that has already errored.

Negative values, non-integers, or booleans return `400`, as does a non-string `failure_reason`. Missing fields are not clobbered (existing values preserved).

Note: **SIGKILL is uncatchable**, so this endpoint never fires on OOM-killed runs. Those are covered by the listener's K8s-terminated-state report on the job-status path; `runner-exit-status` ends up `"oom"` either way. See [Run Response Attributes (Resource Profile / OOM)](#run-response-attributes-resource-profile--oom) for the full signal flow.

Returns 204 on success.

---

## Binary Cache

### Download Binary

```
GET /api/v1/binary-cache/{tool}/{version}/{os}/{arch}
```

Returns a 302 redirect to a presigned URL for the binary. `tool` is `terraform` or `tofu`.

**Required:** Authentication (runner token, API token, or session).

### List Cached Binaries (Admin)

```
GET /api/v1/admin/binary-cache
```

### Warm Cache (Admin)

```
POST /api/v1/admin/binary-cache/warm
```

Pre-cache a specific tool version.

### Bulk Warm Cache (Admin)

```
POST /api/v1/admin/binary-cache/warm-bulk
```

Pre-cache many binaries and/or provider platforms in one call. Request body:

```json
{
  "binaries": [
    { "tool": "tofu", "version": "1.9.0", "platforms": [{ "os": "linux", "arch": "amd64" }] }
  ],
  "providers": [
    { "source": "registry.terraform.io/hashicorp/aws", "version": "5.60.0" }
  ]
}
```

`platforms` is optional — omitted, a binary falls back to linux/amd64 + linux/arm64 and a provider falls back to the configured `provider_cache.platforms`. Provider `source` is the `hostname/namespace/type` address. Resilient: each (entry, platform) is warmed independently and reported back, so one missing version doesn't fail the batch. Returns HTTP 200 with per-target results even when some failed:

```json
{ "total": 2, "succeeded": 1, "failed": 1, "results": [
  { "kind": "binary", "ref": "tofu 1.9.0 linux/amd64", "ok": true },
  { "kind": "provider", "ref": "registry.terraform.io/hashicorp/aws 5.60.0 linux/amd64", "ok": false, "error": "..." }
]}
```

See [Cache pre-population](registry.md#cache-pre-population).

### Purge Cache (Admin)

```
DELETE /api/v1/admin/binary-cache/{tool}/{version}
```

---

## Encryption at Rest (Admin)

Optional application-layer BYOK envelope encryption — off by default. See
[Encryption at Rest](encryption-at-rest.md) for the full operator guide. Both
endpoints require platform `admin`.

### Status

```
GET /api/v1/admin/encryption
```

Reports encryption-at-rest health. `decryptable` is the headline durability
signal — `false` means the platform is running but cannot read its encrypted data
back (page on it). Always returns 200 (even when encryption is disabled).

**Response attributes** (`data.type` = `encryption-status`):

| Attribute | Type | Meaning |
|---|---|---|
| `enabled` | bool | Whether new writes are encrypted |
| `provider` | string | KEK provider in use (`static` / `vault_transit` / `awskms` / empty when off) |
| `active_version` | int \| null | DEK version new writes use |
| `dek_versions` | array<int> | All DEK versions loaded (older ones decrypt existing data) |
| `canary_ok` | bool | The boot decryptability canary verified |
| `decryptable` | bool | Can currently decrypt — the alarm signal |

### Rotate DEK

```
POST /api/v1/admin/encryption/rotate-dek
```

Mints a new active data-encryption key. Prior DEK versions are **retained** so
existing ciphertext stays decryptable; run `encryption_migrate encrypt` afterwards
to re-key old rows. The new key is wrapped **and** unwrapped (round-trip verified)
before activation — a broken provider aborts with nothing changed. Returns the
same status shape as above. **409** when encryption is disabled.

> Rotation propagates to all API replicas within ~30s via the
> `encryption_key_refresh` background task (no restart needed); see the
> [rotation notes](encryption-at-rest.md#key-rotation).

---

## Per-Workspace Cloud Identity (OIDC Federation)

Terrapod can publish an OIDC discovery document and JWKS so a cloud federates to
it as an identity provider, and mint a short-lived RS256 JWT per run describing
the workspace and phase. Off by default
(`api.config.auth.oidc_issuer.enabled`); when off, the two `/.well-known`
routes below are **not mounted at all** rather than mounted and refusing.

Configuration is two levels, merged per key: the deployment's catalogue in
`api.config.auth.oidc_issuer.audiences`, and a workspace's own
[`oidc-audiences`](#cloud-identity-attributes) override over it. A workspace
mints nothing when the **resolved** map is empty, and its runs then authenticate
with the agent pool's own identity exactly as before.

**One token is minted per provider configuration**, each carrying only that
target's audiences, and the runner writes each to its own path
(`/var/run/terrapod/oidc/<target>/token`). A token audienced for several targets
is replayable between them, and AWS refuses a multi-valued `aud` outright — at
the cloud's token exchange, not at configuration time.

See [cloud-identity.md](cloud-identity.md) for the per-provider configuration,
which is the operator's own: Terrapod mints a token and writes it to a file, and
holds nothing cloud-specific.

### Discovery Document

```
GET /.well-known/openid-configuration
```

**Unauthenticated**, by necessity: a cloud fetches this anonymously, before any
token exists, to decide whether to trust one. Publishes only the issuer's own URL
and the claim names. Deliberately minimal — there is no authorization endpoint,
no token endpoint and no client registration, because the only consumer is a
target validating a token Terrapod already minted.

`issuer` is resolved from `api.config.auth.oidc_issuer.public_url`, falling back
to the public webhook URL and then `external_url`. OIDC issuer matching is
**exact**, so this value must equal what the cloud is configured with, trailing
slash included.

**Cacheable**: `Cache-Control: public, max-age=300`. Modest, because the document
carries no key material but a corrected issuer URL should take effect in minutes.

### JWKS

```
GET /.well-known/jwks.json
```

**Unauthenticated**, same reason. Public key material only. Returns a key *set*,
not one key: a rotation publishes the incoming key before it starts signing and
keeps the retired one until the tokens it signed expire. A cloud selects by the
token's `kid`, which is an RFC 7638 thumbprint of the key itself.

**Cacheable, and the lifetime is derived rather than configured**:
`Cache-Control: public, max-age=<key_propagation_seconds / 2>`, with a floor of
60 seconds. The propagation window exists *because* the clouds cache this
document, so advertising a longer lifetime would mean a cloud still holding the
old key set at the moment we begin signing with the new one; half rather than all
of it avoids a clock-skew race at the boundary.

Both issuer documents also have **their own rate-limit bucket**, at
`authenticated_requests_per_minute` rather than the anonymous per-IP limit. A
`429` on the JWKS would fail token verification for every federated run at once,
including runs whose own traffic had nothing to do with filling the bucket.

### Mint Run Identity Tokens

```
POST /api/terrapod/v1/runs/{run_id}/cloud-identity-tokens
```

**Runner token, scoped to that run.** One request per run, **after `init`** —
discovery asks the engine, which cannot answer before the providers are
installed. The body carries what the runner discovered:

```json
{
  "providers": ["aws", "vault.eu"],
  "discovery": "ok",
  "discovery-detail": ""
}
```

`providers` are audience-map keys: `aws`, or `provider.alias` for one aliased
configuration. Each is resolved **specific-then-general**, so `vault.eu` is
answered by an entry for `vault.eu` if there is one and by `vault` otherwise —
which is what lets an operator alias a provider five times without naming every
alias in the catalogue. An empty list is meaningful: a configuration may declare
no provider.

`discovery` is how much the runner trusts its own list — `ok`, `failed` (the
graph command errored or timed out) or `unparsed` (it ran and named provider
nodes, none of which could be read). The field exists because `failed` and
`unparsed` both arrive as an empty list, which is indistinguishable from a
provider-less configuration; taking them at face value would be a silent
fall-through to the agent pool's broader identity. The body accepts no other
field — `extra` is forbidden — and in particular **it cannot name a phase**,
which comes from the presented runner token.

**An engine that cannot discover its provider configurations is minted
everything its workspace resolves**, and `providers` and `discovery` are both
ignored for it. Pulumi is the case: a program is arbitrary code whose provider
instances are built at runtime, so nothing can be enumerated before the program
runs, and the thing that would run it needs the credentials. Which engines these
are is read from the **workspace row**, never from this body — the runner image
does not ship the engine registry, and a runner's claim about its own engine
would be the runner's rather than the platform's. Its runner sends an empty list
with `discovery: "ok"`, because nothing failed; there was no graph to read.

For such an engine the target limit is enforced rather than applied by
truncation: a workspace resolving more than **100** targets is answered `409`,
because a shortened token set looks complete and is not.

| Status | Meaning | What the runner does |
|---|---|---|
| **200** | `{"tokens": [{"target", "token", "audiences"}], "phase", "expires_in"}` | Writes each to `/var/run/terrapod/oidc/<target>/token` (mode `0600`) and exports `TERRAPOD_OIDC_TOKEN_DIR`, `TERRAPOD_RUN_PHASE` and `TF_VAR_terrapod_run_phase` (a configuration declaring that variable **must** mark it `ephemeral = true`, or the saved-plan apply is refused — see [cloud identity](cloud-identity.md)) |
| **204** | The workspace maps nothing; the issuer is not enabled deployment-wide; the configuration declares no provider; or nothing it uses is mapped | Takes no action. The run authenticates with the agent pool's identity, exactly as before |
| **404** | This API does not serve the route | Read as "nothing to do" — an API older than the runner image, which in agent mode upgrades independently |
| **409** | The resolved audiences changed since the run was created; discovery was not `ok` for a workspace that maps targets **and** whose engine discovers; or a non-discovering engine's workspace resolves more than 100 targets | **Fails the run**, carrying the reason |
| **422** | A stored audience-map key is not a usable provider configuration name (reachable only for a key written before the write-side guard existed) | **Fails the run**, naming the key to correct |
| **Other 4xx / 5xx** | Credentials were asked for and could not be had | **Fails the run.** Continuing would mean silently running under broader permissions than the operator chose |

The `204` is load-bearing: "not opted in" has to be distinguishable from
"broken", because those require opposite behaviour from the runner, and the
fall-through to the pool's identity is permanent and supported rather than a
migration step.

**The order of the checks is part of the contract.** A workspace that maps
nothing is answered `204` *before* `discovery` is examined, so a graph failure
can never fail a run that was not using the feature. Only then is a bad outcome
refused, and only then is the intersection computed.

**The `409` compares the run's snapshot against live configuration.**
`Run.oidc_audiences` is the mapping resolved when the run was created; this
endpoint re-resolves each requested target and refuses when the two disagree,
order included, naming the targets that moved. Minting from the snapshot alone
would hand an apply a token matching the reviewed plan while the cloud had moved
on, and the rejection would land inside the engine, possibly after a partial
apply.

The same comparison runs **at confirm time** as well, beside the state-drift and
plan-expiry staleness guards, so an apply is refused before a Job is scheduled —
scoped to the targets the run actually minted for, so one edit to the deployment
catalogue does not refuse every pending apply in the fleet. See
[cloud-identity.md](cloud-identity.md#when-the-configuration-moves-between-plan-and-apply).

**Response** (200):

| Field | Type | Meaning |
|---|---|---|
| `token` | string | The signed JWT |
| `expires_in` | int | `api.config.auth.oidc_issuer.token_ttl_seconds` |
| `phase` | string \| null | `plan` or `apply`, taken from the presented runner token. `null` when the token made no phase claim |
| `target` | string | Echoed, so the runner writes the file under the name it asked for |
| `audiences` | array&lt;string&gt; | **This target's** audiences, verbatim and in order |

**The phase comes from the presented runner token, never from the request body.**
A plan-phase runner asking for the apply identity is what this guards: put write
permissions behind a trust condition on `phase: apply` and a speculative
pull-request plan structurally cannot assume that role, because every PR-driven
run is plan-only.

**Claims:** `iss`, `sub` (`workspace:<name>@<id>:phase:<plan|apply>`), `agent_pool`
+ `agent_pool_id` (the pool that executed the run; absent when there is none), `aud` (this
target's audiences only), `workspace`, `workspace_id`, `phase` (absent when the
runner token made no phase claim), `run_id`, `terrapod_organization` (always the
literal `default`), plus `iat`, `nbf`, `exp`, `jti`. The header carries `kid`. `sub` carries the phase
as well as the discrete `phase` claim because Azure federated identity
credentials match on issuer, subject and audience only, with no access to
arbitrary claims — so `sub` is the one place a phase condition can be expressed
there. Targets that can read arbitrary claims should condition on the discrete
ones, which needs no wildcard. See
[the claim set](cloud-identity.md#the-claim-set).

### Audience Defaults

```
GET /api/terrapod/v1/oidc/audience-defaults
```

**Any authenticated user** — not platform admin. The deployment-wide audience
catalogue (`api.config.auth.oidc_issuer.audiences`) that a workspace's own
`oidc-audiences` map merges over, plus whether the issuer is published at all.

It exists because the two-level merge is otherwise hard to observe: a workspace
read returns the **merged** map, so it says what the workspace will actually
mint for but not which of those entries the workspace itself owns. Reading the catalogue beside it is what makes
the effective mapping visible.

**Response:**

```json
{"data": {"type": "oidc-audience-defaults", "id": "default",
  "attributes": {"audiences": {"aws": ["sts.amazonaws.com"]}, "issuer-enabled": true}}}
```

| Attribute | Type | Meaning |
|---|---|---|
| `audiences` | object | The catalogue: provider configuration → its audiences. `{}` by default, which is not an error |
| `issuer-enabled` | bool | `api.config.auth.oidc_issuer.enabled`. Reported separately because an empty catalogue and a disabled issuer are different states with the same symptom, and only one is fixed by adding audiences |

The gate is reasoned rather than lax: a workspace read already discloses that
workspace's audiences to anyone who can read it, so this adds only the entries a
workspace does not override — and requiring admin would put it out of reach of
exactly the person it is for, a workspace owner deciding whether to override a
key. Knowing an audience grants nothing on its own: the federation target's own
trust policy is the gate, and minting needs a phase-bound runner token scoped to
a run on that workspace.

Note what the runner-facing surface does **not** return: the catalogue. [Mint
Run Identity Tokens](#mint-run-identity-tokens) echoes the audiences for the
targets that run actually uses, because the runner asked for exactly those — but
it never enumerates the rest. The set of audiences names the roles this
deployment can ask to assume, so the whole of it stays on the authenticated
surface a person reads rather than on the one a Job holds a token for.

### List Signing Keys

```
GET /api/terrapod/v1/oidc/signing-keys
```

Platform `admin`. **Public key material only** — the private half never leaves
the API.

**Response attributes** (`data[].type` = `oidc-signing-keys`, `id` = `kid`):

| Attribute | Type | Meaning |
|---|---|---|
| `kid` | string | RFC 7638 JWK thumbprint — the same value a cloud sees in a token header |
| `created-at` | string | RFC3339 |
| `activates-at` | string | When this key starts signing. A rotated-in key is published immediately but signs only from here |
| `retired-at` | string \| null | When it stopped signing. It stays published for `retired_key_grace_seconds` after this |
| `signing` | bool | Whether this is the key currently signing |

`meta.signing-kid` repeats the signing key's `kid`, or is `null` when nothing is
loaded.

### Rotate Signing Key

```
POST /api/terrapod/v1/oidc/signing-keys/actions/rotate
```

Platform `admin`. Adds a key and retires the one currently signing. **201** with
the new key in the same shape as above, and a `meta.note`.

A published trust root cannot be swapped atomically, because the clouds fetch the
JWKS on their own schedule and cache it. So the new key is published immediately
and starts signing only after `key_propagation_seconds`, with the **retired key
signing across that window** — it is already in the published JWKS, so its
tokens verify. The retired key then stays published for
`retired_key_grace_seconds`, which must exceed both `token_ttl_seconds` and
`key_propagation_seconds`.

**409** on a deployment that supplies its own key
(`api.oidcSigningKey.existingSecret`): the key is the operator's and so is
rotating it — replace the Secret and restart the API.

See [runbooks.md → Rotating the OIDC issuer signing
key](runbooks.md#rotating-the-oidc-issuer-signing-key).

---

## Agent Pool Events (SSE)

```
GET /api/v1/agent-pools/{pool_id}/events
```

Server-Sent Events stream for real-time agent pool updates. Emits events when listeners heartbeat or join the pool. Used by the agent pool detail page for live listener status updates.

**Event types:**

| Event | Trigger |
|---|---|
| `listener_heartbeat` | A listener sends its periodic heartbeat |
| `listener_joined` | A new listener joins the pool |

**Required permission:** Platform `admin` or `audit`.

---

## Provider Cache (Network Mirror)

All provider mirror endpoints require authentication (runner token, API token, or session).

### Provider Version Index

```
GET /api/v1/provider-mirror/{hostname}/{namespace}/{type}/index.json
```

### Provider Version Details

```
GET /api/v1/provider-mirror/{hostname}/{namespace}/{type}/{version}.json
```

Returns platform-specific download URLs with `zh:` (zip hash) checksums.

---

## Auth Endpoints

### List Auth Providers

```
GET /api/v1/auth/providers
```

### Authorize (Start Login)

```
GET /api/v1/auth/authorize
```

### Callback (IDP Return)

```
GET /api/v1/auth/callback
POST /api/v1/auth/callback
```

### Active Sessions

```
GET /api/v1/auth/sessions
```

### Session Status

```
GET /api/v1/auth/session
```

Returns the caller's live web-session status for the expiry-warning banner
(#726): `{ "authenticated": true, "ttl_seconds": <int> }`. `ttl_seconds` is the
session's true remaining lifetime read straight from Redis **without sliding
it**, so the web client reconciles against the server's real TTL instead of a
stale client-cached timestamp — SSE-driven views slide the server session
without emitting the `X-Session-Expires` header, which used to make the banner
warn falsely. A `401` is the authoritative "session is gone → re-authenticate"
signal (session auth only; API-token callers get `401` here).

### Logout

```
POST /api/v1/auth/logout
```

---

## OAuth (Terraform Login)

### Authorize

```
GET /oauth/authorize
```

### Token Exchange

```
POST /oauth/token
```

---

## Audit Log

Immutable record of API requests. Requires `admin` or `audit` role.

### List Audit Log Entries

```
GET /api/v1/admin/audit-log
```

**Query Parameters:**

| Parameter | Type | Description |
|---|---|---|
| `filter[actor]` | string | Filter by actor email |
| `filter[resource-type]` | string | Filter by resource type (e.g. `workspaces`, `runs`) |
| `filter[action]` | string | Filter by HTTP method (GET, POST, PATCH, DELETE) |
| `filter[since]` | datetime | Only entries after this timestamp (RFC3339) |
| `filter[until]` | datetime | Only entries before this timestamp (RFC3339) |
| `page[number]` | integer | Page number (default: 1) |
| `page[size]` | integer | Page size (default: 20, max: 100) |

**Response:** JSON:API list of `audit-log-entries` with pagination metadata.

Besides HTTP requests, the log holds system events, whose `action` is a verb.
Every OpenBao/Vault read Terrapod makes for a run is one `vault.read` row
(`resource-type` `runs`), whose `detail` is JSON naming the variables, instance,
mount, path, engine, phase and outcome (`ok`, `denied`, `missing`, `transient`,
`error`), never a value. Filter with `filter[action]=vault.read`. See
[OpenBao/Vault → The audit trail](vault.md#the-audit-trail).

**Example:**

```zsh
curl "https://terrapod.example.com/api/v1/admin/audit-log?filter[actor]=admin@example.com&page[size]=10" \
  -H "Authorization: Bearer $TERRAPOD_TOKEN"
```

---

## Users

User management endpoints. List and show require `admin` or `audit` role. Update and delete require `admin` role.

### List Users

```
GET /api/v1/users
```

**Query Parameters:**

| Parameter | Type | Description |
|---|---|---|
| `filter[email]` | string | Filter by email (case-insensitive substring match) |
| `page[number]` | integer | Page number (default: 1) |
| `page[size]` | integer | Page size (default: 20, max: 100) |

### Show User

```
GET /api/v1/users/{email}
```

### Update User

```
PATCH /api/v1/users/{email}
```

**Updatable attributes:** `is-active`, `display-name`.

When `is-active` is set to `false`, all sessions for that user are revoked immediately.

### Delete User

```
DELETE /api/v1/users/{email}
```

Cascades: revokes all sessions, deletes all role assignments.

---

## Notification Configurations

Workspace-scoped notifications that fire on run lifecycle events. Three destination types: **generic** (webhook with HMAC-SHA512 signing), **slack** (Block Kit formatted), and **email** (SMTP).

### Create Notification Configuration

```
POST /api/v1/workspaces/{id}/notification-configurations
```

**Request body:**
```json
{
  "data": {
    "type": "notification-configurations",
    "attributes": {
      "name": "deploy-alerts",
      "destination-type": "generic",
      "url": "https://example.com/webhook",
      "token": "my-hmac-secret",
      "enabled": true,
      "triggers": ["run:completed", "run:errored"]
    }
  }
}
```

**Destination types:**

| Type | Required fields | Optional |
|---|---|---|
| `generic` | `url` | `token` (HMAC-SHA512 signing) |
| `slack` | `url` (Slack webhook URL) | — |
| `email` | `email-addresses` (list) | — |

**Valid triggers:** `run:created`, `run:planning`, `run:needs_attention`, `run:planned`, `run:applying`, `run:completed`, `run:errored`, `run:drift_detected`

**Required permission:** `admin` on the workspace.

### List Notification Configurations

```
GET /api/v1/workspaces/{id}/notification-configurations
```

**Required permission:** `read` on the workspace.

### Show Notification Configuration

```
GET /api/v1/notification-configurations/{id}
```

**Required permission:** `read` on the associated workspace.

### Update Notification Configuration

```
PATCH /api/v1/notification-configurations/{id}
```

Same body format as create. Only include attributes to change. Token is never returned in responses — only `has-token: true/false`.

**Required permission:** `admin` on the workspace.

### Delete Notification Configuration

```
DELETE /api/v1/notification-configurations/{id}
```

**Required permission:** `admin` on the workspace.

### Verify Notification Configuration

```
POST /api/v1/notification-configurations/{id}/actions/verify
```

Sends a test payload to the configured destination and returns the delivery response.

**Required permission:** `admin` on the workspace.

---

## Slack account linking

Binds a Slack identity (team + user) to a Terrapod identity, established once via
an explicit login (the "connect your Terrapod account" flow) and reused for every
subsequent Slack-initiated action. The binding is long-lived **identity**, never
entitlement — RBAC is re-checked live on each action. See
[Slack integration](slack-integration.md) (#556).

### Preview link

```
POST /api/v1/slack/link/preview
```

Body `{"state": "<signed-state>"}`. Requires an authenticated Terrapod user.
Describes **which** Slack identity the signed state would bind, **without
consuming** the single-use state, so the browser can show an explicit confirm
screen before binding. `422` if the state is missing, `400` if it is
invalid/expired/already used. Binding still happens only on `POST /slack/link`.

Returns `{data: {slack-team-id, slack-user-id, email, user-name, user-real-name,
team-name, resolved}}` — `email` is the caller's, and the three name fields are the
confused-deputy defence (`GHSA-5899-fm2p-88x3`). It used to return the ids alone,
which nobody can recognise as not their own, so the confirm screen asked a question
the reader could not answer. **`user-name` is the handle and is the one to judge
by**: it is unique in the workspace, where `user-real-name` is set by its owner and
can be made to match anyone.

`resolved` is `"true"`/`"false"` and is explicit so a client can distinguish an
absent display name from a failed lookup. The lookup needs the bot `users:read` and
`team:read` scopes and is **best-effort** — without them, or during a Slack outage,
the fields come back empty with `resolved: "false"` and linking still works. An app
installed from a manifest predating those scopes must be reinstalled to grant them,
or the screen falls back to ids.

### Link account

```
POST /api/v1/slack/link
```

Body `{"state": "<signed-state>"}`. Requires an authenticated Terrapod user;
verifies + consumes the single-use signed state (minted by the `/terrapod link`
flow) and binds the **acting** user's identity to the Slack (team, user) in the
state. `422` if the state is missing, `400` if it is invalid/expired/already used.

### List my Slack links

```
GET /api/v1/slack/links
```

Returns the current user's Slack identity links.

### Unlink

```
DELETE /api/v1/slack/links/{link_id}
```

Removes one of the current user's own links (`404` if it isn't theirs).

Both creating and removing a link write an audit entry (`slack.link.create` /
`slack.link.revoke`) naming the actor and the Slack identity. A binding is a
standing ability to act as that account from Slack, and it previously left no record
at all, so "who attached that Slack account" had no answer.

## Execution Hooks

Reusable custom-shell steps run inside the runner Job at fixed points
(`pre_init`, `pre_plan`, `post_plan`, `pre_apply`, `post_apply`). A hook is an
admin-managed library entry, associated with the workspaces that use it — there
is no global scope. See [Execution Hooks](execution-hooks.md) for the full
guide. Delivery is gated by the platform kill-switch `runners.hooksEnabled`
(Helm, default `true`).

### Create Execution Hook

```
POST /api/v1/execution-hooks
```

**Request body:**
```json
{
  "data": {
    "type": "execution-hooks",
    "attributes": {
      "name": "internal-hosts-entry",
      "description": "Add an internal registry host before init",
      "hook-point": "pre_init",
      "script": "echo '10.0.0.5 registry.internal' >> /etc/hosts",
      "enabled": true,
      "priority": 0
    }
  }
}
```

**Valid hook-point:** `pre_init`, `pre_plan`, `post_plan`, `pre_apply`, `post_apply`. An unknown point returns 422; a duplicate name returns 409.

**Required permission:** `admin`.

### List Execution Hooks

```
GET /api/v1/execution-hooks
```

**Required permission:** `admin`.

### Show Execution Hook

```
GET /api/v1/execution-hooks/{id}
```

**Required permission:** `admin`.

### Update Execution Hook

```
PATCH /api/v1/execution-hooks/{id}
```

Same body format as create; include only the attributes to change.

**Required permission:** `admin`.

### Delete Execution Hook

```
DELETE /api/v1/execution-hooks/{id}
```

Removes the hook and all its workspace associations.

**Required permission:** `admin`.

### Associate / Dissociate Workspaces

```
POST   /api/v1/execution-hooks/{id}/relationships/workspaces
DELETE /api/v1/execution-hooks/{id}/relationships/workspaces
```

**Request body** (both verbs, idempotent):
```json
{ "data": [{ "id": "ws-...", "type": "workspaces" }] }
```

**Required permission:** `admin`.

---

## Policy Sets

OPA policy-as-code enforcement. Policy sets and their policies are admin-managed; per-run policy evaluations are readable by anyone with read on the run's workspace. See [policies.md](policies.md) for the Rego authoring contract.

### List Policy Sets

```
GET /api/v1/policy-sets
```

Returns all policy sets. **Required permission:** `admin` or `audit`.

### Create Policy Set

```
POST /api/v1/policy-sets
```

```json
{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "production-guardrails",
      "description": "Mandatory guardrails for production",
      "enforcement-level": "mandatory",
      "global-scope": false,
      "allow-labels": {"env": ["prod"]},
      "deny-names": ["prod-sandbox"]
    }
  }
}
```

`enforcement-level` is `advisory` (default) or `mandatory`. Scoping is `global-scope: true` (every workspace) or the `allow-labels` / `allow-names` / `deny-labels` / `deny-names` rules (same label model as roles; deny wins). **Required permission:** `admin`.

#### VCS-Sourced Policy Sets

Set `source` to `"vcs"` to create a policy set that syncs `.rego` files from a git repository instead of managing policies inline via the API:

```json
{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "security-baseline",
      "enforcement-level": "mandatory",
      "source": "vcs",
      "vcs-connection-id": "vcs-<uuid>",
      "vcs-repo-url": "https://github.com/org/policies",
      "vcs-branch": "main",
      "policy-path": "policies"
    }
  }
}
```

**VCS-specific attributes:**

| Attribute | Type | Description |
|---|---|---|
| `source` | string | `"inline"` (default) or `"vcs"` |
| `vcs-connection-id` | string | Required when `source=vcs`. References a VCS connection (`vcs-<uuid>` format). |
| `vcs-repo-url` | string | Required when `source=vcs`. HTTPS clone URL of the repo. |
| `vcs-branch` | string | Branch to track. Defaults to the repo's default branch if empty. |
| `policy-path` | string | Directory within the repo containing the set's files. Only direct children are loaded (no recursive descent). Empty string means repo root. Since v1.8.0 this takes `.rego` **and** `.yaml`/`.yml`/`.json` data files, plus `.rego` helpers defining no `deny`/`warn` — so any YAML or JSON in this directory is carried into the set. `*_test.rego` is never synced, and a file over 1 MiB is skipped and reported on `vcs-last-error`. |
| `shared-evaluation` | boolean | Evaluate the set's files together in one `opa eval`, so policies can call shared helper rules and read the data files committed beside them. Defaults to `false` — every set evaluated one policy at a time before this existed. Results become per-SET rather than per-policy: the files share `package terrapod`, so OPA cannot attribute a denial to one file. **Requires runners new enough to understand it** — see [`policies.md`](policies.md#runner-version), because an older runner evaluates without the data files and a rule reading `data.x` then passes rather than failing. |
| `support-file-names` | array | Read-only. The data files and helpers the last sync found, sorted. Use it to confirm your files were picked up; an empty list on a set with `shared-evaluation` on usually means the wrong `policy-path`. Written only by the VCS sync — there is no way to set it through the API. |
| `vcs-last-commit-sha` | string | Read-only. SHA of the last successfully synced commit. |
| `vcs-last-synced-at` | string | Read-only. RFC 3339 timestamp of last successful sync. |
| `vcs-last-error` | string\|null | Read-only. Error message from the most recent sync attempt, or null. |

When `source=vcs`, inline policy CRUD is rejected with **409 Conflict** — policies are managed exclusively by the linked repository.

### Sync VCS Policy Set

```
POST /api/v1/policy-sets/{id}/actions/sync
```

Triggers an immediate sync of a VCS-sourced policy set. Returns **202 Accepted** with the current policy set state; the actual sync runs asynchronously. Returns **409 Conflict** if the policy set has `source=inline`. **Required permission:** `admin`.

### Show / Update / Delete Policy Set

```
GET    /api/v1/policy-sets/{id}     # policies embedded
PATCH  /api/v1/policy-sets/{id}     # partial update
DELETE /api/v1/policy-sets/{id}
```

Deleting a set removes its policies; recorded run evaluations are kept (set reference nulled, name snapshot retained). **Required permission:** `admin` (`admin`/`audit` for show).

### Manage Policies

```
POST   /api/v1/policy-sets/{id}/policies   # add a policy
PATCH  /api/v1/policies/{id}               # update
DELETE /api/v1/policies/{id}
```

```json
{
  "data": {
    "type": "policies",
    "attributes": {
      "name": "no-public-buckets",
      "rego": "package terrapod\n\ndeny contains msg if { ... }"
    }
  }
}
```

The Rego is validated with `opa check` on create/update — broken Rego, or Rego that does not declare `package terrapod`, is rejected with 422. **Required permission:** `admin`.

### List Run Policy Evaluations

```
GET /api/v1/runs/{run_id}/policy-evaluations
```

Returns the policy evaluations recorded for a run, plus a `meta.summary` (`status`: `passed` / `advisory-failed` / `blocked`, and counts). Each evaluation's `result` carries the per-policy violations/warnings. This is the endpoint behind the run's `policy-checks` relationship link. Both Terraform and Pulumi runs are evaluated, against their own engine's account of the change (see [`docs/policies.md`](policies.md#what-a-policy-can-read)). `meta.not-evaluated-reason` is present only for an engine that cannot be evaluated at all, and no current engine is in that position. **Required permission:** `read` on the run's workspace.

### Override Run Policy

```
POST /api/v1/runs/{run_id}/actions/override-policy
```

Overrides every failed/errored policy evaluation of a run and immediately re-drives a run held at the post-plan policy gate. **Required permission:** `admin` on the run's workspace.

### Policy checks

```
GET  /api/tfe/v2/runs/{run_id}/policy-checks
GET  /api/tfe/v2/policy-checks/{id}
GET  /api/tfe/v2/policy-checks/{id}/output
POST /api/tfe/v2/policy-checks/{id}/actions/override
```

The run's post-plan gates in the Terraform Enterprise `policy-checks` shape that the `tofu`/`terraform` CLI reads (#1704). A run has up to two checks, each present only when its gate recorded something: `polchk-opa-<run uuid>` for its OPA policy sets (`scope: organization`) and `polchk-scan-<run uuid>` for its security scan (`scope: workspace`).

```json
{
  "data": {
    "id": "polchk-opa-01a0af8c-79a0-759c-86e3-3607f5b419e6",
    "type": "policy-checks",
    "attributes": {
      "status": "soft_failed",
      "scope": "organization",
      "result": {"result": false, "passed": 1, "total-failed": 1, "hard-failed": 0,
                 "soft-failed": 1, "advisory-failed": 0, "duration": 0},
      "actions": {"is-overridable": true},
      "permissions": {"can-override": true},
      "status-timestamps": {"queued-at": "2026-09-17T12:30:00Z", "soft-failed-at": "2026-09-17T12:30:00Z"}
    },
    "relationships": {"run": {"data": {"id": "run-01a0af8c-79a0-759c-86e3-3607f5b419e6", "type": "runs"}}}
  }
}
```

`status` is `soft_failed` while a mandatory policy set's (or an enforced scan's) failure is not overridden, `overridden` once it is, and `passed` otherwise — an advisory failure passes, counted in `advisory-failed`. `/output` returns `text/plain`: each policy set with its denies and warnings, or the scan's findings, worst first. The override overrides everything the check covers (every failed policy set, or the scan) and moves a held run on at once; it answers **409** for a check that is not `soft_failed`. The run advertises these checks in its `policy-checks` relationship only in the Terraform Enterprise vocabulary, but the endpoints are always served.

**Required permission:** `read` on the run's workspace to list or read (a caller without it gets **404**); `admin` to override, which is also what `permissions.can-override` reports.

### Runner protocol — Policy Bundle

```
GET /api/v1/runs/{run_id}/policy-bundle
```

Returns the applicable policy sets + run/workspace context for a run. Used by the runner during the plan phase to drive OPA evaluation locally. A persistent fetch failure on the runner is **fatal** to the run (see [`docs/runners.md` — OPA Policy Evaluation](runners.md)) — there is no silent skip. Response shape is a flat JSON document (not JSON:API — the runner is the only consumer):

```json
{
  "policy_sets": [
    {
      "id": "polset-...",
      "name": "...",
      "enforcement_level": "mandatory",
      "policies": [
        {"id": "pol-...", "name": "...", "rego": "package terrapod\n..."}
      ]
    }
  ],
  "context": {
    "workspace": {"id": "...", "name": "...", "labels": {...}},
    "run": {"id": "...", "message": "...", "source": "...", "is_destroy": false, "plan_only": false}
  }
}
```

`policy_sets` is an empty list when nothing is in scope for the workspace — the runner then skips evaluation entirely. **Required permission:** runner token scoped to this `run_id`.

### Runner protocol — Policy Results

```
POST /api/v1/runs/{run_id}/policy-results
```

```json
{
  "results": [
    {
      "policy_set_id": "polset-...",
      "policy_set_name": "...",
      "enforcement_level": "mandatory",
      "outcome": "failed",
      "result": {
        "policies": [
          {"policy": "...", "passed": false, "violations": ["..."], "warnings": [], "error": null}
        ],
        "evaluated_at": "2026-05-24T10:00:00Z"
      }
    }
  ]
}
```

Records the runner's policy-evaluation outcomes for the run. Persisted via Postgres `ON CONFLICT DO NOTHING` on `(run_id, policy_set_id)` so a retried POST after a transient failure is idempotent. The runner POSTs this **before** posting plan-result, so the API's post-plan gate sees the rows when it queries them. **Required permission:** runner token scoped to this `run_id`.

---

## Onboarding / Resource Discovery

Discover existing, unmanaged cloud resources and generate copy-pasteable `resource {}` + `import {}` blocks, then bring them under management with a single gated import run. A session drives a discovery engine: **D1 schema** discovery runs credential-lessly in the API; **D2 query** + **D3 generate/clean** run on the runner; the only mutating step is an operator-confirmed, plan-only import run through the normal run gate.

Onboarding has **no feature flag** — it is gated per workspace by the `workspace:onboard` capability (see [Roles](#roles)). Every session endpoint requires `workspace:onboard` on the workspace, returning `403` otherwise. The optional **AI mode** (natural-language selection + config cleanup) is the only part behind a switch (`api.config.ai_onboarding.enabled`); it never alters an attribute value or an import id.

### Availability Probe

```
GET /api/v1/onboarding
```

Any authenticated user. Reports whether the optional AI mode is available, so the UI can offer the conversational path when it is configured. Onboarding itself is always present — actual access is decided per-workspace by the `workspace:onboard` capability on the real endpoints.

**Response:**
```json
{
  "data": {
    "type": "onboarding-availability",
    "attributes": {
      "ai-available": true,
      "ai-model-configured": true
    }
  }
}
```

| Attribute | Description |
|---|---|
| `ai-available` | Whether the AI mode switch (`ai_onboarding.enabled`) is on. |
| `ai-model-configured` | Whether AI mode is on **and** a model is configured. |

### Create Onboarding Session

```
POST /api/v1/workspaces/{id}/onboarding-sessions
```

Requires `workspace:onboard`. Starts a session and kicks off credential-less D1 schema discovery on a scheduler trigger (off the request thread). The client polls the session (below) until `status == "schema_ready"`, then reads the discovery surface and selects the data-source types to query.

**Request body:**
```json
{
  "data": {
    "type": "onboarding-sessions",
    "attributes": {
      "provider": "aws",
      "provider-version": "< 6.0"
    }
  }
}
```

| Attribute | Description |
|---|---|
| `provider` | The terraform/tofu provider to onboard, lowercase (e.g. `aws`). One provider per session; onboard several by running several sessions. Invalid → `422`. |
| `provider-version` | Optional provider version *constraint* pinned in the generated `providers.tf` (e.g. `< 6.0`, `~> 5.0`). Empty = unconstrained (latest). Must be a valid terraform version constraint or → `422`. |

Returns `201` with the serialized session (below).

### List Onboarding Sessions

```
GET /api/v1/workspaces/{id}/onboarding-sessions
```

Requires `workspace:onboard`. Returns the workspace's sessions. The (large, per-session) discovery surface is **omitted** from the list — fetch a single session for it.

### Show Onboarding Session

```
GET /api/v1/onboarding-sessions/{id}
```

Requires `workspace:onboard` on the session's workspace. Returns the session **including** its `discovery-surface` (served from a time-limited Redis cache — never persisted per-session; an expired session simply re-runs discovery). Once `status == "config_ready"`, the generated config and import blocks are present.

### Start Discovery (D2/D3)

```
POST /api/v1/onboarding-sessions/{id}/discover
```

Requires `workspace:onboard`. Dispatches the runner discovery run for a `schema_ready` session, querying the selected subset of the session's discovery surface. A session not in `schema_ready` → `422`.

**Request body:**
```json
{
  "data": {
    "type": "onboarding-sessions",
    "attributes": {
      "selected-types": ["aws_vpcs", "aws_subnets"]
    }
  }
}
```

| Attribute | Description |
|---|---|
| `selected-types` | The data-source types (a subset of the session's discovery surface) to query. Must be a list of strings or → `422`. |

Returns the serialized session (now with `discovery-run-id` set).

### Session Attributes

The `onboarding-sessions` JSON:API resource the UI consumes:

| Attribute | Description |
|---|---|
| `workspace-id` | The owning workspace. |
| `status` | Session lifecycle state, one of `pending`, `schema_ready`, `querying`, `config_ready`, `run_created`, `errored`, `canceled`. |
| `provider` | The provider being onboarded (e.g. `aws`). |
| `provider-version` | The provider version constraint pinned in the generated `providers.tf`; empty = unconstrained. |
| `engine` | The engine D1 ran with (`terraform` / `tofu`). |
| `engine-version` | The resolved engine version D1 ran with. |
| `selected-types` | The data-source types selected for the D2 query. |
| `ai-assisted` | Whether the optional AI mode assisted this session (naming, cleanup, chat). True iff the polished view exists. |
| `discovery-surface` | The D1 provider-schema surface (from the Redis cache). Present only on the **show** (detail) read; `null` on list. |
| `data-source-count` | Count derived from the discovery surface (`null` when the surface isn't included). |
| `generated-config` | D3 output — the cleaned, import-only `resource {}` config (null/empty ConflictsWith attributes pruned so it plans). Present once `status == config_ready`. |
| `import-blocks` | D3 output — the candidate `import {}` blocks. Present once `status == config_ready`. |
| `polished-config` | Optional AI-polished view of `generated-config` (resources renamed from tags, grouped, commented). **Never alters a value or import id** (enforced by a value-preservation check). `null` until the polish lands or if rejected / AI disabled. |
| `polished-import-blocks` | The polished counterpart to `import-blocks`; renames are mirrored deterministically into the `to = <addr>` targets. |
| `paired-config` | **Derived presentation view** (computed at serialize time, never stored): each `import {}` interleaved directly above the resource it targets, over the canonical `generated-config`/`import-blocks`. Ids/values untouched. `null` until config exists. |
| `paired-polished-config` | The same derived pairing over the polished halves. `null` until the polished config exists. |
| `discovery-run-id` | The runner discovery run that produced the query results + config (D2/D3), or `null`. |
| `result-run-id` | The resulting gated import-only run, or `null`. |
| `error` | Human-readable failure detail when `status == "errored"`. |
| `created-by` | The user who started the session. |
| `created-at` | RFC3339 timestamp. |
| `updated-at` | RFC3339 timestamp. |

### Runner Discovery Artifacts

The runner discovery Job uploads its generated artifacts to these endpoints. Auth is a **runner token scoped to the discovery run** — each endpoint resolves the owning session via its `discovery_run_id` (== this run), so a Job can only ever write to its own session. Bodies are capped (`413` if too large).

```
PUT  /api/v1/runs/{run_id}/artifacts/onboarding-config
```
The cleaned, import-only generated `resource {}` config (D3 + clean). Body is `.tf` text; stored on the session's `generated-config`. Returns `204`.

```
PUT  /api/v1/runs/{run_id}/artifacts/onboarding-imports
```
The candidate `import {}` blocks (D3). Body is `.tf` text; stored on the session's `import-blocks`. Returns `204`.

```
POST /api/v1/runs/{run_id}/artifacts/onboarding-query-results
```
The raw D2 query results + the import-only verdict (JSON object; non-JSON or non-object → `422`). Stored on the session. Returns `204`.

> **Import run is always plan-only:** the confirmed import step is a gated, **import-only** run (plan-only) through the normal run gate — never an auto-apply.

## Cost Estimation

Terrapod estimates the monthly cost of Terraform/OpenTofu-managed infrastructure using a **native, pure-Python engine over its own self-generated pricesheet** — produced by `pricegen` from official cloud vendor pricing data and published weekly to a rolling GitHub Release. Terrapod ships **no binary and shells out to nothing**; it downloads the gzipped pricesheet and matches plan/state resources against it in-process.

Every figure returned here is **data** (engine-derived) — no AI is involved. (An optional AI *enhancement* — narrative + savings advisories — is a separate surface that rides the plan-analysis AI switch and is always flagged distinctly; it never blends into these authoritative numbers.)

Cost estimation is **on by default** (Helm: `api.config.cost_estimation.enabled`, default `true`); when disabled the endpoints below return `404`. The pricesheet is a **pull-through cache** (mirrored into object storage on demand, no schedule) — air-gapped deployments pre-seed the cached object or point `cost_estimation.prices_url` at an internal mirror. `cost_estimation.default_region` is only the fallback for a resource whose region can't be resolved from its own attributes or provider config (region is resolved **per resource**).

There are two cost views: a **run** view (the monthly cost *delta* a plan introduces) and a **workspace** view (the *current* monthly cost of the workspace's managed infrastructure, priced from its latest state version).

### Show Run Cost Estimate

```
GET /api/v1/runs/{run_id}/cost-estimate
```

Requires `run:read` on the run's workspace. Returns the runner-produced estimate of the plan's monthly cost delta (`404` when the run produced no estimate — errored before plan, cost estimation disabled, or the artifact aged out).

**Response:**
```json
{
  "data": {
    "id": "cost-estimate-<run-uuid>",
    "type": "cost-estimates",
    "attributes": {
      "currency": "USD",
      "total": { "min": 219.0, "max": 219.0 },
      "previous": { "min": 73.0, "max": 73.0 },
      "diff": { "min": 146.0, "max": 146.0 },
      "resources": [
        { "address": "aws_instance.eu", "type": "aws_instance", "name": "eu", "change": "add", "monthly": { "min": 146.0, "max": 146.0 } },
        { "address": "aws_nat_gateway.gw", "type": "aws_nat_gateway", "name": "gw", "change": "add", "monthly": { "min": 37.35, "max": 37.35 },
          "usage_assumptions": [ { "description": "NAT data processed", "dimension": "data processed", "unit": "GB/month", "low": 10, "typical": 100, "high": 50000, "cost_low": 0.45, "cost_typical": 4.50, "cost_high": 2250.0 } ] }
      ],
      "unpriced": [ { "address": "random_pet.name", "type": "random_pet", "change": "add" } ]
    },
    "relationships": { "run": { "data": { "id": "run-<uuid>", "type": "runs" } } }
  }
}
```

| Attribute | Description |
|---|---|
| `currency` | Pricesheet currency (typically `USD`). |
| `total` | Projected monthly spend of the planned state (min/max range). |
| `previous` | Projected monthly spend of the prior state (`total − diff`). |
| `diff` | Monthly delta this run introduces (adds positive, removes negative). |
| `resources[]` | Per-resource cost; `change` is `add` / `remove` / `noop`. |
| `resources[].usage_assumptions[]` | Present only on resources whose cost depends on runtime usage the plan doesn't declare (data processed, invocations, storage). Each entry is `{description, dimension, unit, low, typical, high, cost_low, cost_typical, cost_high}`: `low`/`typical`/`high` are the assumed *quantity* (in `unit`); `cost_low`/`cost_typical`/`cost_high` are the resulting monthly *cost* at each. The `monthly` figure folds in `cost_typical`; the true cost sits in `cost_low`–`cost_high` as usage varies. `cost_*` are omitted if the band couldn't be priced. Raw data — surfaced independently of the AI layer so the estimate is honest with AI off. Omitted entirely for deterministically-priced resources. |
| `unpriced[]` | Resources nothing in the pricesheet matched (unmapped/free type, or a provider the data doesn't cover). |

### Show Workspace Cost Estimate

```
GET /api/v1/workspaces/{id}/cost-estimate
```

Requires `state:read` on the workspace (the estimate is derived server-side from the secret-bearing state blob, though only non-sensitive aggregates are returned). Runs the workspace's **latest state version** through the cost engine to report the current monthly cost of its managed infrastructure — the state analogue of the run delta above. Because state carries no change, every resource is a `noop`, `diff` is zero, and `total` is the current monthly spend.

A workspace with **no state yet** (or a state-version row whose bytes haven't landed / were swept) returns a zeroed estimate with `state-version: null` rather than an error. `503` when no pricesheet is available (upstream fetch failed and nothing is cached).

**Response:**
```json
{
  "data": {
    "id": "workspace-cost-<workspace-uuid>",
    "type": "workspace-cost-estimates",
    "attributes": {
      "currency": "USD",
      "total": { "min": 292.0, "max": 292.0 },
      "previous": { "min": 292.0, "max": 292.0 },
      "diff": { "min": 0.0, "max": 0.0 },
      "resources": [
        { "address": "aws_instance.web", "type": "aws_instance", "name": "web", "change": "noop", "monthly": { "min": 73.0, "max": 73.0 } }
      ],
      "unpriced": [],
      "state-version": { "id": "sv-<uuid>", "serial": 7, "created-at": "2026-01-01T00:00:00Z" }
    },
    "relationships": { "workspace": { "data": { "id": "ws-<uuid>", "type": "workspaces" } } }
  }
}
```

The attributes match the run estimate, plus `state-version` naming the priced version (`null` when the workspace has no state).

### Pricesheet (runner + admin)

```
GET  /api/v1/cost-estimation/pricesheet             # 302 → presigned cached pricesheet (gzipped YAML) (any authenticated caller; consumed by runner Jobs)
GET  /api/v1/cost-estimation/pricesheet/status      # admin: enabled + cached?
POST /api/v1/cost-estimation/pricesheet/refresh     # admin: force re-fetch from upstream
```

The download endpoint is pull-through: a cold or stale cache is fetched from `cost_estimation.prices_url` on demand, and a stale copy is served if a refresh fails (a transient upstream outage never breaks a run). `404` when cost estimation is disabled or nothing is cached; the returned presigned URL needs no auth. `refresh` returns `502` on an upstream/decompress failure.

### AI cost estimate (summary + advisories + chat)

The optional AI layer over the data-only estimate (rides `ai_summary.enabled` + the per-workspace mode). Its **primary** output is estimates for the resources the pricesheet couldn't price; secondary are savings advisories and a short narrative. Every dollar figure is tagged `source: "ai-estimate"`, shown separately from the authoritative deterministic total and never summed into it.

```
GET  /api/v1/runs/{run_id}/cost-summary[?locale=<code>]
POST /api/v1/runs/{run_id}/cost-summary/regenerate
```

`GET` returns the summary; `404` until one has been generated (a `pending` row means "in flight"). With `?locale=` set to a real language different from the deployment's `ai_summary.summary_language`, the narrative + each estimate's `basis` + each advisory's `title`/`detail` are translated on view (best-effort, Redis-cached), and `translated`/`language` reflect that. `POST .../regenerate` re-fires it and returns `202` with a `pending` row (`409` when the run has no cost estimate; `503` when AI is globally disabled).

**Response (`ready`):**
```json
{
  "data": {
    "id": "cost-summary-<uuid>",
    "type": "cost-summaries",
    "attributes": {
      "status": "ready",
      "estimated-resources": [
        { "address": "azurerm_storage_account.a", "type": "azurerm_storage_account", "monthly": { "min": 5.0, "max": 8.0 }, "basis": "LRS hot ~100GB", "source": "ai-estimate" }
      ],
      "advisories": [
        { "kind": "reserved", "title": "1-year RI", "detail": "…", "monthly_saving": { "min": 14.0, "max": 21.0 }, "source": "ai-estimate" }
      ],
      "narrative": "The unpriced resources add an estimated …",
      "model": "bedrock/…", "input-tokens": 120, "output-tokens": 60,
      "language": "en", "translated": false,
      "created-at": "2026-01-01T00:00:00Z", "updated-at": "2026-01-01T00:01:00Z"
    },
    "relationships": { "run": { "data": { "id": "run-<uuid>", "type": "runs" } } }
  }
}
```

`status` is one of `pending` / `ready` / `errored` / `skipped`. Advisory `kind` is one of `savings_plan` / `reserved` / `spot` / `rightsizing` / `other`; `monthly_saving` may be `null`.

#### Cost chat

A follow-up Q&A thread grounded in the estimate (the cost analogue of the [plan-summary chat](#list-plan-summary-chat-messages)), one shared thread per run.

```
GET  /api/v1/runs/{run_id}/cost-summary/messages[?locale=<code>]
POST /api/v1/runs/{run_id}/cost-summary/messages
```

`GET` returns the transcript (`cost-summary-messages`, chronological; each message translated on view when `?locale=` is set, with a per-message `translated` flag). `POST` a body of `{"data": {"attributes": {"content": "…", "locale": "de"}}}` to ask a question and get the synchronous assistant reply (`201`). Read-on-workspace auth. Error mapping mirrors the plan chat: `409` (per-run message cap hit, or the summary isn't `ready`), `429` (daily token budget hit), `503` (chat disabled), `400` (empty/oversize body), `502` (model failure — the user turn is still recorded). The model answers from the estimate only and keeps computed-vs-estimated figures distinct.

## Service Catalog

No-code self-service provisioning over the private module registry. A *catalog item* blesses a registry module; provisioning it creates an agent-mode, non-VCS, catalog-managed workspace whose configuration is a server-generated wrapper. See [Service Catalog](service-catalog.md) for the full feature doc.

All endpoints below are **gated on `catalog.enabled`** (Helm: `api.config.catalog.enabled`, default `true`). When the catalog is disabled every endpoint returns `404`. The `catalog_permission` role axis is opt-in (default `none`), so the feature being enabled grants no access on its own.

Catalog access is governed by a dedicated role axis, `catalog-permission` (`none`/`read`/`use`/`admin`, default `none`, no `everyone` floor) — see [Roles](#roles).

### Provider Templates

Admin-managed parameterised provider configs rendered into the generated `providers.tf`. **Write** requires platform `admin`; **list/show** require platform `admin` or `audit`.

#### List Provider Templates

```
GET /api/v1/provider-templates
```

#### Create Provider Template

```
POST /api/v1/provider-templates
```

**Request body:**
```json
{
  "data": {
    "type": "provider-templates",
    "attributes": {
      "name": "aws-standard",
      "provider-type": "aws",
      "body": "provider \"aws\" {\n  region = var.aws_region\n  assume_role { role_arn = var.aws_role_arn }\n}",
      "parameters": [
        { "name": "aws_region",   "type": "string", "description": "Target AWS region" },
        { "name": "aws_role_arn", "type": "string", "description": "Role to assume" }
      ],
      "labels": {"team": "platform"}
    }
  }
}
```

| Attribute | Description |
|---|---|
| `name` | Unique display name. |
| `provider-type` | The provider configured, e.g. `aws`, `google`, `azurerm`. |
| `body` | HCL provider body referencing `var.*`. Rendered verbatim — no server-side interpolation. |
| `parameters` | Declared parameters; each becomes a Terraform variable on instances that use this template, surfaced as a provision-form field. |
| `labels` | For label-based RBAC. |

#### Show / Update / Delete Provider Template

```
GET    /api/v1/provider-templates/{id}
PATCH  /api/v1/provider-templates/{id}
DELETE /api/v1/provider-templates/{id}
```

### Catalog Items

A blessed designation over a registry module. **Write** (create/update/delete) requires platform `admin`. **List/show** require catalog `read` and are **filtered per item** to those the caller's role matches.

#### List Catalog Items

```
GET /api/v1/catalog-items
```

Returns only items the caller's `catalog-permission` matches.

#### Create Catalog Item

```
POST /api/v1/catalog-items
```

**Request body:**
```json
{
  "data": {
    "type": "catalog-items",
    "attributes": {
      "name": "vpc",
      "display-name": "AWS VPC",
      "description": "Standard VPC with public and private subnets",
      "enabled": true,
      "module-id": "mod-019e0e7b-...",
      "default-version-pin": "1.4.0",
      "provider-template-ids": ["ptpl-019e01db-..."],
      "allowed-agent-pool-ids": ["apool-019e01db-..."],
      "variable-options": [
        { "name": "cidr_block", "description": "VPC CIDR", "default": "10.0.0.0/16" },
        { "name": "environment", "options": ["dev", "staging", "prod"] },
        { "name": "account_id", "hidden": true, "default": "123456789012" }
      ],
      "labels": {"team": "platform"}
    }
  }
}
```

| Attribute | Description |
|---|---|
| `name` | Unique slug. |
| `display-name` | Human-facing name shown in the catalog UI. |
| `description` | Free text. |
| `enabled` | When `false`, the item is visible but provisioning is rejected with `409`. |
| `module-id` | The registry module this item wraps. |
| `default-version-pin` | Default module-version pin new instances inherit. Omit for **float** (track latest published). |
| `provider-template-ids` | Provider templates rendered into the generated wrapper. |
| `allowed-agent-pool-ids` | Pools an instance may bind to. `null` = any pool the provisioner has `write` on. |
| `variable-options` | Per-input overlay list (one object per input, keyed by `name`) curating the module's variables. Each entry supports: `options` (allow-list, **enforced server-side** — value outside it → `422`, rendered as a dropdown); `default` (preset, still editable); `hidden` (fix the value + remove from the form — **must include a `default`**, and supplying it returns `422`); `sensitive` (masked, stored write-only). Validated at create/update: a malformed entry, non-list `options`, or `hidden` without `default` → `422`. |
| `labels` | For label-based RBAC (decides which roles see/use the item). |

#### Show / Update / Delete Catalog Item

```
GET    /api/v1/catalog-items/{id}
PATCH  /api/v1/catalog-items/{id}
DELETE /api/v1/catalog-items/{id}
```

Delete returns `409` while the item has any instances — destroy or migrate them first.

#### Provision Form

```
GET /api/v1/catalog-items/{id}/form
```

Returns the resolved provision form: `resolved-version` (per the item's version policy) and `fields[]` — one field per resolved input (the module's curated variables plus every parameter from the item's provider templates), with type, description, default, sensitivity, and any enum choices. It also returns `interface-error`, `null` unless the module version's interface could not be read — in which case the form may be missing variables the module needs, and the reason says why. **Required permission:** catalog `read`.

#### Module Interface

```
GET /api/v1/catalog-items/{id}/interface
```

The inputs and outputs of the module version the item resolves to — its `default-version-pin`, or the latest uploaded version — derived from the module registry rather than stored on the item. Returns `resolved-version`, `inputs[]` (`name`, `type`, `description`, `default`, `required`, `sensitive`) and `outputs[]` (`name`, `description`, `sensitive`): the same entries as the module registry's interface endpoint. Where `/form` is the curated provision view, this is the module's own surface, and the only place its outputs can be read. All three are `null` while the module has no uploaded version. `interface-error` is `null` unless the version's interface could not be read, when it carries the reason. **Required permission:** catalog `read`.

#### List Item Instances

```
GET /api/v1/catalog-items/{id}/instances
```

**Required permission:** catalog `read`.

#### Provision an Instance

```
POST /api/v1/catalog-items/{id}/provision
```

Creates a catalog-managed, agent-mode, non-VCS workspace, materialises the inputs as Terraform variables, generates the wrapper, and queues the first run (source `catalog`).

**Request body:**
```json
{
  "data": {
    "type": "catalog-instances",
    "attributes": {
      "name": "vpc-prod-us-east-1",
      "agent-pool-id": "apool-019e01db-...",
      "input-values": { "cidr_block": "10.20.0.0/16", "name": "prod", "aws_region": "us-east-1" },
      "version-pin": "1.4.0",
      "auto-apply": false,
      "labels": {"env": "prod"}
    }
  }
}
```

| Attribute | Required | Description |
|---|---|---|
| `name` | yes | Workspace/instance name. |
| `agent-pool-id` | yes | Pool the instance binds to. Caller must have pool `write`; pool must be in `allowed-agent-pool-ids` when the item restricts it. |
| `input-values` | yes | Values for the form fields (module inputs + provider-template parameters). |
| `version-pin` | no | Pin this instance to a module version. Omit to inherit the item's `default-version-pin` (or float when that is unset). |
| `auto-apply` | no | Auto-apply runs for this instance. |
| `labels` | no | Labels on the created workspace. |

**Required permission:** catalog `use` **and** pool `write`.

| Error | When |
|---|---|
| `403` | Caller lacks catalog `use`, lacks pool `write`, or the pool is not in the item's `allowed-agent-pool-ids`. |
| `409` | The item is disabled. |
| `422` | Missing required inputs, or unknown input keys. |

Returns `201` with the created `catalog-instance` (the instance id is the workspace id).

### Catalog Instances

A provisioned instance, addressed by its workspace id (`wsId`).

#### Show Instance

```
GET /api/v1/catalog-instances/{wsId}
```

**Required permission:** catalog `read`.

#### Reconfigure Instance

```
PATCH /api/v1/catalog-instances/{wsId}
```

Update the instance's inputs and/or version pin, regenerate the wrapper, and queue a new run (source `catalog`). This is the only supported way to change a catalog instance's configuration — direct configuration-version uploads and custom-CV runs on a catalog-managed workspace are rejected with `409`.

**Request body:**
```json
{
  "data": {
    "type": "catalog-instances",
    "attributes": {
      "input-values": { "cidr_block": "10.20.0.0/16" },
      "version-pin": null,
      "auto-apply": true
    }
  }
}
```

| Attribute | Description |
|---|---|
| `input-values` | Partial or full input update. |
| `version-pin` | New pin, or `null` to **float** (track latest published module version). |
| `auto-apply` | Toggle auto-apply for this instance. |

Returns a reference to the queued run. **Required permission:** catalog `use`.

#### Destroy Instance

```
POST /api/v1/catalog-instances/{wsId}/destroy
```

Queues an `is_destroy` run with source **`catalog-lifecycle`**. On a **successful apply** of that run the workspace is **archived** (soft delete — state is retained). Nothing is hard-deleted.

**Request body** (optional):
```json
{ "data": { "type": "catalog-instances", "attributes": { "auto-apply": true } } }
```

Returns a reference to the queued destroy run. **Required permission:** catalog `use`.

> **Run sources:** catalog runs carry `source = "catalog"` (provision / reconfigure) or `source = "catalog-lifecycle"` (destroy → archive). These appear on the run object alongside the existing sources (`tfe-api`, `vcs`, `run-trigger`, `drift-detection`, `autodiscovery-lifecycle`, `module-test`, `module-publish`, `onboarding-discovery`).

### Confirm / Discard a Catalog Instance Run

```
POST /api/v1/catalog-instances/{wsId}/confirm
POST /api/v1/catalog-instances/{wsId}/discard
```

Confirm (apply) or discard the instance's pending **planned** run. These are the catalog-surface counterparts of the workspace run API: the catalog-managed workspace clamp gives the provisioner only `read` on the workspace, so a non-auto-apply provision / reconfigure / destroy is confirmed here rather than via `/api/tfe/v2/runs/{id}/actions/confirm` (which would require a platform admin). Returns the run reference. `409` if there's no planned run awaiting action. **Required permission:** catalog `use`.

### Orphan Catalog Instance (discouraged)

```
DELETE /api/v1/catalog-instances/{wsId}?orphan=true
```

Deletes the catalog instance's workspace record **without** destroying its infrastructure — the provisioned resources keep running, untracked. This is the explicit, **discouraged** escape hatch; the recommended teardown is `POST .../destroy`, which reclaims the infrastructure. The `orphan=true` flag is **required** — without it the call returns **409** and points at destroy, so an instance can never be orphaned by accident. The plain `DELETE /workspaces/{id}` also returns **409** for a catalog-managed workspace. **Required permission:** catalog `admin`. Audit-logged. Returns `204`.

---

## Ansible Inventory

A workspace carries **one inventory**, made of the structures ansible's inventory has: hosts, groups, the memberships between them, the nestings between groups, and variables on a host, on a group or inventory-wide. Each is its own addressable resource. Terrapod stores and renders them; **`ansible-inventory` performs the merge**, the precedence, the group DAG, the derivation of `all` and `ungrouped`, and the expansion of `--limit`. See [Ansible Inventory](ansible-inventory.md) for the model, the two sources and the declaration patterns.

**Native surface only** — nothing here is on the TFE-compatible prefix, because no `terraform`, `tofu` or `tfci` invocation consumes it. The canonical prefix is `/api/v1`; `/api/terrapod/v1` is the deprecated alias and serves every route below.

Two capabilities gate it, both in the workspace axis: **`inventory:read`** (read tier) for every read, and **`inventory:write`** (write tier — deliberately not admin, because the Terraform that declares a host runs under an apply) for every write. A **runner token** is handled separately: it may manage the inventory of **its own run's workspace** and nothing else, reads unphased and writes bound to the **apply** phase.

**Configure operations do not exist yet.** These endpoints build an inventory and make it observable; they do not run playbooks.

Typed id prefixes: `invhost-` (host), `invgroup-` (group), `invhg-` (host membership), `invgc-` (group nesting), `invhvar-` (host variable), `invgvar-` (group variable), `invvar-` (inventory variable). The inventory's roots and defaults are **workspace attributes** rather than a resource here — see [The configure-operation attributes](#the-configure-operation-attributes).

Common statuses across every write here: **409** on a duplicate (a second host of the same name in the workspace, a second variable with the same key on the same parent, a membership or nesting that already exists) — which is what makes a Terraform import the next step; **422** on a parent that is absent or in another workspace, on a name ansible cannot use, and on a ceiling, with the limit named in the message.

### List / Create Inventory Hosts

```
GET  /api/v1/workspaces/{id}/inventory/hosts
POST /api/v1/workspaces/{id}/inventory/hosts
```

`GET` requires `inventory:read`, is ordered by name, and supports the standard `page[number]` / `page[size]`. Unphased for a runner token — a plan reads the inventory to diff it. `POST` requires `inventory:write` (apply phase for a runner token) and returns `201`.

```json
{"data": {"type": "inventory-hosts", "attributes": {"name": "web-01"}}}
```

| Attribute | Meaning |
|---|---|
| `name` | Required. Ansible's `inventory_hostname`. Refused with `422` if it contains whitespace or any of `,`, `:`, `!`, `&`, `~` — those are `--limit`'s own operators and separators, so such a host cannot be targeted and a leading `!` would silently exclude the host it names. Dots, hyphens and underscores are fine |

**A host has no other field.** There is no `address`: `ansible_host` is a variable like any other, because that is what it is to ansible.

A read carries `group-count` and `variable-count` rather than the rows themselves — a list view shows "3 groups, 2 variables", and embedding either would make one request grow with the whole inventory. The rows are one drill-down away.

### Show / Update / Delete Inventory Host

```
GET    /api/v1/inventory-hosts/{id}
PATCH  /api/v1/inventory-hosts/{id}
DELETE /api/v1/inventory-hosts/{id}
```

`GET` requires `inventory:read`; `PATCH` and `DELETE` require `inventory:write` (apply phase for a runner token). `DELETE` returns `204`, and the host's memberships and variables go with it — the database's own cascade.

`PATCH` renames: `name` is the only mutable field a host has.

### List / Create Inventory Groups

```
GET  /api/v1/workspaces/{id}/inventory/groups
POST /api/v1/workspaces/{id}/inventory/groups
```

Same gating and paging as hosts. `POST` returns `201`.

```json
{"data": {"type": "inventory-groups", "attributes": {"name": "web"}}}
```

| Attribute | Meaning |
|---|---|
| `name` | Required. Must start with a letter or underscore and contain only letters, digits and underscores — `422` otherwise, because a name ansible merely warns about cannot be used reliably in a `--limit` pattern or as a `group_vars` filename. **`all` and `ungrouped` are refused**: ansible derives both, and the rendered inventory document is rooted at `all:`, so a declared group of that name would collide with the document's own structure. For variables that apply to every host, use the inventory variables below — that is ansible's `group_vars/all` |

A read carries `member-count`, `child-count` and `variable-count`.

### Show / Update / Delete Inventory Group

```
GET    /api/v1/inventory-groups/{id}
PATCH  /api/v1/inventory-groups/{id}
DELETE /api/v1/inventory-groups/{id}
```

As for a host: `PATCH` renames, `DELETE` returns `204` and takes the group's memberships, nestings and variables with it.

### Host memberships

```
GET  /api/v1/inventory-groups/{id}/hosts
GET  /api/v1/inventory-hosts/{id}/groups
POST /api/v1/inventory-groups/{id}/hosts
POST /api/v1/inventory-hosts/{id}/groups
GET    /api/v1/inventory-host-groups/{id}
DELETE /api/v1/inventory-host-groups/{id}
```

One `[groupname]` line, many-to-many, and its own row rather than a list on either side — so a membership has an id a Terraform resource can address, and two concerns can each put their own hosts in a shared group without owning it.

**Both sides can create one, and the result is identical.** A loop over a group's intended members wants the group route; a loop over a host's groups wants the host route; forcing either to invert its loop buys nothing. The row, the constraint and the response are the same.

The other end is a **relationship**, not an `*-id` attribute, because it is a link:

```json
POST /api/v1/inventory-groups/invgroup-.../hosts

{"data": {"relationships": {
  "host": {"data": {"id": "invhost-...", "type": "inventory-hosts"}}}}}
```

`POST` returns `201`; `DELETE` returns `204`. A host in another workspace is a `422` from the composite foreign key rather than a check the API performs first — the constraint answers both "does it exist" and "is it ours", and a `SELECT` first would be check-then-act.

### Group nestings

```
GET  /api/v1/inventory-groups/{id}/children
GET  /api/v1/inventory-groups/{id}/parents
POST /api/v1/inventory-groups/{id}/children
POST /api/v1/inventory-groups/{id}/parents
GET    /api/v1/inventory-group-children/{id}
DELETE /api/v1/inventory-group-children/{id}
```

One `[groupname:children]` entry. Many-to-many too — **a group may have several parents**, which ansible allows — so the same symmetry applies: `…/children` names the child, `…/parents` names the parent, and both create the same row.

```json
POST /api/v1/inventory-groups/invgroup-PARENT/children

{"data": {"relationships": {
  "child-group": {"data": {"id": "invgroup-...", "type": "inventory-groups"}}}}}
```

A nesting that would close a **cycle** is refused with `422`. The one-step case is a database constraint; a longer one is checked before the write, because a constraint cannot walk a graph.

### Variables

```
GET  /api/v1/inventory-hosts/{id}/vars
POST /api/v1/inventory-hosts/{id}/vars
GET    /api/v1/inventory-host-vars/{id}
PATCH  /api/v1/inventory-host-vars/{id}
DELETE /api/v1/inventory-host-vars/{id}

GET  /api/v1/inventory-groups/{id}/vars
POST /api/v1/inventory-groups/{id}/vars
GET    /api/v1/inventory-group-vars/{id}
PATCH  /api/v1/inventory-group-vars/{id}
DELETE /api/v1/inventory-group-vars/{id}

GET  /api/v1/workspaces/{id}/inventory/vars
POST /api/v1/workspaces/{id}/inventory/vars
GET    /api/v1/inventory-global-vars/{id}
PATCH  /api/v1/inventory-global-vars/{id}
DELETE /api/v1/inventory-global-vars/{id}
```

Three surfaces, one shape: a host's `host_vars`, a group's `group_vars`, and the inventory's `group_vars/all`. **The inventory variables are parented on the workspace rather than on a group**, because `all` cannot be a declared group name — they land at the rendered document's root `vars:`, which is the consequence of that refusal rather than a way round it.

Each variable is a row with **one writer**, which is the point of the shape: a second concern can contribute a variable to a host or group it does not own.

```json
{
  "data": {
    "type": "inventory-host-vars",
    "attributes": {
      "key": "ansible_host",
      "value": "10.0.0.5",
      "structured": false,
      "sensitive": false
    }
  }
}
```

| Attribute | Meaning |
|---|---|
| `key` | Required. Unique per parent (`409` otherwise). Only has to be a non-empty string with no leading or trailing whitespace — deliberately laxer than a group name, because ansible stores a non-identifier variable and only warns that it is unreachable as a bare `{{ name }}`, while it is still readable through `hostvars`, which some roles do on purpose |
| `value` | The value. **A `sensitive` value reads back as a fixed mask**, never its own length or shape |
| `structured` | Whether `value` is a typed expression rather than a plain string — a list, a number, a nested object, which is what ansible's own `group_vars` carries natively. Parsed as YAML, so both `[80, 443]` and a block sequence work. Default `false` |
| `sensitive` | A **display** flag: it decides what a reader sees, not what the database holds. All three surfaces are registered for Terrapod's [app-layer encryption](encryption-at-rest.md), so where a deployment has that enabled every value is enveloped whatever this flag says. Default `false` |

`POST` returns `201`; `DELETE` returns `204`. `PATCH` changes `value`, `structured` and `sensitive`.

Every list route in this section supports the standard `page[number]` / `page[size]` and returns `meta.pagination`. Hosts and groups are ordered by name, variables by key, and memberships and nestings by when they were created.

### Show Resolved Inventory

```
GET /api/v1/workspaces/{id}/inventory/resolved[?limit=<pattern>]
```

Requires `inventory:read`; unphased for a runner token. **Resolved by ansible, not by Terrapod** — `ansible-inventory --list` does the merge, the precedence, the group DAG, the derivation of `all` and `ungrouped`, and with `?limit=` the expansion of a `--limit` pattern, so the answer is ansible's own, `~regex` terms included.

**It is live, and it writes nothing.** Every source is static — dynamic inventory was declined ([#1970](https://github.com/mattrobinsonsre/terrapod/issues/1970), closed as not-planned) — so the resolution is a function of the rows and the resolved commit. A Redis entry backs it and is keyed on their content, so a write supersedes it rather than needing an invalidation: there is no timestamp, no freshness field and no refresh action, because there is no other resolution the answer could be.

```json
{
  "data": {
    "id": "ws-...",
    "type": "resolved-inventories",
    "attributes": {
      "hosts": {
        "web-01": {"ansible_host": "10.0.0.5", "ansible_user": "deploy"},
        "web-02": {"ansible_host": "10.0.0.6"}
      },
      "groups": {"web": ["web-01", "web-02"], "eu": []},
      "group-children": {"eu": ["web"]},
      "host-count": 2,
      "group-count": 2
    }
  }
}
```

| Attribute | Meaning |
|---|---|
| `hosts` | Every host, with its merged variables. A host with no variables is present with an empty object |
| `groups` | Each group's **direct** membership. Ansible does not flatten nesting into a group's host list, so a parent whose members all arrive through a child reports none of its own — `eu` above is the example. **Do not read an empty list as "this group targets nothing"** |
| `group-children` | The nesting, carried rather than resolved. Taking the transitive closure would be Terrapod computing the group DAG, which is ansible's job |
| `host-count`, `group-count` | The sizes of the two maps above |
| `limit` | Echoed back when `?limit=` was supplied |

**`?limit=<pattern>` is the authoritative "what would this target"**, and it is the one that expands **through** nesting — so it, not a group's host list, is how the effective set of a parent group is read. The pattern goes straight to `ansible-inventory --limit`: host names, group names, `all` and `*`, globs, comma- or colon-separated terms, `!` exclusion, `&` intersection, and `~regex`.

This is the safety surface rather than a convenience: auto-configure is deliberately broad — at scale the hazard is hosts left unconfigured, not hosts configured — so visibility is the control, and the question has to be answerable before anything runs.

Statuses worth knowing, because the three say different things:

| Status | Meaning |
|---|---|
| `422` | A fetched source was **declined**: a file whose top level carries a `plugin:` key is an inventory plugin configuration, and Terrapod does not run inventory plugins. The message names the file and the plugin it asks for. The resolution did not fail — there is something to do about it |
| `503` | The resolution could not be performed: a repository that cannot be fetched, a branch that is gone, a source ansible cannot parse, or `ansible-core` missing from the API image (it is baked in, so this means a broken image rather than anything an operator can configure). **It fails closed** rather than degrading into a partial host list, because a silently short target set is the failure mode this whole surface exists to prevent |
| `200` with empty maps | A workspace that has declared nothing and bound no repository. A defined empty result, not an error |

## Ansible execution environments

Which images this deployment can run a configure operation in (#2154). See
[Choosing an execution environment](runners.md#choosing-an-execution-environment).

### `GET /api/v1/ansible/execution-environments`

Any authenticated user. The answer is which images this deployment can pull,
which every workspace editor needs and which discloses nothing an operator's own
Helm values do not.

Both kinds come back from one route, tagged, because the precedence between them
is not symmetric: an operator label overrides a workspace's ansible-core line.

```json
{"data": [
   {"type": "ansible-execution-environments", "id": "2.21",
    "attributes": {"kind": "built-in", "ansible-core-line": "2.21",
                   "label": null,
                   "image": "ghcr.io/mattrobinsonsre/terrapod-ee:2.21"}},
   {"type": "ansible-execution-environments", "id": "rhel8-hardened",
    "attributes": {"kind": "operator", "ansible-core-line": null,
                   "label": "rhel8-hardened",
                   "image": "registry.internal/platform/ee-rhel8:2026.10"}}
 ],
 "meta": {"listing": "complete",
          "pagination": {"current-page": 1, "page-size": 2,
                         "total-count": 2, "total-pages": 1}}}
```

`image` is resolved by the same resolver the run path uses, so what this returns
cannot drift from what actually executes.

**`meta.listing` must be read before concluding anything from an empty `data`.**

| `listing` | meaning |
|---|---|
| `complete` | the registry answered. A line that is absent does not exist, and [`ansible-version`](#ansible-version) naming it is refused with a 422 |
| `unknown` | the set could not be determined — an unreachable registry, a listing truncated by pagination, a sealed deployment's upstream being off limits. **Any** line is then accepted on a write, because refusing one Terrapod cannot confirm would make an ordinary workspace edit depend on registry reachability |

So an empty `data` with `complete` is a real answer — this deployment publishes
nothing and every line will be refused. An empty `data` with `unknown` means
nothing at all, and a client offering a picker should let someone type a line
rather than presenting an empty list. Operator-supplied entries are
authoritative in both states: they come from configuration, not from a registry.

A string rather than a boolean because the next state this may need is
`partial` — a listing trusted for one source and not another — and a boolean
would have to be deprecated to say it.

## High Availability

Leader/follower pair endpoints (#960). See [High availability](high-availability.md).

### `GET /api/v1/ha/whoami`

**Unauthenticated by necessity** — this is what a node probes against the shared
DNS name to discover whether it owns that name, and the probe runs before any
trust exists between the two nodes. It discloses only an operator-chosen node
name and a role. `Cache-Control: no-store`, so a CDN or WAF in front of the
external name cannot pin leadership to a stale answer.

```json
{"data": {"type": "ha-nodes", "id": "node-a",
          "attributes": {"node-id": "node-a", "role": "leader"}}}
```

> **The replication surface is inert until peering is declared.** With neither
> `ha.peer.url` nor `ha.peer.inbound.client_id` set, no peer token is issued and
> none is accepted, so `/ha/replication/*` refuses every request with 401 —
> including one bearing a credential left behind by a pairing that was torn down.
> Withdrawing the configuration withdraws the capability.

### `GET /api/v1/ha/status`

**Requires authentication; the in-cluster half additionally requires `admin` or
`audit`.** Whether this node is converging with its peer — the question to
answer before moving DNS. Computed entirely from local state, so it still works
when the peer is the thing that has broken.

The node's own disposition (role, peer, sync state) is readable by **any
authenticated user**: hiding "you are talking to a follower" from the person
whose next write is about to be refused with a 503 is the opposite of useful.

| Attribute | Meaning |
|---|---|
| `role`, `node-id` | This node's identity and current role |
| `peer-configured` | False on an ordinary single node; the rest then does not apply |
| `replication-enabled` | Whether this node pulls from a peer |
| `in-sync` | **The summary.** True only when a pull has succeeded *and* no class is mid-backfill |
| `last-sync-at`, `seconds-since-last-sync` | The last successful pull. Null when it has never synced |
| `backfilling-classes` | Classes still being pulled in full. **Non-empty means not in sync**, however recent the last pull |
| `events-retained`, `oldest-event-age-seconds` | Leader side: as the oldest event approaches `retention-seconds`, the follower is close to having to backfill from scratch |
| `retention-seconds` | The retained event window |
| `events-behind` | How many events outstanding as of the last successful pull. **`null` is unknown** (never pulled, or a peer that does not report it) and is NOT the same as `0`, which means caught up |
| `behind-seconds` | How old the oldest un-applied change was at that same pull. Null when caught up or unknown |
| `replicated-classes` | What a failover would carry |

`events-behind` needs the peer's latest event id, which the follower cannot
derive alone — its page is capped at the batch size, so a full page means "there
is more" and nothing about how much more. The leader therefore reports its
newest event id (and the timestamp of the oldest event in the page) on every
events response, and the follower stores both alongside its cursor. Both figures
describe **the last successful pull**, not this instant — pair them with
`seconds-since-last-sync` to know how old the answer is.

The same response also reports this node's **in-cluster** HA posture, because a
pair that replicates flawlessly is still not highly available if it is serving
from one API pod:

| Attribute | Meaning |
|---|---|
| `components-restricted` | True when the caller lacks `admin`/`audit`. The component fields below are then empty because they were **not read**, which is deliberately distinct from `components-unavailable-reason` ("the cluster could not be read") and from an empty list ("nothing is running") |
| `components` | Per component: `ready` and `desired` replicas, the `nodes` and `zones` they occupy, and the PodDisruptionBudget covering them. API and web come from Kubernetes; listeners come from their Redis heartbeats, since a listener may be in another cluster entirely |
| `single-replica-components` | Components on exactly one ready replica |
| `schedulable-nodes`, `cluster-zones` | The spread that *was* available. Null when the node read is declined or the environment is unzoned — null means unknown, never one |
| `ha-findings` | Named gaps: `no-pdb`, `pdb-blocks-eviction`, `node-concentration`, `zone-concentration`, `single-zone-cluster`. Each carries the component and a human-readable detail |
| `components-unavailable-reason` | Set when the namespace could not be read. An empty `components` with a reason set means *"I cannot see"*, never *"nothing is running"* |

**An empty `ha-findings` means nothing avoidable was found — not that nothing
was checked.** A finding is only raised where the cluster could have done
better: a single-node cluster cannot spread replicas and a single-zone one
cannot spread zones, so neither is reported as a gap. See
[High availability](high-availability.md#findings-disruption-budgets-and-placement).

### `GET /api/v1/ha/blob-readiness`

**Requires `admin` or `audit`.** Are the objects this node's rows name actually in
its object store? Replication carries database rows; the object store is a second
data plane, and **rows present with blobs absent** is a node that looks healthy
and cannot serve a single run.

| Query | Default | Meaning |
|---|---|---|
| `full` | `false` | Check every row of every class. Thousands of round trips on a real estate, hence opt-in |
| `sample` | `25` | Newest rows per class when not running full |

| Attribute | Meaning |
|---|---|
| `irreplaceable-missing` | **The list that should stop a failover** — classes whose absence is permanent |
| `irreplaceable-unchecked` | Irreplaceable classes this run made **no claim about** — switched off, or not verifiable from rows. What makes the list above trustworthy |
| `missing-total` | Missing objects among those **checked** |
| `sampled` | Whether this was a sample rather than a full verification |
| `classes[]` | Per class: `name`, `tier` (`irreplaceable`\|`history`\|`rederivable`), `mode` (`off`\|`verify`\|`copy`), `verifiable`, `note`, `total-rows`, `checked`, `missing`, `missing-examples` (capped), `complete`, `error` |
| `unavailable-reason` | Set when the store could not be read — *"I could not look"*, distinct from *"all is well"* |
| `duration-ms` | What the check cost |

**A clean sample is not a clean estate.** `complete` is true only when nothing was
held back; otherwise compare `checked` against `total-rows`. `missing == 0` on a
sample means *no missing objects among those sampled*.

**Nor is a clean report a covered store.** `mode` reflects `ha.blobs` — a class set
to `off` is reported with `checked: 0` and a `note` saying so, never omitted.
`verifiable: false` marks a class no database row guarantees (a run's logs exist
only if it got that far; a pull-through cache holds whatever it holds), so presence
cannot be derived and the report says as much instead of implying a pass.
`irreplaceable-unchecked` names any of those that matter.

**`tier` is the effective tier for this deployment.** On a sealed
(`registry.cache_only`) node the upstream-fed caches report as `irreplaceable`,
because a promoted node with a cold cache cannot reach upstream to re-warm and so
can never run anything. Terrapod derives that rather than asking an operator to
restate it.

Deliberately **not** folded into `/ha/status`: that endpoint is answered from local
state in milliseconds and is refreshed freely, while this one does real
object-store I/O.

See [High availability](high-availability.md#the-other-data-plane-is-the-object-store-actually-there).

### Peer-only endpoints

`GET /api/v1/ha/replication/blobs/{class}` lists an object-store class's
objects (key, size, etag) in key order with `after`/`limit` paging, and
`GET .../blobs/{class}/content?key=…` streams one object. Both are how a follower
copies the object store (see [High availability](high-availability.md#choosing-verify-or-copy-per-class)).

Two properties worth knowing if you are reading the code: the key is checked
against the class that **owns** it before a byte is served — a peer token reads
more than a user's, so this must not become an arbitrary-read primitive — and
`meta.cursor`/`meta.complete` are derived from what the *store* returned, not from
what survived the ownership filter, so a page thinned by the filter is a short
page rather than the end of the class.

`/api/v1/ha/replication/*` are consumed **by the peer node**, not by
users or tooling. They accept a `peer` token and nothing else, and no other
endpoint accepts one — a peer can read entities an ordinary user cannot, so that
visibility is deliberately not expressible as roles somebody could be granted.

## Deleted Workspaces (undelete)

Deleting a workspace removes its rows but not its state blobs. A delete marker
written at delete time keeps that state findable and gives the retention reaper
something to age; these endpoints are how an operator sees and recovers it.

The window is finite — once a marker is older than
`api.config.artifact_retention.deleted_workspace_retention_days` (default 30)
the state is reaped and the workspace is gone for good. Set the value to `0` to
disable reaping entirely.

**Platform admin only, on every route including the reads.** A marker names a
workspace, its labels and its variable names, and a restore materialises its
state — and therefore its secrets — into a workspace the caller can then read.
The original workspace's ACL died with its rows, so there is nothing to
delegate to; it fails closed to admin.

### List Deleted Workspaces

```
GET /api/v1/deleted-workspaces
```

Newest deletion first. Supports the standard `page[number]` / `page[size]`.

Notable attributes:

| Attribute | Meaning |
|---|---|
| `marker-reason` | `deleted` — written by the delete, so `deleted-at` is the true deletion time. `discovered-orphaned` — the reaper found state with no marker (deleted before this feature shipped, or the marker write failed), so `deleted-at` is when it was first seen |
| `state-versions-available` | Counted from storage at request time, not taken from the marker — a partial reap or an incomplete replication shows up here and nowhere else |
| `restorable-until` | When the state becomes eligible for reaping. Empty when retention is disabled |
| `workspace-id` | The deleted workspace's id — also the resource `id`. Accepted bare or `ws-`-prefixed on the routes below |
| `workspace-name` | Its name at delete time. `null` on a reaper-discovered marker, which has no name to record |
| `deleted-at` / `deleted-by` | When, and by whom. On a `discovered-orphaned` marker `deleted-at` is when the reaper first *saw* it, not when it was deleted |
| `age-days` | Days since `deleted-at`, rounded — what the retention window is measured against |
| `last-serial` / `lineage` | The state's serial and lineage at delete time, so you can tell which workspace's state this is before restoring |
| `settings` | The workspace's non-secret configuration snapshot (labels, owner, execution mode, VCS reference, …), used to rebuild it |
| `restored-to` | Workspace ids this deletion has already been restored into; empty until the first restore. Check it before offering a restore — a repeat would produce a second live workspace over the same infrastructure |
| `restored-at` / `restored-by` | When and by whom the most recent restore happened |
| `variable-names` | Names and categories only. Values are **never** recorded: the marker is a plain object in the bucket and replicates to any standby |

### Show Deleted Workspace

```
GET /api/v1/deleted-workspaces/{workspace_id}
```

`{workspace_id}` is accepted both bare (`0192f3a1-…`, as the list emits it) and
`ws-`-prefixed, on this route and on the restore below.

### Restore a Deleted Workspace

```
POST /api/v1/deleted-workspaces/{workspace_id}/restore
```

Optional body: `{"data": {"attributes": {"name": "...", "force": false}}}`.

`name` — when omitted the original is reused, suffixed if it has been taken
since. It must meet the same format contract as any other workspace name
(start with a letter or number; letters, numbers, hyphens and underscores; 90
characters or fewer), because the name is what the `cloud {}` block matches on
and what `/app/{org}/{name}` redirects by. A name that came from the marker
rather than the caller is sanitized instead of rejected, so a hand-edited
marker cannot make a recoverable workspace un-restorable.

`force` — permits restoring a deletion that has already been restored. Without
it the request is refused; see below.

This creates a **new workspace with a new id** and copies the state history
into it. It is not an in-place revival, and that is deliberate: re-attaching
the original id would need no copy at all and would make deletion a
one-keystroke mistake to undo, which makes deletion feel free. Recovery is an
explicit operation that yields a visibly new workspace.

Three properties worth knowing before you call it:

- **Lineage and serial are preserved exactly**, recovered from inside the state
  documents. This is the hard correctness constraint — a fresh lineage would
  make the next apply fail on a mismatch, or treat live infrastructure as
  unmanaged.
- **It comes back inert.** Auto-apply and drift detection are forced off and the
  VCS connection is not re-attached, whatever the snapshot said. A restored
  workspace that applied immediately, against infrastructure that may have
  drifted or been partly torn down since the delete, is the failure this
  prevents. The response's `suppressed` list says what to re-enable.
- **Dangling references are dropped, not re-attached.** A recorded VCS
  connection id may since have been reused by a different connection; the
  response reports it in `dropped-references` rather than binding to it.

- **Only the newest state versions are copied**, bounded by
  `api.config.artifact_retention.state_versions_keep`. Anything beyond the cap
  is listed in `state-versions-skipped` with a reason rather than dropped
  silently. Without a bound, one request walks every version ever written
  through the API pod — decrypt, re-encrypt, put, per document, inside a single
  open transaction — and a large state exhausts the ingress timeout long before
  it finishes.
- **A deletion is restored once.** A repeat would create a *second* live
  workspace holding the same state lineage over the same real infrastructure,
  after which an apply in either makes the other's next plan read as wholesale
  drift. The second attempt is refused with a `409` naming the workspace that
  already exists. Pass `force` only when that earlier restore is known to be
  gone.

Response attributes:

| Attribute | Meaning |
|---|---|
| `name` | The new workspace's name — the original if free, suffixed if taken, or the one you supplied |
| `restored-from` | The deleted workspace's id, so the provenance is on the record |
| `state-versions-restored` | How many were copied |
| `state-versions-skipped` | Each with a `key` and a `reason` — unreadable blob, duplicate serial, or beyond the version cap. **A partial-failure signal**: a caller that ignores it can believe it recovered history it did not |
| `suppressed` | Settings forced off (`auto_apply`, `drift_detection_enabled`, `auto_merge`, `vcs_connection`) — what to re-enable deliberately. **What each one *was* is on the deleted workspace's `settings`**, which the list and show endpoints return: `auto_apply` is only a boolean projection, so a workspace held at `create` or `create_update` reads `auto_apply_mode` there to put the same guardrail back rather than re-enabling it as `always` |
| `dropped-references` | Things pointing at other resources that were not re-attached, e.g. a VCS connection whose id may since have been reused |

The source prefix and its marker are left untouched, so the original remains
recoverable until its window expires.

| Code | Meaning |
|---|---|
| `201` | Restored. The body carries the new workspace id and the suppression report |
| `403` | Not a platform admin |
| `404` | No delete marker for that id |
| `409` | Either no state could be recovered (already reaped) or this deletion has already been restored. Nothing is created; an empty restore is reported as a failure rather than handing back a bare workspace |
| `422` | The supplied `name` does not meet the workspace name format |

## Common Response Codes

| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 204 | Deleted (no content) |
| 302 | Redirect (presigned URLs, binary cache, artifact downloads, OAuth flows) |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (missing or invalid token) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not found |
| 409 | Conflict (lock conflict, duplicate resource, label change would reduce your access) |
| 422 | Unprocessable entity (semantic validation error) |
| 503 | Service unavailable (readiness check failed) |