# OuterLayer

> An open-source software factory: issue in, reviewed and verified code out, on your agents, in your repos.

- [What OuterLayer is](https://docs-stg.outerlayer.ai/index.md): An open-source software factory: issue in, reviewed and verified code out, on your agents, in your repos.
- [Quickstart](https://docs-stg.outerlayer.ai/quickstart.md): From your invite to your first issue built into a pull request by a Claude Code session on your machine.
- [Key concepts](https://docs-stg.outerlayer.ai/concepts.md): The words every other page uses, each defined once.
- [How a work item flows](https://docs-stg.outerlayer.ai/how-a-work-item-flows.md): What a work item is, what attaches to it, and what is left when the work ships.
- [Connect a repository](https://docs-stg.outerlayer.ai/connect-repository.md): Install the OuterLayer GitHub App, then link a repository and its base branch to the factory.
- [GitHub App permissions and build tokens](https://docs-stg.outerlayer.ai/github-app-and-build-tokens.md): What the OuterLayer GitHub App is allowed to do, and the short-lived repository tokens the gateway issues for a build.
- [Connect an issue tracker](https://docs-stg.outerlayer.ai/connect-a-tracker.md): Read issues from a Linear workspace or a Jira site into the Work page, next to GitHub, and file specs as Linear or Jira issues.
- [Launch a session](https://docs-stg.outerlayer.ai/launch-a-session.md): The one rule that decides whether a session uploads: it was launched naming the work item it is for.
- [Review and merge](https://docs-stg.outerlayer.ai/review-the-work.md): Review a work item on its page, ask the agent for changes, approve it, and merge its pull requests.
- [Attach evidence](https://docs-stg.outerlayer.ai/attach-evidence.md): Upload a screenshot, recording, report, log or JUnit test results as proof that a change works, anchored where a reviewer will look.
- [Share evidence](https://docs-stg.outerlayer.ai/share-evidence.md): Each pull request has an evidence page with its criteria, proof and cost. Choose whether only your team or anyone with the link can read it.
- [Record a check](https://docs-stg.outerlayer.ai/record-a-check.md): Record a named pass or fail on a work item from CI or a terminal.
- [Declare a pull request](https://docs-stg.outerlayer.ai/declare-a-pull-request.md): Tell the factory which pull request a session's work landed in.
- [Findings](https://docs-stg.outerlayer.ai/findings.md): Problems agents hit in the factory while they work, recorded so someone can fix the cause.
- [Run work on your own machines](https://docs-stg.outerlayer.ai/run-work-on-your-machines.md): outerlayer runner takes work from your factory's queue and runs it on a machine you control.
- [Set up your first host](https://docs-stg.outerlayer.ai/set-up-a-host.md): Install the runner on one machine, give it its key, give it Claude's credential, and build your first item.
- [Run the runner as a service](https://docs-stg.outerlayer.ai/run-a-host-as-a-service.md): Run the runner under an account and a service manager, move it between machines, upgrade it and remove it.
- [Run the runner in a container](https://docs-stg.outerlayer.ai/run-the-runner-in-a-container.md): Start the runner from the published image with one docker run, and keep it running with Docker's restart policy.
- [Container and microVM builds](https://docs-stg.outerlayer.ai/container-builds.md): What a build gets when the runner starts it in a container or a microVM, and how to size, limit and stop it.
- [Destinations and secrets](https://docs-stg.outerlayer.ai/destinations-and-secrets.md): Let a build reach a private service through the runner, without the build holding the secret.
- [Write your own hooks](https://docs-stg.outerlayer.ai/write-your-own-hooks.md): Replace the runner's built-in hooks with scripts of your own: the variables a build gets, and what each hook must do.
- [Run builds on macOS](https://docs-stg.outerlayer.ai/run-builds-on-macos.md): On a Mac, run the runner image on Docker Desktop, or use a small Linux VM when the Mac has no Docker. Either way builds run in containers of their own.
- [Run builds on Windows](https://docs-stg.outerlayer.ai/run-builds-on-windows.md): Isolated builds on a Windows machine need Docker Engine inside WSL2, or the runner image on Docker Desktop.
- [Build a repository's image from its devcontainer file](https://docs-stg.outerlayer.ai/build-image-from-devcontainer.md): outerlayer runner image builds the image a repository's builds run in, from the devcontainer file of the repository that governs it.
- [Troubleshoot builds](https://docs-stg.outerlayer.ai/troubleshoot-builds.md): Read the runner's log, find out from the work item why a build ended, look up its outcome, and fix refused signatures, releases that do not land and items that come back.
- [Security and limits](https://docs-stg.outerlayer.ai/build-security.md): What each way of isolating a build protects, how the host key and the item key limit a build, and what no isolation covers.
- [Invite your team](https://docs-stg.outerlayer.ai/invite-your-team.md): Add people to the organization, and have each of them sign in on their own machine.
- [API keys](https://docs-stg.outerlayer.ai/api-keys.md): Mint a key, choose its permissions, and give it to the CLI once.
- [Organization API](https://docs-stg.outerlayer.ai/organization-api.md): Manage members, roles, the audit log and control planes from a script, with a management API key.
- [Policy and validators](https://docs-stg.outerlayer.ai/policy-and-validators.md): Declare what evidence a change must carry, and how strict the verdict is, from files on the base branch.
- [Agent context](https://docs-stg.outerlayer.ai/agent-context.md): Keep agent instructions in AGENTS.md and skills in .agents/skills/. Nothing generated is committed.
- [Share instructions across repositories](https://docs-stg.outerlayer.ai/share-instructions-across-repositories.md): Keep agent instructions, policy and validators in one repository, and the one commit each of the others must make.
- [What leaves your machine](https://docs-stg.outerlayer.ai/what-leaves-your-machine.md): The privacy model: capture is local, upload is launch-gated, and session content is scrubbed before it is sent.
- [CLI overview](https://docs-stg.outerlayer.ai/reference/cli.md): Every user-facing outerlayer command, grouped by what it touches.
- [Capture commands](https://docs-stg.outerlayer.ai/reference/cli-capture.md): init, doctor, daemon and hooks: installing the capture hooks and keeping them healthy.
- [Cloud commands](https://docs-stg.outerlayer.ai/reference/cli-cloud.md): login, connect, logout and sync: signing in, choosing a repository's factory, and uploading launched sessions.
- [Work commands](https://docs-stg.outerlayer.ai/reference/cli-work.md): Start, remove and read what the factory is working on.
- [Spec commands](https://docs-stg.outerlayer.ai/reference/cli-spec.md): Find, file and edit the issue a spec lives in, through OuterLayer.
- [Runner commands](https://docs-stg.outerlayer.ai/reference/cli-runner.md): Start, stop and inspect the loop that takes work on this machine.
- [Emit commands](https://docs-stg.outerlayer.ai/reference/cli-emit.md): Record a named check, upload a proof artifact, record findings, report a step, or record a work item's acceptance criteria.
- [Context and tool commands](https://docs-stg.outerlayer.ai/reference/cli-context.md): context emit and mcp.
- [Environment variables](https://docs-stg.outerlayer.ai/reference/environment-variables.md): Every variable the CLI and its hooks read.
- [The config file](https://docs-stg.outerlayer.ai/reference/config-file.md): Every key in ~/.outerlayer/config.json.
- [The .outerlayer directory](https://docs-stg.outerlayer.ai/reference/outerlayer-directory.md): What lives in a repository's .outerlayer/ and which branch each file is read from.
- [Use the MCP server](https://docs-stg.outerlayer.ai/mcp.md): Give a chat client or coding agent read access to your sessions, costs, outcomes and work items.
- [Upgrade OuterLayer](https://docs-stg.outerlayer.ai/upgrade.md): What to run after a new CLI version, on a laptop, in a repository and on a build host, and the changes that need you to act.
- [Troubleshooting](https://docs-stg.outerlayer.ai/troubleshooting.md): Common setup errors and the command that fixes each.
- [Changelog](https://docs-stg.outerlayer.ai/changelog.md): What's new in OuterLayer: the dashboard, the CLI and self-hosted runners.
- [Self-host OuterLayer](https://docs-stg.outerlayer.ai/self-host/index.md): Run OuterLayer against your own Supabase. This page lists the Supabase Auth settings an install needs.
- [Introduction](https://docs-stg.outerlayer.ai/api-reference/introduction.md): Base URL, credentials, the factory header, errors and rate limits for the OuterLayer API.
- [OAuth protected-resource metadata](https://docs-stg.outerlayer.ai/api-reference/oauth/oauth-protected-resource-metadata.md): RFC 9728 protected-resource metadata for the MCP endpoints. Points MCP clients at the Supabase-backed authorization server; unauthenticated.
- [OAuth protected-resource metadata for the per-app MCP mount](https://docs-stg.outerlayer.ai/api-reference/oauth/oauth-protected-resource-metadata-for-the-per-app-mcp-mount.md): RFC 9728 protected-resource metadata for /v1/apps/{appId}/mcp. Points MCP clients at the Supabase-backed authorization server; unauthenticated.
- [Service health](https://docs-stg.outerlayer.ai/api-reference/health/service-health.md): Check if the gateway service is running. Returns healthy if all required environment variables are configured.
- [Files health](https://docs-stg.outerlayer.ai/api-reference/health/files-health.md): Check the health of the files service and its dependencies.
- [Ingestion health](https://docs-stg.outerlayer.ai/api-reference/health/ingestion-health.md): Check the health of the trace ingestion pipeline and its dependencies.
- [Fetch an agent session image blob via a signed token](https://docs-stg.outerlayer.ai/api-reference/agents/fetch-an-agent-session-image-blob-via-a-signed-token.md): Returns the raw bytes of a content-addressed agent-session image, authorized by a signed, expiring token minted on a session-detail response. Never accepts a raw sha256 — the token is the only capability.
- [Fetch an agent session image blob](https://docs-stg.outerlayer.ai/api-reference/agents/fetch-an-agent-session-image-blob.md): Returns the raw bytes of a content-addressed agent-session image (sha256). Scoped to the API key's organization and app.
- [Ingest coding-agent sessions (outerlayer sync)](https://docs-stg.outerlayer.ai/api-reference/agents/ingest-coding-agent-sessions-outerlayer-sync.md): Ingests a batch of canonical AgentSessions (schemaVersion 1) plus their content-addressed image blobs. Each session is tier-clamped to the organization ceiling, secret-scrubbed, and mapped to spans. Deterministic ids make re-sync idempotent. Sessions are validated individually: a malformed session i…
- [List API keys](https://docs-stg.outerlayer.ai/api-reference/api-keys/list-api-keys.md): Returns API keys for the authenticated organization. Plaintext is never returned on this endpoint — record it at creation time. A runner key bound to a host key carries `hostKey`: the key's fingerprint and when it was bound.
- [Create API key](https://docs-stg.outerlayer.ai/api-reference/api-keys/create-api-key.md): Creates a new API key. The plaintext key is returned EXACTLY ONCE in `data.plaintext_key` — record it immediately. Subsequent reads expose only metadata.
- [Revoke API key](https://docs-stg.outerlayer.ai/api-reference/api-keys/revoke-api-key.md): Revokes the API key and removes its local metadata row. Note: a brief revocation lag may occur — the gateway caches verified credentials for a short TTL, so a freshly-revoked key may still verify until the cache expires.
- [Change API key permissions](https://docs-stg.outerlayer.ai/api-reference/api-keys/change-api-key-permissions.md): Replaces the key's permissions with the set in the body. The caller must hold every permission it grants. A key already in use picks up the change after the gateway's short credential cache expires.
- [Clear a runner key's host binding](https://docs-stg.outerlayer.ai/api-reference/api-keys/clear-a-runner-keys-host-binding.md): Clears the host key a runner key is bound to, so its next signed claim binds the key of whichever host sends it. Use it to move a runner to a new host. The change is written to the org audit log. Clearing a key that is not bound changes nothing. A key already in use picks up the change at once: the…
- [List apps](https://docs-stg.outerlayer.ai/api-reference/apps/list-apps.md): Returns factories for the authenticated organization, newest first. Use `?name=<exact>` to look up a specific factory by name without paginating.
- [Create app](https://docs-stg.outerlayer.ai/api-reference/apps/create-app.md): Creates a new app in the authenticated organization.
- [Get app](https://docs-stg.outerlayer.ai/api-reference/apps/get-app.md): Returns a single app by ID.
- [Delete app](https://docs-stg.outerlayer.ai/api-reference/apps/delete-app.md): Deletes an app. Cascades to all child rows via ON DELETE CASCADE (git_connection, git_branch, api_key, etc.).
- [Update app](https://docs-stg.outerlayer.ai/api-reference/apps/update-app.md): Updates writable fields on an app. PATCH semantics — any subset of `name`, `display_name`, `runner_updates`, `auto_resolve_conflicts` may be sent. `display_name` is the optional free-form UI label; send `null` to clear it and fall back to `name`. `runner_updates` chooses the CLI version heartbeats n…
- [Get git connection status for an app](https://docs-stg.outerlayer.ai/api-reference/apps/get-git-connection-status-for-an-app.md): Returns the current git connection state. `connected: true` means the factory has completed the GitHub App install (OAuth handshake). `repository` is null between install-done and repo-picked.
- [List branches in a repository](https://docs-stg.outerlayer.ai/api-reference/apps/list-branches-in-a-repository.md): Returns the list of branch names for `repository` (passed as a query param because the value contains a slash). Use after `list-app-git-repositories` to populate a branch picker before linking.
- [Mint an OAuth authorization URL for git-provider connect](https://docs-stg.outerlayer.ai/api-reference/apps/mint-an-oauth-authorization-url-for-git-provider-connect.md): Returns a GitHub App install authorization URL plus a signed state token. Flow for a signed-in person:
- [Link a repository and branch to an app](https://docs-stg.outerlayer.ai/api-reference/apps/link-a-repository-and-branch-to-an-app.md): Adds the chosen repository + branch to the app, or updates the watched branch when the app already holds that repository. Each push to `branch` syncs the app's context from that branch.
- [Clear the linked repository and branch](https://docs-stg.outerlayer.ai/api-reference/apps/clear-the-linked-repository-and-branch.md): Deletes the linked repository's git_connection row and its git_branch row. The GitHub App install is kept on git_installation, so the user can re-link without re-clicking the install URL.
- [List every repository linked to the factory, with its branches](https://docs-stg.outerlayer.ai/api-reference/apps/list-every-repository-linked-to-the-factory-with-its-branches.md): Lists each repository linked to the factory, ordered by when it was linked. `repository` is the name as stored, which is GitHub's own spelling; compare it case-insensitively. `branches` holds the branches the factory watches for that repository. A factory with no linked repository returns an empty l…
- [List repositories accessible to the app's git installations](https://docs-stg.outerlayer.ai/api-reference/apps/list-repositories-accessible-to-the-apps-git-installations.md): Returns repositories the factory's GitHub App installations can see (the App's `/installation/repositories`), one installation per GitHub organization. Each item names its `installation_id`, its `owner` and whether that installation is `suspended`. A suspended installation lists no repositories, bec…
- [Remove a GitHub organization from the factory](https://docs-stg.outerlayer.ai/api-reference/apps/remove-a-github-organization-from-the-factory.md): Removes one GitHub App installation from this factory, in this order: the factory's git_branch rows for the installation's repositories, those git_connection rows, then the factory's git_installation row. It never calls GitHub, so the App stays installed on the GitHub organization, and it touches no…
- [Emit an artifact (evidence for a pull request)](https://docs-stg.outerlayer.ai/api-reference/artifacts/emit-an-artifact-evidence-for-a-pull-request.md): Accepts one artifact — a screenshot, recording, report, or log emitted as proof that a change works — plus its content-addressed blob. The artifact anchors to a pull request directly (prNumber), through the recorded session that produced it, or through git context resolved to a PR later; a request w…
- [Get capabilities](https://docs-stg.outerlayer.ai/api-reference/capabilities/get-capabilities.md): Returns a map of available API endpoints for the current target (cloud or local). Use this to discover which features are supported before calling other endpoints.
- [List context changes](https://docs-stg.outerlayer.ai/api-reference/context/list-context-changes.md): Returns the commits that changed `.outerlayer/` in the repository the app's context comes from, newest first: the designated control-plane source for a governed factory, the factory's own connected branch otherwise. `source` says which. `snapshots` is deprecated.
- [Get control plane](https://docs-stg.outerlayer.ai/api-reference/context/get-control-plane.md): Returns the control plane that governs the given repository: a factory's control plane, the one it names else its first-linked repository, governs every other repository the factory links. `source` holds its repository, ref and the commit the ref resolved to, `state` is `governed`, and `sources` hol…
- [Read a factory's control plane](https://docs-stg.outerlayer.ai/api-reference/context/read-a-factorys-control-plane.md): Returns the factory's designated control plane, or `data: null` when none is designated. Requires 'governance.read'.
- [Designate a factory's control plane](https://docs-stg.outerlayer.ai/api-reference/context/designate-a-factorys-control-plane.md): Marks one of the factory's linked repositories as its control plane, replacing the one it had. The control plane governs every other repository the factory links. The repository is read before it is stored: its ref is resolved to a commit and `.outerlayer/config.json` is parsed at that commit. A mis…
- [Revoke a factory's control plane](https://docs-stg.outerlayer.ai/api-reference/context/revoke-a-factorys-control-plane.md): Revokes the factory's designated control plane. Requires 'governance.delete'.
- [Record a work item's acceptance criteria](https://docs-stg.outerlayer.ai/api-reference/criteria/record-a-work-items-acceptance-criteria.md): Records the work item's acceptance criteria as one list of 1 to 200 criteria, each with an id, its text and the artifact kind that proves it (or null). The list is the only source for the item's Criteria tab, its count and its status. Every recorded list is kept with who recorded it and when; the cu…
- [Emit a check result (pass/fail evidence for a work item)](https://docs-stg.outerlayer.ai/api-reference/emitted-results/emit-a-check-result-passfail-evidence-for-a-work-item.md): Accepts one emitted result — one recorded pass or fail, named after the validator that declares it. A check that ran in your own CI or compute carries its run URL as the proof link. A person recording a judgment carries the one sentence they typed instead. A failing result needs one of the two. Ever…
- [Change a check's status](https://docs-stg.outerlayer.ai/api-reference/emitted-results/change-a-checks-status.md): Records a new pass or fail under the same check name and work item as an existing check, so the caller need not restate the anchor. Nothing is ever updated in place: the earlier outcome and the new one both survive, and the check's status is the latest of them. A credential that is not a person's ow…
- [Record a batch of findings on a work item](https://docs-stg.outerlayer.ai/api-reference/findings/record-a-batch-of-findings-on-a-work-item.md): Accepts a batch of 1 to 500 findings — problems an agent hit in the factory, each with a category — and links every one to one or more factory-level problems. A finding joins the problem that owns one of its strict keys; otherwise it links the problems it names with a reason, or records a new one wi…
- [Findings and time lost per category](https://docs-stg.outerlayer.ai/api-reference/findings/findings-and-time-lost-per-category.md): One row per category, all six always present: findings, distinct work items, minutes lost (null when none is measured) and findings with no measured time. It reads findings, not problems, so a finding that reports several problems counts once. `since` and `until` narrow to findings recorded in that…
- [Rank a factory's problems](https://docs-stg.outerlayer.ai/api-reference/findings/rank-a-factorys-problems.md): The factory's problems, ranked by the work items they hit (`reports`, the default) or by time lost (`minutesLost`). A problem is a factory-level issue that findings report, such as a check that keeps failing. Each row carries the strict keys that join a finding to it: the exact text to search for in…
- [One problem with its findings](https://docs-stg.outerlayer.ai/api-reference/findings/one-problem-with-its-findings.md): One problem's figures, as `GET /v1/problems` returns them (`findingCount` is the row's `findings`), plus its findings, newest recorded first, at most 100 (`findingsTruncated` says there are more). Each finding carries its cause, suggestion, command, error line, the rule it relates to, how it joined…
- [A work item's findings](https://docs-stg.outerlayer.ai/api-reference/findings/a-work-items-findings.md): One work item's findings, newest recorded first and at most the newest 500 (`pagination.truncated` is true when there are more), each with the problems it reports. `workItemId` is the item's id or its number in this factory. A key scoped to one work item can read that item's findings and no other's.
- [List the factory's runner hosts](https://docs-stg.outerlayer.ai/api-reference/hosts/list-the-factorys-runner-hosts.md): Every host that has sent at least one heartbeat, ordered by host name. Each carries the CLI version, the runner protocol and slots it last reported, its last heartbeat time, its last successful request for work, its last error, its last self-update (the versions it moved between, how it ended, and w…
- [Report a heartbeat from a runner host](https://docs-stg.outerlayer.ai/api-reference/hosts/report-a-heartbeat-from-a-runner-host.md): Upserts one row for `host`, stamping the platform's own clock for the heartbeat time and, when `workRequest` is present, for the last success or the last error. `runnerProtocol` is the gateway contract the runner was built against; a heartbeat without it is stored as 0, below every minimum. `workReq…
- [List the factories the login token can use](https://docs-stg.outerlayer.ai/api-reference/account/list-the-factories-the-login-token-can-use.md): Lists every factory where the login token's owner has an active membership and can act, with the organization it belongs to. Needs only a login token, and no factory named: a factory key is refused with 401. With `repository`, each factory also says whether that repository is linked to it: `true`, `…
- [Get a cost/session/error breakdown by dimension](https://docs-stg.outerlayer.ai/api-reference/metrics/get-a-costsessionerror-breakdown-by-dimension.md): Ranks `branch`, `agent_type`, `worker_kind`, `model`, or `tool` by spend/volume for `from`..`to` (UTC calendar dates, default trailing 30 days). `branch`/`agent_type`/`worker_kind`/`model` items carry `sessions` + `costUsd` + `toolErrorRate`; `tool` items carry `requests` + `toolErrorRate` instead —…
- [Compare metrics across two windows](https://docs-stg.outerlayer.ai/api-reference/metrics/compare-metrics-across-two-windows.md): Correlational comparison — not causal attribution: returns fleet-behavior tiles for two EXPLICIT, caller-chosen windows (`a`, `b`; UTC calendar dates), side by side. Neither window defaults — this is for "before vs. after a specific change" (e.g. either side of a context sync from `GET /v1/context/c…
- [Get per-model stats](https://docs-stg.outerlayer.ai/api-reference/metrics/get-per-model-stats.md): Returns metered token spend, request counts, and latency per model for the authenticated app, over `from`..`to` (UTC calendar dates, default trailing 7 days).
- [Get fleet overview](https://docs-stg.outerlayer.ai/api-reference/metrics/get-fleet-overview.md): Returns fleet-wide agent behavior tiles (sessions, tool-error rate, hands-on rate, spend, and more) for `from`..`to` (UTC calendar dates, default trailing 30 days), each as a `{ current, prior }` pair against the equal-length preceding period. Call twice with explicit windows to compare before/after…
- [Get the daily sessions/cost/quality trend](https://docs-stg.outerlayer.ai/api-reference/metrics/get-the-daily-sessionscostquality-trend.md): Daily sessions, spend, tool-error rate, and clean-session rate for `from`..`to` (UTC calendar dates, default trailing 30 days) — one point per day WITH activity; a day with zero sessions has no point, so the series is not dense over the window. From the SAME agent-session population as `/v1/metrics/…
- [List an org's audit log](https://docs-stg.outerlayer.ai/api-reference/org-management/list-an-orgs-audit-log.md): Lists the org's audit trail, newest first. Requires the `audit.read` management-API-key permission and the Enterprise `audit_log` plan feature.
- [Export an org's audit log as CSV](https://docs-stg.outerlayer.ai/api-reference/org-management/export-an-orgs-audit-log-as-csv.md): Exports the org's full audit trail as CSV, oldest first, capped at 50,000 rows. Requires 'audit.read' and the Enterprise `audit_log` plan feature.
- [Get one audit log entry](https://docs-stg.outerlayer.ai/api-reference/org-management/get-one-audit-log-entry.md): Returns the full detail of one audit log entry in this org. Requires 'audit.read' and the Enterprise `audit_log` plan feature.
- [List org members and pending invites](https://docs-stg.outerlayer.ai/api-reference/org-management/list-org-members-and-pending-invites.md): Returns active memberships and pending invites for the org. Requires the `org.read` management-API-key permission.
- [Invite an org member](https://docs-stg.outerlayer.ai/api-reference/org-management/invite-an-org-member.md): Sends an org invite. Requires 'members.insert'. `custom_role_id` gives the invitee a custom role (requires the `custom_roles` entitlement). Per-app roles are not set here: a non-empty `appRoles` is refused with 400 `app_roles_not_supported`.
- [Resend a pending invite](https://docs-stg.outerlayer.ai/api-reference/org-management/resend-a-pending-invite.md): Resends the invite email for a pending membership. Requires 'members.insert'.
- [Remove a member from the org](https://docs-stg.outerlayer.ai/api-reference/org-management/remove-a-member-from-the-org.md): Removes a member from the org. Requires 'members.delete'.
- [Change a member's role](https://docs-stg.outerlayer.ai/api-reference/org-management/change-a-members-role.md): Changes a member's role: a built-in role, or a custom role with `custom_role_id` (requires the `custom_roles` entitlement). Requires 'members.update'.
- [List built-in org roles](https://docs-stg.outerlayer.ai/api-reference/org-management/list-built-in-org-roles.md): Returns the built-in role catalog. Requires 'roles.read'.
- [Get LLM pricing](https://docs-stg.outerlayer.ai/api-reference/pricing/get-llm-pricing.md): Returns per-model pricing for cost calculation. Response is a dynamic map keyed by model ID (e.g. `gpt-5`, `claude-opus-4-6`). Prices are per 1,000 tokens.
- [Get session→PR attribution merged with cost](https://docs-stg.outerlayer.ai/api-reference/prs/get-session→pr-attribution-merged-with-cost.md): How many sessions produced PRs, which branches/PR numbers they attribute to, which needed mid-session human steering, and what each attributed (repo, branch, PR number) group cost — for the app's dominant repo. Deliberately NOT date-windowed: a PR's session set and cost include work that predates it…
- [Report the GitHub App access builds need on each of the factory's repositories](https://docs-stg.outerlayer.ai/api-reference/repositories/report-the-github-app-access-builds-need-on-each-of-the-factorys-repositories.md): Lists each repository connected to the caller's factory. `missingPermissions` names each permission builds need that the GitHub App installation has not accepted, compared by level, so `read` does not satisfy `write`. Builds need contents, pull requests and issues write, and actions, checks, commit…
- [Read a runner key's host binding](https://docs-stg.outerlayer.ai/api-reference/work-items/read-a-runner-keys-host-binding.md): Returns whether the calling runner key is bound to a host key, and the bound key's fingerprint and binding time. A bound key's request must be signed by its host key like any other, so a host the key is not bound to gets `runner_key_signature_invalid` instead of this answer.
- [List live work items](https://docs-stg.outerlayer.ai/api-reference/work-items/list-live-work-items.md): Every live (not withdrawn) work item for this factory, filterable by repository, stage, and section. Page size 100; follow `pagination.cursor` for the rest. `issue`, with `repository`, narrows the page to the single item that subject answers to — a pull request whose closing issue is known resolves…
- [Add an issue to Work](https://docs-stg.outerlayer.ai/api-reference/work-items/add-an-issue-to-work.md): Records that a named source is working on an issue and puts it on Work, with no build request, so no host takes it (`outerlayer work build --local`). The attestor is resolved by the server (a recorded session, then a CI run, then the caller's own membership, then the API key itself) and never accept…
- [Request a host build an item](https://docs-stg.outerlayer.ai/api-reference/work-items/request-a-host-build-an-item.md): Records a `build-requested` attestation naming who asked and when — the fact `claim_work_item` and the queue listings read to decide whether a host may pick the item up. With no open pull request it feeds the implement queue; with an open pull request whose general thread waits on an agent it feeds…
- [Declare a session's pull request onto its work item](https://docs-stg.outerlayer.ai/api-reference/work-items/declare-a-sessions-pull-request-onto-its-work-item.md): Records that the pull request opened by a session on a work item belongs to that item — the same fact a session's transcript `pr-link` line records on sync, written through the one path so a pull request never links a work item any other way. Idempotent: declaring the same pull request twice is a no…
- [Report that a step has started on a work item](https://docs-stg.outerlayer.ai/api-reference/work-items/report-that-a-step-has-started-on-a-work-item.md): Records that an agent started a step, with any name of 1 to 80 characters on one line, and the time it started. The item is named by its number in this factory. Who started the step is derived from the credential: the host's label when the caller holds the item's live host lease, otherwise the displ…
- [Link a session to a work item](https://docs-stg.outerlayer.ai/api-reference/work-items/link-a-session-to-a-work-item.md): Links the calling session to an item that already exists, writing the same `work_item_session` link and `session-linked` attestation an addition writes as its side effect — without admitting the item or recording a `work-added` attestation. Idempotent: linking the same session to the same item twice…
- [Read one work item](https://docs-stg.outerlayer.ai/api-reference/work-items/read-one-work-item.md): The stage, section, gate ledger (with the attestation ids behind each gate), `evaluation` (the newest evidence verdict, its sentence, when it was recorded, and each row that failed or has no result yet; `null` before the first evaluation), linked pull requests and sessions (each with `claimId`, the…
- [List a work item's artifacts](https://docs-stg.outerlayer.ai/api-reference/work-items/list-a-work-items-artifacts.md): The live artifacts of one work item, oldest first: every artifact anchored to a pull request declared onto the item, and every artifact emitted from a session linked to it. An artifact a later one replaced is left out. Each carries its kind, caption, the criterion it is bound to, its pull request, a…
- [List checks recorded on a work item since a point](https://docs-stg.outerlayer.ai/api-reference/work-items/list-checks-recorded-on-a-work-item-since-a-point.md): Every check recorded against this work item after the point `since` names, oldest first, including both the fail and the later pass on the same check. The caller keeps its own place: we hold no per-caller state, so the same `since` always returns the same answer and a client that loses its place can…
- [List the checks currently open on a work item](https://docs-stg.outerlayer.ai/api-reference/work-items/list-the-checks-currently-open-on-a-work-item.md): Every check recorded against this work item, reduced to the latest row per name — what is open right now. A check a person recorded carries their sentence and their name alongside the outcome. An item holding more recorded rows than one read can return is answered from its most recent ones, and `pag…
- [Claim a work item](https://docs-stg.outerlayer.ai/api-reference/work-items/claim-a-work-item.md): Records a lease for the named host and returns an item key for it. The body must carry `runnerProtocol`, at or above the gateway's minimum, or the claim is refused with `runner_upgrade_required` (426) and no lease is recorded. A runner key that is not yet bound to a host key binds to the one in `hos…
- [Release a host's claim on a work item](https://docs-stg.outerlayer.ai/api-reference/work-items/release-a-hosts-claim-on-a-work-item.md): Marks the caller's own lease released, optionally with an `outcome`, the `stage` the attempt ended in, its `exitCode`, a one-line `reason` (at most 200 characters, no line break), and an `environment` recording what the attempt ran in: its `isolation` (`container`, `vm` or `shared-user`), the recipe…
- [Renew a host's claim on a work item](https://docs-stg.outerlayer.ai/api-reference/work-items/renew-a-hosts-claim-on-a-work-item.md): Extends the live lease the calling key holds, whatever `host` the body names. `claim_expired` (410) when no live lease exists; `claim_not_held` (403) when a live lease is held by a different key.
- [Stop a work item's host build](https://docs-stg.outerlayer.ai/api-reference/work-items/stop-a-work-items-host-build.md): Asks for the item's live host build to stop. The request is recorded on the claim with who asked, when, and the note, and reaches the build's host in its next heartbeat; the host ends the build and releases the claim as `stopped`. A build stopped this way uses up its build request, so the item is no…
- [Issue a GitHub token for a work item's repository or its control plane](https://docs-stg.outerlayer.ai/api-reference/work-items/issue-a-github-token-for-a-work-items-repository-or-its-control-plane.md): Returns a GitHub App installation token limited to one repository of the item's claim: the one named in `repository`, or the claim's primary. `access` is `read` (contents, issues, pull requests, actions, checks and statuses, read only) or `push` (contents write, plus workflows write when the reposit…
- [Read a host attempt's runner log](https://docs-stg.outerlayer.ai/api-reference/work-items/read-a-host-attempts-runner-log.md): The runner's own log for one attempt a host made on the item: what the runner did around the agent (claiming, provisioning, starting and ending the command, syncing, cleaning up and releasing), scrubbed on the host, plus the tail of the stage log when the attempt ended in provision, sync, cleanup or…
- [Post a comment on a work item's general thread or a criterion thread](https://docs-stg.outerlayer.ai/api-reference/work-items/post-a-comment-on-a-work-items-general-thread-or-a-criterion-thread.md): Posts one comment. Omitting `criterion` posts on the item's general thread; naming one posts on that criterion's own thread. `pass`/`fail` are a person's verdict on the whole item: they are refused on a criterion thread (`verdict_on_criterion`) and from an agent session or a machine key (`verdict_ne…
- [Send review notes on several criteria as one agent job](https://docs-stg.outerlayer.ai/api-reference/work-items/send-review-notes-on-several-criteria-as-one-agent-job.md): Stores one `request` comment on each named criterion's thread and one `fail` on the item's general thread whose body lists the notes, in a single statement: either every row is stored or none is. Each `request` leaves its criterion thread waiting on an agent. Every comment of the send carries `clien…
- [Open or edit a work item's pull request](https://docs-stg.outerlayer.ai/api-reference/work-items/open-or-edit-a-work-items-pull-request.md): Opens the pull request for the work item a build is working on, from the branch its live claim named in one of the claim's repositories, into that repository's default branch, as the factory's GitHub App, or edits the title and body of the open pull request already on that branch, whoever opened it.…
- [Withdraw a work item's declaration of a pull request](https://docs-stg.outerlayer.ai/api-reference/work-items/withdraw-a-work-items-declaration-of-a-pull-request.md): Removes one work item's declaration of one pull request and leaves any other item's declaration of it. `repository` is one URL-encoded path segment. Only a person can withdraw (`withdraw_needs_person` otherwise). The pull request and the item are nominated for an evidence comment refresh.
- [Remove an addition from Work](https://docs-stg.outerlayer.ai/api-reference/work-items/remove-an-addition-from-work.md): Withdraws the caller's own live addition of this item, recording the reason — never deletes anything. With no addition of their own and `work.update` on the factory, removes every live addition instead. The item itself is withdrawn only once no live addition remains on it or on any pull request link…
- [A work item's general thread and its criterion threads](https://docs-stg.outerlayer.ai/api-reference/work-items/a-work-items-general-thread-and-its-criterion-threads.md): The item's general thread plus one thread per acceptance criterion that carries proof or a comment — each with its derived `waitingOn`, its latest verdict, its proof (if any) and every comment, oldest first.
- [List agent sessions](https://docs-stg.outerlayer.ai/api-reference/sessions/list-agent-sessions.md): Returns a filtered, paginated list of agent-coding sessions. Without `sessions.read_team`, actor identities are anonymized and `actor` filters are rejected. When no repo or repoScope is given, results are scoped to the app's dominant repo (the repo with the highest total spend); pass `repo` to pin a…
- [Get agent session detail](https://docs-stg.outerlayer.ai/api-reference/sessions/get-agent-session-detail.md): Returns the full span tree + rollup identity for one session. Span count is capped — `truncated: true` means only the FIRST spans (not necessarily the last) are included. A missing trace and a trace from another app return the identical 404 — there is no existence oracle for a transcript the caller…
- [File a spec as an issue](https://docs-stg.outerlayer.ai/api-reference/specs/file-a-spec-as-an-issue.md): Creates an issue in the factory's tracker with the given title and Markdown body, and answers with its key, URL and the `outerlayer work build` command that builds it. Where to file is decided from what the factory connected: when it could be more than one place the request is refused with the choic…
- [Search issues a spec might duplicate](https://docs-stg.outerlayer.ai/api-reference/specs/search-issues-a-spec-might-duplicate.md): Issues in the factory's tracker whose title or body match `q`, open and closed alike, newest activity first. A closed issue is a match too: it may already hold the decision.
- [Where a spec would be filed](https://docs-stg.outerlayer.ai/api-reference/specs/where-a-spec-would-be-filed.md): Names the tracker this factory files specs in, every tracker it could, the sources the tracker's connection covers, the factory's repositories, and whether the factory can file there now (`canFile`). A GitHub factory with no admin approval of the App's issue permission answers `canFile: false`.
- [Replace a spec's body](https://docs-stg.outerlayer.ai/api-reference/specs/replace-a-specs-body.md): Replaces the body of an existing issue in the factory's tracker. `key` is the issue's key, URL-encoded: a GitHub key such as `acme/api#12` contains `/` and `#`. Send the `updatedAt` you read as `expectedUpdatedAt` and the edit is refused with `conflict` when the issue has changed since. The tracker…

## OpenAPI Specs

- [openapi](/openapi.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.