# OuterLayer

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

- [What OuterLayer is](https://docs.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.outerlayer.ai/quickstart.md): From signup to your first issue built into a pull request, from the Work page, in about ten minutes.
- [Key concepts](https://docs.outerlayer.ai/concepts.md): The words every other page uses, each defined once.
- [How a work item flows](https://docs.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.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.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.outerlayer.ai/connect-a-tracker.md): Read issues from a Linear workspace or a Jira site into the Work page, next to GitHub.
- [Launch a session](https://docs.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.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.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.
- [Record a check](https://docs.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.outerlayer.ai/declare-a-pull-request.md): Tell the factory which pull request a session's work landed in.
- [Findings](https://docs.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.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.outerlayer.ai/set-up-a-host.md): Install the runner on one machine, give it a key and Claude's credential, and build your first item.
- [Run a host as a service](https://docs.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.
- [Container and microVM builds](https://docs.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.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.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.outerlayer.ai/run-builds-on-macos.md): On a Mac the runner lives in a small Linux VM, so builds still run in containers of their own.
- [Run builds on Windows](https://docs.outerlayer.ai/run-builds-on-windows.md): Isolated builds on a Windows machine need Docker Engine inside WSL2, not Docker Desktop.
- [Build a repository's image from its devcontainer file](https://docs.outerlayer.ai/build-image-from-devcontainer.md): outerlayer runner image builds the image a repository's builds run in, from the devcontainer file on its default branch.
- [Troubleshoot builds](https://docs.outerlayer.ai/troubleshoot-builds.md): Read the runner's log, look up how a build ended, and fix refused signatures, releases that do not land and items that come back.
- [Security and limits](https://docs.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.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.outerlayer.ai/api-keys.md): Mint a key, choose its permissions, and give it to the CLI once.
- [Organization API](https://docs.outerlayer.ai/organization-api.md): Manage members, roles, the audit log and context sources from a script, with a management API key.
- [Policy and validators](https://docs.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.outerlayer.ai/agent-context.md): Keep one source of agent instructions in .outerlayer/ and compile it into each tool's native files.
- [Share instructions across repositories](https://docs.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.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.outerlayer.ai/reference/cli.md): Every user-facing outerlayer command, grouped by what it touches.
- [Capture commands](https://docs.outerlayer.ai/reference/cli-capture.md): init, doctor, daemon and hooks: installing the capture hooks and keeping them healthy.
- [Cloud commands](https://docs.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.outerlayer.ai/reference/cli-work.md): Start, remove and read what the factory is working on.
- [Runner commands](https://docs.outerlayer.ai/reference/cli-runner.md): Start, stop and inspect the loop that takes work on this machine.
- [Emit commands](https://docs.outerlayer.ai/reference/cli-emit.md): Record a named check, upload a proof artifact, record findings, or record a work item's acceptance criteria.
- [Context and tool commands](https://docs.outerlayer.ai/reference/cli-context.md): context emit, context materialize, import, and mcp.
- [Environment variables](https://docs.outerlayer.ai/reference/environment-variables.md): Every variable the CLI and its hooks read.
- [The config file](https://docs.outerlayer.ai/reference/config-file.md): Every key in ~/.outerlayer/config.json.
- [The .outerlayer directory](https://docs.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.outerlayer.ai/mcp.md): Give a chat client or coding agent read access to your sessions, costs, outcomes and work items.
- [Troubleshooting](https://docs.outerlayer.ai/troubleshooting.md): Common setup errors and the command that fixes each.
- [Self-host OuterLayer](https://docs.outerlayer.ai/self-host/index.md): Self-hosting is coming soon.
- [Introduction](https://docs.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.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.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.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.outerlayer.ai/api-reference/health/files-health.md): Check the health of the files service and its dependencies.
- [Ingestion health](https://docs.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.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.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.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.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.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.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.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.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.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.outerlayer.ai/api-reference/apps/create-app.md): Creates a new app in the authenticated organization.
- [Get app](https://docs.outerlayer.ai/api-reference/apps/get-app.md): Returns a single app by ID.
- [Delete app](https://docs.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.outerlayer.ai/api-reference/apps/update-app.md): Updates writable fields on an app. PATCH semantics — any subset of `name`, `display_name`, `runner_updates` 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 name to this factory's runn…
- [Get git connection status for an app](https://docs.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.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.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.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.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.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 installation](https://docs.outerlayer.ai/api-reference/apps/list-repositories-accessible-to-the-apps-git-installation.md): Returns repositories the linked GitHub App installation can see (the App's `/installation/repositories`).
- [Emit an artifact (evidence for a pull request)](https://docs.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.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.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 context source](https://docs.outerlayer.ai/api-reference/context/get-context-source.md): Returns the designated context sources of every factory the given repository is attached to. An empty `sources` list means the repository is self-sourced — its own tree governs itself — which is a normal, first-class answer rather than an error.
- [Read a factory's context source](https://docs.outerlayer.ai/api-reference/context/read-a-factorys-context-source.md): Returns the factory's designated context source, or `data: null` when none is designated. Requires 'governance.read'.
- [Designate a factory's context source](https://docs.outerlayer.ai/api-reference/context/designate-a-factorys-context-source.md): Designates the repository the factory's `.outerlayer/` context comes from. 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 missing config is accepted — it governs nothing yet. Requires 'governance.insert'.
- [Revoke a factory's context source](https://docs.outerlayer.ai/api-reference/context/revoke-a-factorys-context-source.md): Revokes the factory's designated context source. Requires 'governance.delete'.
- [Change a factory context source's require-a-pull-request setting](https://docs.outerlayer.ai/api-reference/context/change-a-factory-context-sources-require-a-pull-request-setting.md): Changes whether saves to the context this source supplies must go through a pull request. Requires 'governance.insert'.
- [Record a work item's acceptance criteria](https://docs.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.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.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.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 upserts every one on (work item, client id): a re-emitted id replaces that finding in place rather than adding a second one. A schemaVersion 1 batch is refused with a message to upgrade the CLI. V…
- [List the factory's runner hosts](https://docs.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.outerlayer.ai/api-reference/work-items/list-live-work-items.md): Every live (not withdrawn) work item for this factory, oldest-computed first, 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 i…
- [Add an issue to Work](https://docs.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.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 implement queue's listing read to decide whether a host may pick the item up. Adds the item to Work first (admitting it, the same as `POST /v1/work-items`) when `subject` names one not already ther…
- [Declare a session's pull request onto its work item](https://docs.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…
- [Link a session to a work item](https://docs.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.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, every addition (live or r…
- [List checks recorded on a work item since a point](https://docs.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.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.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.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.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.
- [Issue a GitHub token for a work item's repository](https://docs.outerlayer.ai/api-reference/work-items/issue-a-github-token-for-a-work-items-repository.md): Returns a GitHub App installation token limited to the item's repository. `access` is `read` (contents, issues, pull requests, actions, checks and statuses, read only) or `push` (contents write, plus workflows write when the repository default branch's `.outerlayer/policy.yaml` sets `build.workflows…
- [Post a comment on a work item's general thread or a criterion thread](https://docs.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.outerlayer.ai/api-reference/work-items/send-review-notes-on-several-criteria-as-one-agent-job.md): Stores one plain 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. The `fail` is what asks an agent to amend, so one send starts one job. Only a person can send notes (`verdic…
- [Open or edit a work item's pull request](https://docs.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 into the 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. The route takes no branch and no pul…
- [Remove an addition from Work](https://docs.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.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.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.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…

## OpenAPI Specs

- [openapi](/openapi.yaml)


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