API
The server exposes one JSON API for three callers: runners, people and automation. All request and response bodies are the types in the Go package github.com/stackorder/stackorder/api/v1, which automation can import to decode responses.
Fields are only ever added within v1. Clients must ignore fields they do not know. Fields that are empty are left out of responses, except where a table below says otherwise.
Conventions
- Bodies are JSON. A request with a body must send
Content-Type: application/json(or no content type), one JSON value and nothing after it. Unknown request fields are ignored. - Times are RFC 3339 in UTC, such as
2026-09-28T09:14:03Z. - Run, stack and module ids are UUIDs. Repository and installation ids are GitHub's numeric ids.
- Stack keys in paths are percent-encoded, so slashes become
%2F:POST /v1/runs/{id}/stacks/stacks%2Fprod%2Fvpc/result. - Every response carries
X-Request-Id, echoing a valid incoming one or a new UUID. JSON responses carryCache-Control: no-store. - Unknown paths under
/v1/and/auth/answer a JSON404 not_found. Every other unknown path serves the embedded web UI, with a fallback to itsindex.html.
Lists
List endpoints take ?limit= and ?cursor= and return a page:
{
"items": [],
"next_cursor": "c3RhY2tzL3Byb2QvdnBj",
"total": 42
}| Parameter | Default | Meaning |
|---|---|---|
limit | 50 | Items per page, a positive integer; values above 500 are treated as 500. |
cursor | first page | The next_cursor of the previous page, opaque. A malformed cursor is 400 invalid with details.field cursor. |
next_cursor is absent on the last page. total counts every item across pages and is present only on GET /v1/repos, GET /v1/repos/{owner}/{repo}/stacks, GET /v1/stacks and, for API keys, GET /v1/modules, and only when it is not zero. Pages of GET /v1/audit and GET /v1/modules may hold fewer than limit items, or none, and still carry next_cursor, because entries the caller may not see are removed after paging.
Authentication
| Caller | Credential | Sees |
|---|---|---|
| Runner | Authorization: Bearer <GitHub Actions OIDC token> | Its own repository |
| Automation | Authorization: Bearer sk_<key> | Every repository, unless the key is scoped; an unscoped key is an administrator |
| Person | The stackorder_session cookie, set by GitHub sign-in | Repositories whose installation account is one of the person's organisations, or their own login |
Runners never hold a shared secret: the token is the job's own OIDC token. A runner token is accepted only once, so the CLI requests a fresh one for every call. See OIDC binding. API keys are created by an operator; see API keys.
Anything a caller may not see answers 404 not_found, as if it did not exist. State-changing requests made with the session cookie (unlock, re-run, sign-out) must also come from the server's own origin: Origin must equal the origin of STACKORDER_BASE_URL, or, without Origin, Sec-Fetch-Site must be same-origin; otherwise they are 403 forbidden. API keys are exempt. A 401 response carries WWW-Authenticate: Bearer realm="stackorder".
API key scopes
An API key is an unscoped administrator by default. Creating a key may narrow it three independent ways:
- Read-only (
read_only). The key is refused every mutating route — any request whose method is notGET— with403 forbidden. It may still read anything its installation scope allows. Starting a manual run, uploading a graph, reporting a result, unlocking, re-running and managing keys are all refused. - Installation-scoped (
installation_id). The key sees only the one installation and nothing of any other: repository and stack lists, overview counts, runs, plan text, shared outputs, resources and the audit log are all filtered, and a repository, run or stack of another installation answers404 not_foundexactly as one that does not exist, with no403-versus-404difference to probe. A key whose installation is later uninstalled sees nothing. - Expiring (
expires_at). After that time the key stops authenticating and is refused exactly like a revoked one (401 unauthorized). Expiry is checked on every request.
A scoped key is not an administrator: it can neither list, create nor revoke keys, so it can never mint itself a broader key. Only an unscoped (read-write, installation-wide) key that does not expire manages keys; an expiring key, even one otherwise unscoped, cannot create keys, so it cannot outlive itself by minting a permanent one.
All three scopes are enforced only by a server on v0.6.0 or later. A v0.5.0 replica honours any key as a full, never-expiring administrator, so during a rolling upgrade do not issue or distribute a scoped or expiring key until every replica runs v0.6.0 or later, and revoke such keys before rolling back. See Upgrades and backups.
Errors
Every error response has the same body. details is present only for the codes that define it.
{
"code": "locked",
"message": "stacks/prod/vpc is locked by pull request 41",
"details": {
"conflicts": [
{
"stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"stack_key": "stacks/prod/vpc",
"run_id": "5b8e1f2a-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"pr_number": 41,
"taken_at": "2026-09-27T16:02:11Z"
}
]
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid | The body or a parameter failed validation. details.field and details.reason name the field when one is at fault. A JSON value of the wrong type names it by its path, without array indexes, such as resources.items.tainted. |
| 401 | unauthorized | Missing or unusable credentials: no token, a bad signature, the wrong audience or issuer, a token older than 10 minutes or already used, an unknown, revoked or expired API key, an expired session. |
| 403 | forbidden | Valid credentials that may not do this: a repository the server does not know, a suspended installation, a job_workflow_ref that does not match, a claim that does not match the run, a person without push permission, a cross-origin request. |
| 404 | not_found | The run, stack, module, repository or route does not exist or is not visible to the caller. |
| 409 | conflict | The request conflicts with the current state, such as a result for a stack that already finished. |
| 409 | refused | The apply gate refused. details.failures lists each failure as {"layer", "name", "reason", "stacks"}. |
| 409 | superseded | A newer commit replaced the run. |
| 413 | invalid | The body is larger than the route allows: 8 MB for a graph upload, 1 MB for every other POST under /v1 and /auth. |
| 422 | unprocessable | The server understood the request but cannot carry it out on what it read. |
| 423 | locked | A stack is locked by another pull request or run. details.conflicts lists the locks. |
| 500 | internal | An unexpected server error; the message is generic and the details are in the server log. |
| 503 | unavailable | GitHub's signing keys, GitHub itself, the database or a state object cannot be reached, or the server is in setup mode. |
A read of a stack's outputs answers codes of its own as well; see its errors.
The CLI maps these to exit codes.
Endpoints
| Method and path | Caller | Request | Response |
|---|---|---|---|
POST /v1/runs | Runner; API key for manual runs | CreateRunRequest | 201 or 200, CreateRunResponse |
POST /v1/runs/{id}/graph | Runner | GraphUploadRequest | ResolveResponse |
PUT /v1/repos/{owner}/{repo}/default-graph | Runner (push token) | RecordGraphRequest | RecordGraphResponse |
POST /v1/runs/{id}/stacks/{key}/result | Runner; API key for manual runs | StackResult | RunStack |
POST /v1/runs/{id}/stacks/{key}/checks/{name} | Runner; API key for manual runs | CheckVerdict | Check |
GET /v1/runs/{id} | Runner, person, API key | Run | |
GET /v1/repos/{owner}/{repo}/stacks/{key}/outputs | Runner, API key | ?run=&reader= | StackOutputs |
GET /v1/runs/{id}/stacks/{key}/plan | Person, API key | text/plain, the full plan text | |
POST /v1/runs/{id}/rerun | Person with push permission, API key | 201 or 200, CreateRunResponse | |
POST /v1/unlock | Person with push permission, API key | UnlockRequest | UnlockResponse |
POST /v1/stacks/{id}/unlock | Person with push permission, API key | UnlockRequest, optional | UnlockResponse |
GET /v1/me | Person, API key | Whoami | |
GET /v1/overview | Person, API key | Overview | |
GET /v1/repos | Person, API key | Page of RepoSummary | |
GET /v1/repos/{owner}/{repo}/graph | Person, API key | ?ref=&run= | GraphView |
GET /v1/repos/{owner}/{repo}/runs | Person, API key | ?status=&pr=&mode= | Page of Run |
GET /v1/repos/{owner}/{repo}/stacks | Person, API key | Page of StackDetail | |
GET /v1/stacks | Person, API key | Page of StackDetail | |
GET /v1/stacks/{id} | Person, API key | StackDetail | |
GET /v1/stacks/{id}/runs | Person, API key | Page of RunStackRef | |
GET /v1/stacks/{id}/resources | Person, API key | StackResources | |
GET /v1/modules | Person, API key | ?q= | Page of ModuleDetail |
GET /v1/modules/{id} | Person, API key | ModuleDetail | |
GET /v1/audit | Person, API key | Page of AuditEntry | |
GET /v1/keys | API key | APIKeyList | |
POST /v1/keys | API key | CreateAPIKeyRequest | 201, CreatedAPIKey |
DELETE /v1/keys/{id} | API key | APIKey | |
GET /auth/login | Browser | ?next= | 302 to GitHub |
GET /auth/callback | Browser, from GitHub | 302 to next, sets the session cookie | |
POST /auth/logout | Person | 204 | |
GET /setup | Browser, with the setup token | ?token=&org=&name=&force=1 | HTML, the App manifest form; 303 without token after checking it; 403 without the token |
GET /setup/callback | Browser, from GitHub | HTML, the App credentials, once | |
GET /setup/installed | Browser, from GitHub | HTML | |
GET /setup/logo.png | Browser | PNG, the logo to upload for the App | |
POST /webhooks/github | GitHub | Webhook payload | 202 |
GET /healthz | Load balancer | 200 | |
GET /readyz | Load balancer | 200 or 503 | |
GET /metrics | Prometheus | Prometheus text format |
Runner endpoints
POST /v1/runs
Finds or creates the run a job belongs to, and answers 201 for a new run or 200 for an existing one. What it does depends on the credential:
- A
pull_requesttoken registers the plan run of the pull request's head commit.modemust beplan(or empty),repomust be the token's repository,pr_numbermust matchrefs/pull/<n>/mergein the token'sref, andshamust be the pull request's current head, which the server reads from GitHub; an older head is409 superseded. A new run supersedes the plan runs of older heads of the same pull request. - A
workflow_dispatchtoken registers a job the server dispatched.run_idis required and names the existing run; the job is bound to its dispatch. - An API key starts a manual apply run, as
stackorder apply --localdoes.triggermust bemanual,modeapply,shaset andstacksnon-empty; the server takes the stacks' locks before it answers (423 lockedwhen one is held) and releases them when the results arrive.
A pull request plan job:
{
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"base_sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
"pr_number": 42,
"mode": "plan",
"trigger": "pull_request",
"workflow_run_id": 12345678901,
"workflow_run_attempt": 1
}A dispatched job:
{
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"mode": "apply",
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"workflow_run_id": 12345679999,
"workflow_run_attempt": 1
}A manual run:
{
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"mode": "apply",
"trigger": "manual",
"stacks": ["stacks/prod/vpc"]
}The response always embeds the run:
{
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "pending",
"existing": false,
"run": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"base_sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
"pr_number": 42,
"trigger": "pull_request",
"mode": "plan",
"status": "pending",
"requested_by": "octocat",
"created_at": "2026-09-28T09:13:58Z",
"waves": 0,
"current_wave": 0,
"html_url": "https://stackorder.example.com/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
}mode is plan, apply or drift. trigger is pull_request, comment, push, schedule, rerequest or manual.
POST /v1/runs/{id}/graph
Uploads the scanned graph and the changed paths, and answers with the affected stacks, their waves, warnings and the matrix. Only the resolve job of the pull request that created the run may upload, and only while the run is pending or planning; graph.repo and graph.sha must match the run. A tree_hash equal to that of a stored graph is a cache hit, reported as cached: true. The body limit is 8 MB.
{
"graph": {
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"tree_hash": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
"stacks": [
{
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"backend": {
"type": "s3",
"bucket": "acme-terraform-state",
"key": "stacks/prod/vpc/terraform.tfstate",
"region": "us-east-1",
"use_lockfile": true
},
"environment": "production",
"tool": "tofu",
"tool_version": "1.10.0",
"plan_output": "full"
},
{
"key": "stacks/prod/apps",
"path": "stacks/prod/apps",
"backend": {
"type": "s3",
"bucket": "acme-terraform-state",
"key": "stacks/prod/apps/terraform.tfstate",
"region": "us-east-1",
"use_lockfile": true
},
"environment": "production",
"tool": "tofu",
"tool_version": "1.10.0",
"plan_output": "full",
"config": { "depends_on": ["stacks/prod/vpc"] }
}
],
"modules": [
{
"key": "acme/infra//modules/vpc",
"kind": "local",
"path": "modules/vpc",
"source": "../../../modules/vpc"
}
],
"edges": [
{
"from": { "kind": "stack", "key": "stacks/prod/vpc" },
"to": { "kind": "module", "key": "acme/infra//modules/vpc" },
"type": "uses_module",
"meta": { "ref": "", "source": "../../../modules/vpc" }
},
{
"from": { "kind": "stack", "key": "stacks/prod/apps" },
"to": { "kind": "stack", "key": "stacks/prod/vpc" },
"type": "depends_on"
}
]
},
"changed_paths": ["modules/vpc/main.tf"],
"base_sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
"config": { "version": 1, "tool": "tofu" }
}The request may also carry a stacks list that restricts the run, as a stackorder plan stacks/a stacks/b comment does. Edges point from the dependent to what it depends on. An inferred edge has inferred: true; meta carries ref and source on uses_module edges, the matched bucket and key on reads_state edges inferred from terraform_remote_state, and source stackorder_outputs on those inferred from a stackorder_outputs block. A cross-repository depends_on target, or a stack of another repository that a stackorder_outputs block reads, appears as a stack with external: true, repo set and key qualified as owner/repo//key. A stack that is an instance of its directory has the key path:instance and carries instance; workspace is set only when the stack selects a Terraform workspace; and watch_paths lists the repository-relative files outside the stack directory that it reads at init or plan, its backend configuration files and var files. backend is the effective backend, after the stack's backend_config. A node from a CLI older than instances has workspace and no instance; the server takes the workspace as the instance.
The uploaded config, the pull request's own stackorder.yaml after defaults and validation, decides the affected set of the plan, but cannot shrink it: when it differs from the default branch's configuration, the graph is resolved under both and the affected sets are united. Stacks of the default-branch graph (before the first merge, the latest graph) that only the default branch's configuration discovers are added to the commit's graph when it finds them affected, and warnings names the keys that differ and the stacks planned because of them. Such a stack whose directory the pull request deletes is not added; warnings names it as removed. Policy does not come from it either: a default-branch plan_output: summary always wins over it, and the apply gate, allowed_teams and the environment an apply runs under are read from the default branch when the apply starts.
{
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"affected": [
{
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"wave": 0,
"reasons": ["module"],
"environment": "production",
"tool": "tofu",
"tool_version": "1.10.0",
"plan_output": "full",
"via": ["acme/infra//modules/vpc"]
},
{
"key": "stacks/prod/apps",
"path": "stacks/prod/apps",
"wave": 1,
"reasons": ["dependent"],
"environment": "production",
"tool": "tofu",
"tool_version": "1.10.0",
"plan_output": "full",
"via": ["stacks/prod/vpc"]
}
],
"waves": [["stacks/prod/vpc"], ["stacks/prod/apps"]],
"matrix": {
"include": [
{
"stack": "stacks/prod/vpc",
"key": "stacks/prod/vpc",
"workspace": "",
"environment": "production",
"wave": 0,
"tool": "tofu",
"tool_version": "1.10.0",
"plan_output": "full",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c"
},
{
"stack": "stacks/prod/apps",
"key": "stacks/prod/apps",
"workspace": "",
"environment": "production",
"wave": 1,
"tool": "tofu",
"tool_version": "1.10.0",
"plan_output": "full",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c"
}
]
},
"cached": false
}Other fields: warnings; cycles, set when resolution failed on a dependency cycle, each entry spelling one cycle (the response is still 200, and the run fails); external, the cross-repository stacks with an ordering edge to a scheduled stack; unconfirmed, set only when the CLI produced the response locally; and locked_by on an affected stack another pull request holds a lock on. reasons are changed, watch_path (a file outside the stack directory that the stack reads changed), module, reads_state, dependent and requested, in that order. Affected stacks and matrix entries carry instance next to workspace.
PUT /v1/repos/{owner}/{repo}/default-graph
Records the graph a push-triggered resolve job scanned on the default branch as the repository's default-branch graph, so a direct push to the default branch updates the stack lists, /v1/overview, removed stacks and drift scheduling at once, instead of waiting for the next merged pull request that had a plan. Only a merge and this endpoint move the default-branch graph.
The token must be a GitHub Actions OIDC token of a push event: event_name is push, repository and repository_id are the repository's, and ref is refs/heads/<default branch>. The request's graph.sha must be the token's sha (leave it empty to take it from the token). The server then reads the current head of the default branch from GitHub and records the graph only when it still equals that commit. A pull-request token, a fork (which gets no OIDC token), or a push whose commit is no longer the head records nothing: the response is 200 with recorded: false and a reason. Recordings of one repository are serialised and the head is read inside that serialisation, so an out-of-order, superseded or force push cannot replace a newer graph, and the last push to reach the head wins. A merged pull request records its plan graph through the same lock and head check and only while the merge commit is still the branch head, so the two writers share one ordering and a delayed or redelivered merge webhook cannot revert the default branch to the pull request's older graph after a newer push. Recording the default-branch graph marks the stacks it no longer lists removed, and clears the mark on those it lists again, exactly as a merged pull request's plan does.
{
"graph": { "repo": "acme/infra", "sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c", "stacks": [] }
}{
"recorded": true,
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"head": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c"
}No reusable workflow posts here yet; the resolve job records the default-branch graph when it runs on a push to the default branch, which a future stackorder/actions release triggers. A repository that has not adopted that trigger keeps the previous behaviour, where only merges move the default-branch graph.
POST /v1/runs/{id}/stacks/{key}/result
Reports a plan, apply or drift outcome for one stack and answers with the stack's updated row. mode must match the run's mode. Posting the same result twice changes nothing. A result for a stack that already finished is 409 conflict, and one for a superseded run is 409 superseded. For a pull_request token a plan run is final once it is planned, failed or otherwise finished: any result other than a repeat of the recorded one is 409 conflict, so a re-run of only the failed jobs of the plan workflow cannot report to it; re-run all jobs, push or comment stackorder plan for a new plan run. An API key may report only results of manual runs.
{
"mode": "plan",
"status": "success",
"exit_code": 2,
"has_changes": true,
"summary": {
"adds": 1,
"changes": 2,
"destroys": 0,
"replaces": 0,
"added": ["aws_route_table.private[2]"],
"changed": ["aws_subnet.private[0]", "aws_subnet.private[1]"]
},
"plan_text": "OpenTofu will perform the following actions: ...",
"plan_artifact": "stackorder-plan-stacks-prod-vpc-69df0ef0-9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"job_url": "https://github.com/acme/infra/actions/runs/12345678901",
"tool": "tofu",
"tool_version": "1.10.0",
"duration_ms": 48210,
"backend": {
"type": "s3",
"bucket": "acme-terraform-state",
"key": "stacks/prod/vpc/terraform.tfstate",
"region": "us-east-1",
"use_lockfile": true
},
"state": {
"bucket": "acme-terraform-state",
"key": "stacks/prod/vpc/terraform.tfstate",
"region": "us-east-1"
}
}An apply or drift result also carries resources, the resource list the job read from the stack's state:
{
"resources": {
"total": 2,
"items": [
{
"address": "aws_subnet.private[0]",
"type": "aws_subnet",
"provider": "registry.opentofu.org/hashicorp/aws"
},
{
"address": "module.nat.aws_nat_gateway.this[\"a\"]",
"type": "aws_nat_gateway",
"module": "module.nat",
"provider": "registry.opentofu.org/hashicorp/aws",
"tainted": true
}
]
}
}status is success, failure (the tool or a hook failed, or the CLI refused) or error. exit_code is the tool's exit code, 2 for a plan with changes. Other fields: truncated when the plan text was cut at 256 KB, error_text, and unconfirmed, which records the stack as unconfirmed. The summary can also count imports, moves and output_changes, and list destroyed and replaced addresses. Plan text of a stack whose default-branch plan_output is summary is never stored.
backend is the backend init recorded. state is the S3 object that held the stack's state after init and workspace selection: bucket, key with the workspace prefix (env:/production/stacks/prod/vpc/terraform.tfstate in the workspace production), and region unless the backend takes it from the environment. The CLI leaves it out for a backend other than s3, or without a bucket or a key. The server records it as the stack's state location from an accepted apply or drift result, manual runs included and whatever the outcome; never from a plan result, a repeated or refused result, or a result of a run older than the one that recorded the current location, and, with shared outputs on, never an object that no entry of STACKORDER_STATE_BUCKETS grants the stack's repository: such a result clears the recorded location instead, under the same order, and the server logs the object. Shared outputs read the state from there.
resources lists the managed resources in the stack's state, sorted by address, with no attribute values: each item has address, type, module (the module address, left out in the root module), provider (the provider's source address), and tainted and deposed when the object is tainted or the state also holds a deposed object at the address. Data sources are left out. An address still carries the for_each keys of the resource and its modules, which come from configuration; see Resource lists. total counts every resource in the state, and truncated is set when items holds fewer. Apply jobs read the list once the tool has run, failed applies included, and drift jobs after the plan; plan results never carry one. The server records it as the stack's list from an accepted apply or drift result, manual runs included, whatever the outcome and even when the result repeats the recorded one, unless the recorded list was read from newer state: a confirmed apply result counts as read when it first arrives, and a repeat of it counts as read when the first accepted post finished the stack, so a late repeat never replaces the list of a drift run created, or of an apply result first posted, after that; a drift or unconfirmed apply result counts as read when its run was created. A plan result's list and a refused result's are ignored. The server drops an item with an empty address or type, invalid UTF-8, a control or format character, or a field over its limit (2048 bytes for address and module, 512 for type and provider), keeps the rest and sets truncated; it merges items with the same address and drops any last_change. A list's content never makes the server refuse a result, but its JSON types are checked with the rest of the body: a string for tainted is 400 invalid with details.field resources.items.tainted. A result body may be up to 1 MB (MaxResultBytes); the CLI cuts the list to fit, and when the server answers 413 or a 400 invalid whose details.field starts with resources, it posts the result once more without the list.
{
"stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"environment": "production",
"wave": 0,
"status": "planned",
"reasons": ["module"],
"summary": {
"adds": 1,
"changes": 2,
"destroys": 0,
"replaces": 0,
"added": ["aws_route_table.private[2]"],
"changed": ["aws_subnet.private[0]", "aws_subnet.private[1]"]
},
"exit_code": 2,
"job_url": "https://github.com/acme/infra/actions/runs/12345678901",
"plan_artifact": "stackorder-plan-stacks-prod-vpc-69df0ef0-9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"plan_text": "OpenTofu will perform the following actions: ...",
"plan_output": "full",
"started_at": "2026-09-28T09:14:03Z",
"finished_at": "2026-09-28T09:14:51Z"
}A row can also carry instance, workspace, truncated, checks (the stack's named checks), blocked_by (the failed predecessors of a blocked stack), lock (the orchestration lock on the stack now, whichever run holds it; stackorder apply applies only while it names its own run) and plan_url (the full plan text in the artifact bucket, when plan_text holds only its beginning).
POST /v1/runs/{id}/stacks/{key}/checks/{name}
Records a named policy or cost check verdict from any tool the workflow runs, and answers with the stored check. The same caller rules as for results apply. The server shows the verdict as the check run stackorder/<name>: <key> and the apply gate honours it. name is letters, digits, -, _ and ., up to 64 characters; resolve, plan and apply are reserved. Posting again replaces the verdict until, for a pull_request token, the plan run is planned or finished; after that only a repeat of the recorded verdict is answered and anything else is 409 conflict. Post verdicts before the stack's result, as a post-plan.sh hook does.
{
"status": "fail",
"summary": "2 policy violations",
"details": "deny: aws_s3_bucket.logs must block public access",
"details_url": "https://github.com/acme/infra/actions/runs/12345678901"
}{
"name": "policy",
"status": "fail",
"summary": "2 policy violations",
"details_url": "https://github.com/acme/infra/actions/runs/12345678901",
"updated_at": "2026-09-28T09:15:10Z"
}status is pass, fail or warn. In the gate warn passes and fail refuses; on GitHub warn is a neutral check.
GET /v1/runs/{id}
The run with its per-stack rows. A pull_request token may read only its own pull request's plan run, and only until it is planned or finished (409 conflict, or 409 superseded); a workflow_dispatch token is bound to its dispatch on first contact, as for POST /v1/runs.
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"base_sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
"pr_number": 42,
"trigger": "comment",
"mode": "apply",
"status": "applying",
"requested_by": "octocat",
"created_at": "2026-09-28T09:20:00Z",
"started_at": "2026-09-28T09:20:04Z",
"waves": 2,
"current_wave": 0,
"stacks": [
{
"stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"environment": "production",
"wave": 0,
"status": "applying",
"reasons": ["module"],
"plan_artifact": "stackorder-plan-stacks-prod-vpc-69df0ef0-9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"plan_output": "full"
},
{
"stack_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"key": "stacks/prod/apps",
"path": "stacks/prod/apps",
"environment": "production",
"wave": 1,
"status": "planned",
"reasons": ["dependent"],
"plan_artifact": "stackorder-plan-stacks-prod-apps-4b32b4c4-9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"plan_output": "full"
}
],
"html_url": "https://stackorder.example.com/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7"
}html_url links to the run's page in the web UI; warnings lists anything the server wants people to see, such as a dispatch GitHub refused. Run status is pending, planning, planned, applying, applied, failed, unconfirmed or superseded. Stack status adds blocked, noop, unknown and skipped. See Run states.
GET /v1/repos/{owner}/{repo}/stacks/{key}/outputs
The root-module outputs of stack {key} of {owner}/{repo}, the producer, read from its state for a stack that the producer's default branch lists under outputs.readers. The stackorder provider calls it from a stack's job; Shared outputs has the whole feature. The server answers only when its operator has set STACKORDER_STATE_BUCKETS, and 404 outputs_disabled otherwise.
The caller is a runner or an API key, never a person: a session cookie is 401 unauthorized, and the web UI shows no outputs.
GET /v1/repos/acme/infra/stacks/stacks%2Fprod%2Fvpc/outputs?run=7c9e6679-7425-40de-944b-e07fc1f90ae7&reader=stacks%2Fprod%2Feks| Parameter | Meaning |
|---|---|
run | The id of the run the calling job belongs to. Required with a runner token. Optional with an API key, which only has its form checked: 400 invalid with details.field run_id when it is not a UUID. |
reader | The key of the reading stack. Required with a runner token. Optional with an API key, which only has its form checked: 400 invalid with details.field reader when it is not a stack key. |
Whatever the credential, a repository, key, run or reader that is not valid UTF-8 or holds a control character, such as %00, is 400 invalid before anything is looked up, with details.field repo, stack_key, run_id or reader.
A runner token must name a run of its own repository and a stack of that run whose job has not reported yet: pending, planning or unknown in a plan or drift run, and pending, planned, applying or unknown in an apply run. The run must not be superseded (409 superseded) or finished, nor, for a pull_request token, planned (409 conflict). A workflow_dispatch token's reader must have been dispatched, and the job binds to its dispatch as for a result. A missing run or reader, a run that does not exist or belongs to another repository, which answer alike, and a stack that is not one of the run's are 403 forbidden. The producer must belong to the reader's installation, and the producer's outputs.readers must match the reader. An API key reads the outputs of any stack, whatever its readers, and every read is audited; an installation-scoped key reads only stacks of its own installation and treats any other as not found.
The producer's repository is matched without regard to case. Its policy comes from the default branch only: repos.config and the stack's .stackorder.yaml at the commit that configuration was read at. At that commit, the key must name a stack the default branch still has: stackorder.yaml discovers its directory, the directory exists, and the key names one of the stack's instances, declared in its .stackorder.yaml or derived by stacks.instances.from_var_files from the var files there, or none for a stack without instances.
{
"repo": "acme/infra",
"stack": "stacks/prod/vpc",
"serial": 42,
"lineage": "8d3f6c1e-2b7a-4e9d-9c51-0f4a6b2d7e13",
"terraform_version": "1.9.8",
"outputs": {
"private_subnet_ids": {
"value": ["subnet-0a1b2c3d4e5f6a7b8", "subnet-0b2c3d4e5f6a7b8c9"],
"type": ["list", "string"],
"sensitive": false
},
"vpc_id": {
"value": "vpc-0a1b2c3d4e5f67890",
"type": "string",
"sensitive": false
}
},
"withheld": ["vpn_preshared_key"]
}| Field | Meaning |
|---|---|
repo, stack | The producer, as owner/repo, and its key |
serial, lineage, terraform_version | Those of the state the outputs were read from |
outputs | Every output served, by name: its value and its type, the cty type as the state writes it, such as "string" or ["list", "string"], both as JSON, and sensitive. Always an object, {} when there is nothing to serve |
withheld | The names of the sensitive outputs left out, sorted, when the producer's outputs.sensitive is withhold; absent when there are none |
The response carries Cache-Control: no-store. Nothing read from the state is stored, cached or logged by the server. Reads are recorded in the audit log as outputs_read, and refusals of the caller, the run, the producer or its policy as outputs_refused, with counts and never values; a read that cannot be recorded is not served. Errors says which refusals are not recorded.
Errors
Beyond 401 unauthorized, 400 invalid, 403 forbidden, 409 conflict and 409 superseded for the caller and the run, a read answers:
| Status | Code | When |
|---|---|---|
| 404 | outputs_disabled | The server reads no state: STACKORDER_STATE_BUCKETS is unset. |
| 403 | outputs_not_shared | The reader is a stack of the producer's repository, and the producer's default-branch outputs.readers does not list it, or the producer's outputs configuration does not parse or render. The message names the files to edit. |
| 404 | not_found | The repository does not exist, is suspended or, for a runner, belongs to another installation; the key is not a stack of it, or not one its default branch still has: stackorder.yaml no longer discovers the directory, the directory was deleted on the default branch, or the instance is no longer declared, or no longer has its var file. For a reader in another repository, also a producer that does not list it or whose configuration does not resolve. One message covers every cause. |
| 409 | state_location_unknown | The producer has had no apply or drift job on a CLI that reports its state object, or its last one reported an object outside every entry of STACKORDER_STATE_BUCKETS granted to its repository, so the server does not know where its state is. |
| 403 | state_bucket_not_allowed | The state object lies outside the entries of STACKORDER_STATE_BUCKETS granted to the producer's repository or to *. Nothing was requested from S3. |
| 403 | state_access_denied | S3, or KMS through S3, denied the server access to the state object, or STS refused to let the server assume STACKORDER_STATE_ROLE_ARN. Without s3:ListBucket, S3 also answers so for a missing object. |
| 404 | state_not_found | The state object, or its bucket, does not exist. |
| 422 | state_encrypted | OpenTofu encrypted the state. The server never decrypts state. |
| 422 | state_unsupported | The state's format version is not 4. |
| 422 | state_too_large | More than 64 MiB of the object precede its outputs, or the outputs, or a single string or number before them, exceed 4 MiB. |
| 422 | state_unreadable | The object is not valid state JSON, its location is unusable, such as an invalid region, or S3 refused the request for another reason. |
| 503 | unavailable | The read failed for now: S3 throttled it, answered with a server error or did not answer within 30 s, the server's read slots stayed busy for 20 s, or the server could not record the read in the audit log, so it served nothing. Retry. |
A read never answers the generic 422 unprocessable: each of its 422s carries one of the codes above.
Refusals answered with invalid, forbidden, not_found, conflict, superseded, outputs_not_shared, state_location_unknown or state_bucket_not_allowed are audited as outputs_refused, with the code as details.reason. outputs_disabled is not audited, and neither is a failure of the state read itself: state_access_denied, state_not_found, state_encrypted, state_unsupported, state_too_large, state_unreadable and unavailable. Troubleshooting says what to do about each code.
Human and automation endpoints
GET /v1/runs/{id}/stacks/{key}/plan
The full plan text of a stack of a run, as text/plain; charset=utf-8, read from the artifact bucket. Use it when the run's stack row has truncated and plan_url set: its plan_text then holds only the first 8 KB, and this endpoint returns everything the CLI sent, up to 256 KB. {key} is percent-encoded like the runner endpoints' keys. A person sees the runs of the repositories they see; API keys see every run.
404 with code not_found when the run is unknown or hidden, the stack is not part of the run, the row has no plan_url (its plan_text is all the server keeps, as for every stack without a bucket and for plan_output: summary stacks), the server has no artifact bucket, or the object has expired from the bucket. Runner tokens are refused with 401.
POST /v1/runs/{id}/rerun
Plans every stack of a plan run again, in a new run on the same commit with trigger rerequest, dispatched to stackorder-run.yml with mode: plan. The body is empty. A person needs push permission on the repository. Only plan runs can be re-run; a superseded run is 409 superseded. Audited as rerun. The response is a CreateRunResponse for the new run, 201:
{
"run_id": "0d9c8b7a-6f5e-4d3c-8b2a-1f0e9d8c7b6a",
"status": "planning",
"existing": false,
"run": {
"id": "0d9c8b7a-6f5e-4d3c-8b2a-1f0e9d8c7b6a",
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"pr_number": 42,
"trigger": "rerequest",
"mode": "plan",
"status": "planning",
"requested_by": "octocat",
"created_at": "2026-09-28T10:02:00Z",
"waves": 1,
"current_wave": 0,
"html_url": "https://stackorder.example.com/runs/0d9c8b7a-6f5e-4d3c-8b2a-1f0e9d8c7b6a"
}
}POST /v1/unlock
Releases a stack's orchestration lock, whoever holds it, addressed by repository and key. This is what stackorder unlock calls. repo and stack_key are required. A person needs push permission on the repository. Audited as unlock; the pull request that held the lock gets a comment.
{
"repo": "acme/infra",
"stack_key": "stacks/prod/vpc",
"reason": "PR 41 closed; reverted in PR 43",
"force_state": false
}{
"released": [
{
"stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"stack_key": "stacks/prod/vpc",
"run_id": "5b8e1f2a-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"pr_number": 41,
"taken_at": "2026-09-27T16:02:11Z",
"reason": "apply of #41"
}
]
}released is empty when the stack held no lock. force_state: true releases the lock the same way; it marks the release as following a runner that died mid-apply, and the comment asks for the S3 state lock to be checked. The server never touches the state lock.
POST /v1/stacks/{id}/unlock
The same release, addressed by stack id, as the UI does it. The body is optional and carries reason and force_state:
{ "reason": "runner lost during apply", "force_state": true }The response is an UnlockResponse, as above.
GET /v1/me
For a person:
{
"login": "octocat",
"avatar_url": "https://avatars.githubusercontent.com/u/583231",
"orgs": ["acme"]
}For an API key, login is apikey:<key name> and admin is true only for an unscoped key; a read-only or installation-scoped key reports admin false (omitted):
{ "login": "apikey:ci", "orgs": [], "admin": true }GET /v1/overview
Counts over the repositories the caller sees.
{
"repos": 3,
"stacks": 57,
"drifted": 2,
"locks_held": 4,
"runs_by_status": { "applied": 120, "failed": 3, "planned": 14, "superseded": 31 },
"stacks_by_status": { "applied": 48, "planned": 6, "failed": 1, "blocked": 2 },
"recent_runs": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"pr_number": 42,
"trigger": "comment",
"mode": "apply",
"status": "applied",
"requested_by": "octocat",
"created_at": "2026-09-28T09:20:00Z",
"finished_at": "2026-09-28T09:22:40Z",
"waves": 2,
"current_wave": 1,
"stack_count": 2,
"stack_keys": ["stacks/prod/vpc", "stacks/prod/apps"],
"summary": { "adds": 3, "changes": 1, "destroys": 0, "replaces": 0 },
"html_url": "https://stackorder.example.com/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
]
}runs_by_status and stacks_by_status are always present, {} when empty. recent_runs has the same run list fields as the runs of a repository. stacks and drifted count only the stacks the default branch still has: a stack whose directory a merged pull request deletes stops being counted once the merge updates the default-branch graph.
GET /v1/repos
A page of repositories, ordered by full name.
{
"items": [
{
"id": 123456789,
"full_name": "acme/infra",
"default_branch": "main",
"stacks": 42,
"drifted": 1,
"locks_held": 2,
"last_run_at": "2026-09-28T09:20:00Z"
}
],
"total": 1
}GET /v1/repos/{owner}/{repo}/graph
The repository's graph as JSON, for tooling, with the server's stack ids.
| Parameter | Meaning |
|---|---|
ref | The commit: a full commit SHA the server has a graph for, a prefix of at least 7 characters that only one recorded graph starts with, or default for the default-branch graph (404 before the first merge). A prefix several graphs share, or anything else, is refused with invalid (details.field is ref); branch names are not supported, because the server records graphs by commit only. Without it: the default-branch graph (the latest graph of a merged pull request) when known, else the latest graph. |
run | A run of this repository. The graph is then that run's graph, unless ref is given, and the response adds the run's affected stacks and waves, to replay its resolution. |
{
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"graph": {
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"stacks": [{ "key": "stacks/prod/vpc", "path": "stacks/prod/vpc", "environment": "production" }],
"modules": [{ "key": "acme/infra//modules/vpc", "kind": "local", "path": "modules/vpc", "source": "../../../modules/vpc" }],
"edges": [
{
"from": { "kind": "stack", "key": "stacks/prod/vpc" },
"to": { "kind": "module", "key": "acme/infra//modules/vpc" },
"type": "uses_module",
"meta": { "ref": "", "source": "../../../modules/vpc" }
}
]
},
"stack_ids": { "stacks/prod/vpc": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f" }
}A repository with no recorded graph, or a ref without one, is 404 not_found.
GET /v1/repos/{owner}/{repo}/runs
A page of the repository's runs, newest first, in the Run shape without stacks. status (a run status), pr (a positive number) and mode (plan, apply or drift) filter the list; an unknown value is 400 invalid.
Instead of stacks, each run sums up its stacks, leaving out those an apply skips: stack_count is how many it covers, stack_keys the first five of their keys in wave order, and summary their plan summaries added up, without addresses. summary is absent until a stack has a plan summary, and the three fields are absent for a run with no stacks yet.
{
"items": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"repo": "acme/infra",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"pr_number": 42,
"trigger": "comment",
"mode": "apply",
"status": "applied",
"requested_by": "octocat",
"created_at": "2026-09-28T09:20:00Z",
"started_at": "2026-09-28T09:20:04Z",
"finished_at": "2026-09-28T09:22:40Z",
"waves": 2,
"current_wave": 1,
"stack_count": 2,
"stack_keys": ["stacks/prod/vpc", "stacks/prod/apps"],
"summary": { "adds": 3, "changes": 1, "destroys": 0, "replaces": 0 },
"html_url": "https://stackorder.example.com/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
],
"next_cursor": "MjAyNi0wOS0yOFQwOToyMDowMFo"
}GET /v1/repos/{owner}/{repo}/stacks
A page of the repository's current stacks, ordered by key, each in the StackDetail shape, with total. A stack the default branch no longer has, because a merged pull request deleted its directory, is left out once the merge updates the default-branch graph; its id still resolves at GET /v1/stacks/{id}.
{
"items": [
{
"id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"repo": "acme/infra",
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"environment": "production",
"tool": "tofu",
"dependents": ["stacks/prod/apps"]
}
],
"total": 1
}GET /v1/stacks
A page of the current stacks of every repository the caller sees, ordered by repository full name and then by key, each in the StackDetail shape, with total. Each item is the one GET /v1/repos/{owner}/{repo}/stacks returns for the stack.
{
"items": [
{
"id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"repo": "acme/infra",
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"environment": "production",
"tool": "tofu",
"dependents": ["stacks/prod/apps"]
},
{
"id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"repo": "acme/network",
"key": "stacks/prod/tgw",
"path": "stacks/prod/tgw",
"environment": "production",
"tool": "tofu"
}
],
"next_cursor": "YWNtZS9uZXR3b3JrAHN0YWNrcy9wcm9kL3Rndw",
"total": 42
}GET /v1/stacks/{id}
Stack detail: last plan and apply, the latest drift result, the lock, dependencies both ways (over depends_on and reads_state in the default-branch graph) and pinned modules.
{
"id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"repo": "acme/infra",
"key": "stacks/prod/vpc",
"path": "stacks/prod/vpc",
"environment": "production",
"backend": {
"type": "s3",
"bucket": "acme-terraform-state",
"key": "stacks/prod/vpc/terraform.tfstate",
"region": "us-east-1",
"use_lockfile": true
},
"tool": "tofu",
"last_apply": {
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"pr_number": 42,
"status": "applied",
"summary": { "adds": 1, "changes": 2, "destroys": 0, "replaces": 0 },
"finished_at": "2026-09-28T09:22:40Z",
"job_url": "https://github.com/acme/infra/actions/runs/12345679999"
},
"drift": {
"checked_at": "2026-09-28T06:07:12Z",
"drifted": false
},
"dependents": ["stacks/prod/apps"],
"modules": [
{ "module_key": "acme/modules//tags", "ref": "v1.2.0", "latest": "v1.4.1", "behind": 2 }
]
}last_plan has the same shape as last_apply. A stack detail also carries instance and workspace when they are set. lock is a LockInfo while the stack is locked. A drifted stack's drift carries the plan summary and, with drift issues enabled, issue_number and issue_url.
GET /v1/stacks/{id}/runs
A page of the stack's history, newest first, each item in the RunStackRef shape:
{
"items": [
{
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"pr_number": 42,
"status": "applied",
"summary": { "adds": 1, "changes": 2, "destroys": 0, "replaces": 0 },
"finished_at": "2026-09-28T09:22:40Z",
"job_url": "https://github.com/acme/infra/actions/runs/12345679999"
}
],
"next_cursor": "MjAyNi0wOS0yOFQwOToyMDowMFo"
}GET /v1/stacks/{id}/resources
The stack's resource list: the managed resources its last apply or drift job found in its state, with no attribute values. A person sees the stacks of the repositories they see, and API keys every stack; a stack the caller cannot see is 404, and runner tokens are refused with 401.
{
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"mode": "apply",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"reported_at": "2026-09-28T09:22:41Z",
"changed_at": "2026-09-28T09:22:41Z",
"total": 3,
"items": [
{
"address": "aws_route_table.private[2]",
"type": "aws_route_table",
"provider": "registry.opentofu.org/hashicorp/aws",
"last_change": {
"action": "create",
"run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"sha": "9b2f7c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
"pr_number": 42,
"finished_at": "2026-09-28T09:22:40Z"
}
},
{
"address": "aws_vpc.main",
"type": "aws_vpc",
"provider": "registry.opentofu.org/hashicorp/aws"
},
{
"address": "module.nat.aws_nat_gateway.this[\"a\"]",
"type": "aws_nat_gateway",
"module": "module.nat",
"provider": "registry.opentofu.org/hashicorp/aws",
"tainted": true
}
]
}run_id, mode (apply or drift) and sha name the run whose job reported the list; run_id is left out if that run is deleted. reported_at is when the list was last recorded, and changed_at when it last differed from the list before it. Items have the fields of a result's resources, and truncated is set when items holds fewer than total.
last_change is the newest applied run whose plan created (create), updated (update) or replaced (replace) the address: its run_id, sha, pr_number and finished_at, when the stack's apply finished. The server derives it from the plan summaries of the stack's applied runs and stores nothing for it. It is left out when no applied run changed the address, as for a resource imported, moved, created outside Stackorder or by an apply that failed, and when the newest such run destroyed the address, since what recreated it is unknown.
With no list recorded, the answer is 200 with "total": 0, "items": [] and no run fields. A removed stack keeps its last list. The list is not paged: it fits in a result body.
GET /v1/modules
A page of modules, ordered by key, each in the ModuleDetail shape. A git or registry module is listed once, under its family key without @ref. ?q= keeps the modules whose key contains the text, ignoring case. A person sees a module that belongs to one of their accounts or has a consumer they can see.
{
"items": [
{
"id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"key": "acme/modules//tags",
"kind": "git",
"source": "git::https://github.com/acme/modules.git//tags?ref=v1.4.1",
"latest": "v1.4.1",
"consumers": [
{ "stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f", "repo": "acme/infra", "stack_key": "stacks/prod/vpc", "ref": "v1.2.0", "behind": 2 }
]
}
],
"total": 1
}GET /v1/modules/{id}
One module with its released versions and its consumers across repositories. latest is the newest stable version by semantic version precedence, whatever order the tags were pushed in, or the newest pre-release when no stable version is released. Each consumer carries the ref it pins and how many released versions it is behind. An id of a pinned module (key@ref) answers with its family.
{
"id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"key": "acme/modules//tags",
"kind": "git",
"source": "git::https://github.com/acme/modules.git//tags?ref=v1.4.1",
"latest": "v1.4.1",
"versions": [
{ "version": "v1.4.1", "sha": "c0ffee1234567890c0ffee1234567890c0ffee12", "tagged_at": "2026-09-20T12:00:00Z" },
{ "version": "v1.3.0", "sha": "decafbad1234567890decafbad1234567890deca", "tagged_at": "2026-08-02T08:30:00Z" }
],
"consumers": [
{
"stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"repo": "acme/infra",
"stack_key": "stacks/prod/vpc",
"ref": "v1.2.0",
"behind": 2
}
]
}GET /v1/audit
A page of audited actions, newest first: unlocks (unlock), re-runs (rerun), manual applies (manual_apply), comment commands (command, command_ignored, command_rate_limited), reads of a stack's outputs (outputs_read, outputs_refused), lock warnings and reminders, cross-repository plans and invalid configuration notices.
{
"items": [
{
"at": "2026-09-28T09:31:00Z",
"actor": "octocat",
"action": "unlock",
"target": "acme/infra//stacks/prod/vpc",
"details": {
"repo": "acme/infra",
"stack": "stacks/prod/vpc",
"stack_id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"pr": 41,
"run_id": "5b8e1f2a-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
"reason": "PR 41 closed",
"force_state": false
}
}
],
"next_cursor": "MTIz"
}Unlocks target the qualified stack key owner/repo//key and keep the stack's id in details.stack_id; re-runs and comment commands target owner/repo and keep the pull request in details.pr. Reads of a stack's outputs target the producer's qualified key and keep details.stack, details.reader_repo, details.reader and details.run_id; outputs_read adds the counts details.outputs, details.sensitive and details.withheld, and outputs_refused the error code as details.reason. Their details.repo is the producer, or the runner's own repository when a runner was refused before the producer was found. Every one of them carries details.repo. A person sees the entries they made and those whose details.repo, or whose target (owner/repo… or kind:owner/repo…), names a repository they see.
API keys
These endpoints create, list and revoke API keys. Only an unscoped administrator API key may call them. A read-only or installation-scoped key, a session cookie and a runner token are refused — a session and a scoped key with 403 forbidden ("managing API keys requires an administrator API key"), a runner token with 401 unauthorized — so a scoped key can never mint itself a broader one. The first key, when none exists, is minted with the stackorder-server api-key subcommand instead.
POST /v1/keys
Creates a key and returns its metadata together with the full secret, which is shown only here and stored only as a SHA-256 hash afterwards. name is required, is trimmed, and must be at most 100 characters. The key's created_by is the calling key's actor (apikey:<name>). The creation is audited as api_key_created; the key and its audit entry are written in one transaction, so the call fails and creates no key if the entry cannot be recorded.
The request may scope the new key:
| Field | Meaning |
|---|---|
read_only | A key refused every mutating route. Default false. |
installation_id | Limit the key to one installation id; it sees nothing of any other. Default 0, every installation. An id that is not an installation of this server is 400 invalid. |
expires_at | When the key stops authenticating, RFC 3339. Must be in the future, else 400 invalid. Default unset, never expires. |
{
"id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"name": "deploy",
"prefix": "sk_7f3a9c1",
"created_by": "apikey:ci",
"created_at": "2026-11-15T09:20:00Z",
"read_only": true,
"installation_id": 42,
"expires_at": "2027-05-15T09:20:00Z",
"secret": "sk_7f3a9c1d…"
}read_only, installation_id and expires_at are omitted when the key is unscoped on that axis.
GET /v1/keys
Every key, revoked ones included, newest first. The secret is never returned; only prefix identifies a key by sight.
{
"keys": [
{
"id": "3d6f0a2e-1b4c-4d8e-9f10-2a3b4c5d6e7f",
"name": "deploy",
"prefix": "sk_7f3a9c1",
"created_by": "apikey:ci",
"created_at": "2026-11-15T09:20:00Z",
"last_used_at": "2026-11-15T10:05:00Z",
"revoked_at": null
}
]
}DELETE /v1/keys/{id}
Revokes the key with id, a UUID, and returns its metadata with revoked_at set. A revoked key no longer authenticates. Revoking an already-revoked key keeps the first revocation time and still answers 200. An unknown or malformed id is 404 not_found. Only the call that actually revokes the key is audited as api_key_revoked, in the same transaction as the revocation, so the call fails and the key stays as it was if the entry cannot be recorded, and a repeated revoke records no further entry. A key may revoke itself.
Sign-in
GET /auth/login redirects to GitHub's authorization page for the App's OAuth client with the read:org scope, and remembers next (a path on this server, / by default) for 10 minutes in a signed cookie. GET /auth/callback exchanges the code, reads the user and their organisations, and issues a session only when the App is installed, and not suspended, on the user's account or on one of their organisations; otherwise it shows a page explaining that the App is not installed. The session lasts 7 days, is stored hashed in Postgres, records the user's organisations at sign-in (a membership change takes effect at the next sign-in), and is sent as the stackorder_session cookie: HttpOnly, SameSite=Lax, and Secure when the base URL is https. POST /auth/logout ends the session and answers 204.
Without GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET, /auth/login answers 503 with a page saying sign-in is not configured.
Setup
GET /setup renders a page that posts the GitHub App manifest (webhook URL, callback URLs, permissions and events) to GitHub's App creation page, on your personal account or, with ?org=<organisation>, on an organisation. ?name= chooses the App name, up to 34 characters; the default is stackorder-<host>. Outside setup mode the page explains that an App is already configured; ?force=1 creates another App only when STACKORDER_ALLOW_RESETUP is true, and otherwise GET /setup?force=1 and GET /setup/callback answer 404.
The manifest form needs the setup token the server logs at start-up. ?token=<token> sets the stackorder_setup_auth cookie, signed, bound to the token and valid for an hour, and answers 303 to the same URL without token. Without the token or that cookie, GET /setup answers 403. Once an App is created, the token and the cookie stop working until the server restarts, and GET /setup says an App exists.
GitHub redirects back to GET /setup/callback, which converts the one-time code into the App's credentials and prints them once as environment variables: GITHUB_APP_ID, GITHUB_WEBHOOK_SECRET, GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET and the PEM for GITHUB_APP_PRIVATE_KEY, plus GITHUB_API_URL and GITHUB_WEB_URL on Enterprise Server, with a link to install the App, a link to the App's settings to upload its logo, and the next steps. The code works once and for an hour, and only from the browser that started the flow; after an App was created, the callback answers 409. GitHub sends the browser to GET /setup/installed after an installation. That page needs no token: it shows only the installation id GitHub passes. GET /setup/logo.png needs no token either and answers in and out of setup mode: it is the 512×512 Stackorder logo to upload in the App's settings, since GitHub sets an App's logo only there.
In setup mode, when the App variables are not set, the server serves only these three pages, the logo, /healthz and /readyz, and answers 503 with code unavailable everywhere else:
{
"code": "unavailable",
"message": "setup is required: the GitHub App is not configured yet; open https://stackorder.example.com/setup with the setup token from the server log"
}Webhooks
POST /webhooks/github receives every App event. It verifies the X-Hub-Signature-256 HMAC against GITHUB_WEBHOOK_SECRET, writes the delivery to the events queue keyed by its X-GitHub-Delivery id, and answers 202 before any work is done. A redelivery of a stored id is acknowledged with "queued": false and not processed again.
{ "queued": true }| Answer | When |
|---|---|
202 {"queued": true} | A new delivery |
202 {"queued": false} | A delivery id already stored |
200 {"ok": true} | A ping |
401 unauthorized | Missing or wrong signature |
400 invalid | No event or delivery header, or a body that is not JSON |
413 invalid | A body over 5 MB |
This route has no API body limit; the webhook receiver bounds it. See GitHub App for the events.
Health and metrics
| Endpoint | Answer |
|---|---|
GET /healthz | Always 200 while the process serves |
GET /readyz | 200 when the database answers within 2 s, in setup mode too; 503 unavailable otherwise |
GET /metrics | Prometheus metrics; with STACKORDER_METRICS_TOKEN set, 401 without Authorization: Bearer <token>. See Metrics and tracing. |
{ "status": "ok", "version": "0.2.0" }In setup mode both health endpoints add "setup_mode": true.
OIDC binding
A runner authenticates with the job's GitHub Actions OIDC token, requested for the audience STACKORDER_OIDC_AUDIENCE. Before any handler runs, the server checks the token itself:
| Claim | Check | Failure |
|---|---|---|
| signature | RS256 against the issuer's JWKS, cached for an hour and refetched on an unknown kid | 401; 503 when the keys cannot be fetched |
iss | https://token.actions.githubusercontent.com, or GITHUB_OIDC_ISSUER | 401 |
aud | Contains STACKORDER_OIDC_AUDIENCE, which defaults to the base URL | 401 |
iat, exp | Issued within the last 10 minutes, not expired (60 s clock skew allowed) | 401 |
jti | Never seen before; every accepted jti is recorded until the token expires | 401 |
repository, repository_id | A repository the server knows, with the same GitHub id, whose installation is not suspended | 403 |
job_workflow_ref | Matches STACKORDER_REQUIRED_WORKFLOW_REF, when set | 403 |
Then the run service binds the token to the run, according to how the job started:
| Job | Claims | Binding |
|---|---|---|
| Pull request plan job | event_name is pull_request, ref is refs/pull/<n>/merge | <n> is the run's pull request, the run is a plan run started by a pull request, and, when the run is created, the pull request's head SHA read from GitHub equals the SHA the CLI sent. Such a token can reach only plan runs registered by a pull request resolve job. |
| Server-dispatched job | event_name is workflow_dispatch, ref is refs/heads/<default branch> | run_id is the workflow run of the dispatch that carries the stack, bound on first contact; run_attempt is recorded; environment equals the stack's environment for an apply, and default for a plan or drift dispatch. In an apply, a stack that no dispatch carries yet binds only to a dispatch of its own wave and environment, and a skipped stack to none, so a job never acts for a stack of another wave or one the apply skips. A read of a stack's outputs binds a workflow run no dispatch holds yet only when the workflow run's jobs name a stack of the reader's dispatch. A workflow run whose dispatch is already bound to another workflow run is refused. |
A failed binding is 403 forbidden. actor is recorded as requested_by. Results for a finished stack are 409 conflict, and for a superseded run 409 superseded. A pull_request token's plan run is final once it is planned or finished: its results, verdicts and reads are 409 conflict, except a repeat of the recorded result or verdict.
Why sha is never compared. GitHub's sha claim is the commit that triggered the workflow, not the commit being planned. For a pull_request event it is the merge commit of refs/pull/<n>/merge, which GitHub creates and changes whenever the base branch moves; for workflow_dispatch it is the head of the default branch the workflow was dispatched on, while the job checks out the sha input. Neither equals the run's SHA, the pull request head, so comparing them would refuse every legitimate job. The server binds to the commit through GitHub instead: it reads the pull request's current head when a plan run is registered, supersedes runs whose head moved, and dispatches applies only for the head that was planned, or, in on_merge mode, for the merge commit of that head. The CLI, in turn, refuses to apply unless the run's SHA equals the dispatch sha input and the checkout's HEAD.
pull_request_target plans are not supported. A fork pull request gets a neutral check from the server and no plans; see Fork pull requests.