> ## Documentation Index > Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Read one work item > 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 host attempt it ran in, or `null` for a session linked any other way), every addition (live or removed) recorded against this item, `buildRequests` (every build request, used or not, each with the `instructions` its requester gave the agent or `null`), the live claim — with `holderKind` (`host` or `session`) and, for a session lease, `sessionId` — and `claims`, every lease this item has ever had with its `id` (the attempt's name, which `GET /v1/work-items/{workItemId}/claims/{claimId}/log` takes), its holder kind, `buildRequestId` (the `id` of the build request it answers), session id for a session lease, its outcome, the step it ended in (`stage`), the exit code of the process that ended it (`exitCode`), a host-written reason, and `environment` (what the attempt ran in: its isolation, the recipe and image, the hosts it reached and the ranges refused, the names of the variables it was given, the names of the destinations it called, the kinds of repository token it used, `commitIdentity` (whether its commits were authored by the App or the host, and whether the requester was credited) and `controlPlane` (the control-plane repository and commit a governed build received its instructions from; `null` for a self-governed build); `null` for a lease that recorded none). Both the live claim and every past lease also carry `apiKeyName` (the key that took it) and `requestedByKind`/`requestedByName` (who asked for the build it answers — a member or a key, resolved once when the lease was written); no membership or key id is ever included. `criteria` is the item's current recorded acceptance criteria — `drafted` (the build wrote them from the issue description), `recordedAt`, `recordedBy` and `items` of `id`, `text` and `proof` — or `null` when none are recorded. `checks` is every check open on the item, the latest row per name, each with its result, sentence, link and `items`, its check items (one per thing the check judged, with its own result and reason; `null` when the recorder sent none). `issue` is the issue the item wraps, as the dashboard last copied it from its tracker: its `url`, `state`, Markdown `body`, `author`, `openedAt` and `labels`, with `syncedAt` and `syncStatus` saying how current the copy is. It is how a build reads a Linear or Jira issue it holds no credential for. ## OpenAPI ````yaml /openapi.yaml get /v1/work-items/{workItemId} openapi: 3.0.3 info: contact: email: hello@outerlayer.ai url: https://www.outerlayer.ai description: >- The OuterLayer Gateway API lets you ingest coding-agent sessions and record evidence of work programmatically. Most teams reach it through the `outerlayer` CLI, which calls it for them. Call it directly to build your own integration or to automate what the dashboard does. Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation window; anything additive lands on the current prefix. Vocabulary: the dashboard calls this API's `app` a **factory** — the unit that owns a set of repositories, the agent sessions worked on them, and the evidence they produce. They are the same entity. The API keeps `app` in its paths, headers, and field names because those are a published contract; only the product surface was renamed. title: OuterLayer Gateway API version: '1.0' servers: - description: Production (OuterLayer Cloud) url: https://api.outerlayer.ai - description: Local dev server (self-hosted gateway) url: http://localhost:9418 security: - AppId: [] BearerAuth: [] tags: - description: >- What a CLI login token can read about its owner without naming a factory, such as the factories they can use. name: Account - description: >- Coding-agent session ingest (outerlayer sync) and content-addressed session images. name: Agents - description: >- Evidence artifacts (screenshots, recordings, reports, logs) emitted as proof of a change and anchored to pull requests. name: Artifacts - description: >- Pass/fail outcomes of checks run in your own CI or compute, anchored to pull requests with the run URL as proof. name: Emitted Results - description: >- The acceptance criteria of a work item, recorded as one list. The Criteria tab, its count and the item status read that list. name: Criteria - description: >- What any agent found wrong about a change under review or about a rule it ran on, recorded on a work item. name: Findings - description: >- Find, file and edit the issue a spec lives in, through OuterLayer, with no tracker credential on the caller's side. name: Specs - description: >- Add or remove a source's statement that it is working on an issue or pull request, and read what is currently live. name: Work Items - description: >- What the factory's GitHub App installation lets builds do on each connected repository, and whether each default branch requires a pull request. name: Repositories - description: >- A runner host's heartbeat — its CLI version, slots and last request for work — and the factory's list of hosts with a derived status. name: Hosts - description: Query server feature availability. name: Capabilities - description: Per-model LLM pricing data. Public, unauthenticated. name: Pricing - description: >- Create, list, and revoke factory API keys. Plaintext returned exactly once at creation. name: API Keys - description: >- Factory CRUD — a factory is owned by an organization and is the unit every other resource hangs off. Lets a headless agent provision one without the dashboard. name: Apps - description: >- Agent-coding session list and full transcript reads, with actor-privacy controls for machine keys. name: Sessions - description: >- Per-model token spend and fleet-wide agent behavior tiles, including two-window comparisons. name: Metrics - description: Synced-commit history of the app's `.outerlayer/` context tree. name: Context - description: >- Session→PR attribution: which agent sessions produced which pull requests, and what each attributed PR cost. name: PRs - description: Service health checks. name: Health - description: >- Org member and role administration, authenticated with an org-scoped management API key (`olk_…`) minted in the dashboard's settings. name: Org Management - description: OAuth 2.1 discovery metadata for MCP connector clients. name: OAuth paths: /v1/work-items/{workItemId}: get: tags: - Work Items summary: Read one work item description: >- 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 host attempt it ran in, or `null` for a session linked any other way), every addition (live or removed) recorded against this item, `buildRequests` (every build request, used or not, each with the `instructions` its requester gave the agent or `null`), the live claim — with `holderKind` (`host` or `session`) and, for a session lease, `sessionId` — and `claims`, every lease this item has ever had with its `id` (the attempt's name, which `GET /v1/work-items/{workItemId}/claims/{claimId}/log` takes), its holder kind, `buildRequestId` (the `id` of the build request it answers), session id for a session lease, its outcome, the step it ended in (`stage`), the exit code of the process that ended it (`exitCode`), a host-written reason, and `environment` (what the attempt ran in: its isolation, the recipe and image, the hosts it reached and the ranges refused, the names of the variables it was given, the names of the destinations it called, the kinds of repository token it used, `commitIdentity` (whether its commits were authored by the App or the host, and whether the requester was credited) and `controlPlane` (the control-plane repository and commit a governed build received its instructions from; `null` for a self-governed build); `null` for a lease that recorded none). Both the live claim and every past lease also carry `apiKeyName` (the key that took it) and `requestedByKind`/`requestedByName` (who asked for the build it answers — a member or a key, resolved once when the lease was written); no membership or key id is ever included. `criteria` is the item's current recorded acceptance criteria — `drafted` (the build wrote them from the issue description), `recordedAt`, `recordedBy` and `items` of `id`, `text` and `proof` — or `null` when none are recorded. `checks` is every check open on the item, the latest row per name, each with its result, sentence, link and `items`, its check items (one per thing the check judged, with its own result and reason; `null` when the recorder sent none). `issue` is the issue the item wraps, as the dashboard last copied it from its tracker: its `url`, `state`, Markdown `body`, `author`, `openedAt` and `labels`, with `syncedAt` and `syncStatus` saying how current the copy is. It is how a build reads a Linear or Jira issue it holds no credential for. operationId: get-work-item parameters: - in: path name: workItemId required: true schema: type: string responses: '200': content: application/json: schema: properties: data: additionalProperties: nullable: true properties: checks: description: >- Every check open on the item: the latest row per name, with the check items it carries. items: properties: body: type: string id: type: string items: description: >- The check's check items: one per thing it judged, with its result and why. null when the recorder sent none. items: properties: criterion: pattern: ^[A-Za-z0-9_.:-]{1,64}$ type: string id: maxLength: 200 minLength: 1 pattern: ^[^\u0000-\u001f\u007f]+$ type: string inputs: pattern: ^[0-9a-f]{64}$ type: string reason: maxLength: 1000 type: string refs: items: properties: href: maxLength: 1000 type: string line: exclusiveMinimum: true minimum: 0 type: integer path: maxLength: 500 minLength: 1 pattern: ^[^\u0000-\u001f\u007f]+$ type: string required: - path type: object maxItems: 20 type: array result: enum: - pass - fail - skipped type: string required: - id - result type: object nullable: true type: array link: type: string name: type: string provenance: enum: - ci - local type: string recordedAt: type: string recordedBy: type: string result: enum: - pass - fail type: string source: enum: - machine - session - human - host type: string required: - id - name - result - source - provenance - link - body - items - recordedBy - recordedAt type: object type: array criteria: description: >- The current recorded acceptance criteria, or null when none are recorded. nullable: true properties: drafted: description: >- The build drafted the list from the issue description. type: boolean items: items: properties: id: type: string proof: nullable: true type: string text: type: string required: - id - text - proof type: object type: array recordedAt: type: string recordedBy: description: >- Who recorded the list; `user:hidden` or `key:hidden` without team visibility. type: string required: - drafted - recordedAt - recordedBy - items type: object host: description: >- The host holding the live claim, with its `state` and `status`; null when no host holds the item or the host has not heartbeated. A caller with `hosts.read` gets the host as `GET /v1/hosts` lists it; a caller with only `work.read` gets `host`, `state`, `status` and `waitingItems`. nullable: true properties: blocked: nullable: true properties: reason: type: string required: - reason type: object cliVersion: type: string host: type: string lastError: nullable: true properties: at: type: string code: type: string message: type: string required: - code - message - at type: object lastHeartbeatAt: type: string lastSuccessAt: nullable: true type: string lastUpdate: nullable: true properties: at: nullable: true type: string from: type: string outcome: enum: - updated - rolled_back - verification_failed - not_published - retrying type: string reason: nullable: true type: string to: type: string required: - from - to - outcome - reason - at type: object lowDisk: nullable: true properties: free: type: integer needed: type: integer required: - free - needed type: object pollSeconds: type: integer runnerProtocol: type: integer slotsTotal: type: integer slotsUsed: type: integer state: enum: - taking-work - draining - restarting - holding-for-update - blocked - low-disk - null nullable: true type: string status: enum: - ok - failing - outdated - stale - draining type: string takes: nullable: true properties: queues: items: type: string type: array repos: properties: exclude: items: type: string type: array include: items: type: string type: array required: - include - exclude type: object truncated: type: boolean required: - queues - repos - truncated type: object waitingItems: items: type: integer nullable: true type: array required: - host - state - status type: object issue: description: >- The issue this item wraps, as the dashboard last copied it from GitHub, Linear or Jira. properties: author: description: >- Who opened the issue, as the tracker names them; empty until read. type: string body: description: >- The issue's description as Markdown; empty when it has none or has not been read yet. type: string labels: items: type: string type: array openedAt: description: When the issue was opened; null until read. nullable: true type: string state: description: null until the dashboard has read the issue. enum: - open - closed - null nullable: true type: string syncStatus: description: >- `unreadable`: the last read failed, and these fields are from the read before it. `not_found`: the tracker says the issue no longer exists. enum: - ok - unreadable - not_found type: string syncedAt: description: >- When the dashboard last read the issue; null before the first read. nullable: true type: string url: description: >- The issue's page on its tracker; null until the dashboard has read it. nullable: true type: string required: - url - state - body - author - openedAt - labels - syncedAt - syncStatus type: object pullRequests: description: The pull requests linked to the item. items: properties: conflict: description: >- Set while the pull request does not merge cleanly into its base branch; null otherwise. nullable: true properties: baseBranch: type: string detectedAt: type: string headSha: description: >- The pull request head the conflict was found on. A push moves the head and ends the conflict. type: string required: - headSha - baseBranch - detectedAt type: object method: type: string prNumber: type: number repository: type: string repositoryConnected: description: >- false while the pull request is open and its repository is one this factory no longer connects. true otherwise, including for a merged or closed pull request. type: boolean required: - repository - prNumber - method - conflict - repositoryConnected type: object type: array repositoryDisconnected: description: >- true while at least one open pull request of the item is in a repository this factory no longer connects. Worked out on each read and never stored: connecting the repository again clears it. type: boolean waiting: description: >- Why nothing is building the item; null while it is building or queued with a host to take it. oneOf: - description: >- The last build ended and nothing has asked for another. properties: reason: enum: - trigger-used type: string required: - reason type: object - description: >- No host that heartbeated recently takes this queue and repository. properties: maybe: description: >- True when a host that would decline cut its repository patterns, so one of them may take the item. type: boolean reason: enum: - no-host type: string required: - reason - maybe type: object - description: >- Every host that would take the item is draining, holding, blocked or low on disk. properties: hosts: items: properties: host: type: string state: enum: - draining - restarting - holding-for-update - blocked - low-disk type: string required: - host - state type: object type: array reason: enum: - hosts-unavailable type: string required: - reason - hosts type: object - nullable: true required: - host - waiting - criteria - checks - issue - pullRequests - repositoryDisconnected type: object required: - data type: object description: The work item. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Invalid request parameters (validation failed). '401': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Missing or invalid API key. '404': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: No such work item. components: securitySchemes: AppId: description: Factory id the request is scoped to. in: header name: X-Outerlayer-App-Id type: apiKey BearerAuth: description: API key (sk_outerlayer_*) scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.