> ## 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. # Ask for the next managed build > The route a fleet machine asks for its next managed build on. A fleet machine is a machine OuterLayer operates; it belongs to no factory and authenticates with a fleet machine key (`olfm_…`) as the bearer. Every request is signed by the machine's host key, the same profile as a runner key; the first request carries the host key in `hostKey` and binds the machine to it. A request from an address the machine does not allow is refused with `machine_source_refused`, and a request from a revoked machine with `machine_revoked`. The request is also the machine's heartbeat. The gateway picks at most one build of any organization that has managed builds on, the organization that runs the fewest fleet builds first and the oldest build first, within each organization's `max_managed_builds` limit, and only a build that fits the machine's room. The answer carries the claim for that build, a reservation when the gateway holds room on this machine for a larger build, and the stops people asked for. Served by the Worker gateway only; a Node gateway answers 404. ## OpenAPI ````yaml /openapi.yaml post /v1/fleet/next 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: >- The route a fleet machine asks for its next managed build on. A fleet machine is a machine OuterLayer operates. name: Fleet - description: >- The CLI version a gateway names to its runners, set with the gateway's runner version key. name: Runner version - 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/fleet/next: post: tags: - Fleet summary: Ask for the next managed build description: >- The route a fleet machine asks for its next managed build on. A fleet machine is a machine OuterLayer operates; it belongs to no factory and authenticates with a fleet machine key (`olfm_…`) as the bearer. Every request is signed by the machine's host key, the same profile as a runner key; the first request carries the host key in `hostKey` and binds the machine to it. A request from an address the machine does not allow is refused with `machine_source_refused`, and a request from a revoked machine with `machine_revoked`. The request is also the machine's heartbeat. The gateway picks at most one build of any organization that has managed builds on, the organization that runs the fewest fleet builds first and the oldest build first, within each organization's `max_managed_builds` limit, and only a build that fits the machine's room. The answer carries the claim for that build, a reservation when the gateway holds room on this machine for a larger build, and the stops people asked for. Served by the Worker gateway only; a Node gateway answers 404. operationId: fleet-next parameters: - description: >- HTTP Message Signature (RFC 9421) made with the runner key's host key: `runner=::`. in: header name: Signature required: false schema: description: >- HTTP Message Signature (RFC 9421) made with the runner key's host key: `runner=::`. type: string - description: >- The signature's covered components and parameters: `runner=("@method" "@path" "@query" "content-digest");created=;nonce="";keyid="";alg="ed25519"`. in: header name: Signature-Input required: false schema: description: >- The signature's covered components and parameters: `runner=("@method" "@path" "@query" "content-digest");created=;nonce="";keyid="";alg="ed25519"`. type: string - description: >- RFC 9530 digest of the request body, always sent, including for a request with none: `sha-256=::`. in: header name: Content-Digest required: false schema: description: >- RFC 9530 digest of the request body, always sent, including for a request with none: `sha-256=::`. type: string requestBody: content: application/json: schema: properties: cliVersion: maxLength: 100 minLength: 1 type: string free: description: The room the machine has free now. properties: diskGB: maximum: 1000000000 minimum: 0 type: number memoryGiB: maximum: 1000000 minimum: 0 type: number vcpus: maximum: 1000000 minimum: 0 type: number required: - memoryGiB - vcpus - diskGB type: object hostKey: pattern: ^[A-Za-z0-9_-]{43}$ type: string images: description: >- The repositories, as `owner/repo`, whose build images the machine holds. items: maxLength: 255 minLength: 1 type: string maxItems: 500 type: array runnerProtocol: type: integer total: description: >- The room the machine has in all: memory in GiB, cores and disk in GB. properties: diskGB: maximum: 1000000000 minimum: 0 type: number memoryGiB: maximum: 1000000 minimum: 0 type: number vcpus: maximum: 1000000 minimum: 0 type: number required: - memoryGiB - vcpus - diskGB type: object required: - total - free - images - cliVersion - runnerProtocol type: object responses: '200': content: application/json: schema: properties: data: properties: claim: description: >- The build handed out, with the lease the machine now holds, or `null` when no build fits. nullable: true properties: appId: description: The factory the work item belongs to. type: string branch: description: >- The branch the build works on in the primary repository: the head branch of the item's one open pull request there, or `outerlayer//` when it has none. `null` only for a lease recorded before claims named a branch. nullable: true type: string coAuthor: description: >- The member who asked for the build, for the `Co-authored-by` line the runner adds to each commit. The address is `+@users.noreply.github.com`, from the GitHub account the member signed in with. Absent when the build has no requester who is a member of the org, when the requester signed in without GitHub, and when `commitAuthor` is absent. properties: email: type: string name: type: string required: - name - email type: object commitAuthor: description: >- The identity every commit the build makes is authored and committed under: the GitHub App's bot account, named `[bot]`, with the address `+[bot]@users.noreply.github.com`. Absent on a gateway that holds no GitHub App keys. properties: email: type: string name: type: string required: - name - email type: object createdAt: type: string expiresAt: type: string host: type: string id: type: string itemKey: description: >- A signed key, prefixed `olitem_`, that acts only on this work item and only while this lease is live. The runner gives it to the build as its API key. A claim by the lease's own holder returns the same key. type: string kind: enum: - implement - amend type: string repositories: description: >- Every repository the build checks out, the primary first and the others in name order. A factory with one connected repository names one. Each repository has the head branch of the item's one open pull request there, or `outerlayer//` when it has none. Empty when the item names no repository and the factory has connected none. items: properties: branch: description: >- The branch the build works on in this repository. type: string primary: description: >- `true` for the one repository the item itself lives in or, failing that, the first the claim chose. type: boolean repository: description: The repository, as lower-case `owner/repo`. type: string required: - repository - branch - primary type: object type: array size: description: The size of the machine the build needs. enum: - small - large type: string unreachable: description: >- Repositories the factory links that this claim leaves out because the GitHub App installation that reaches them is suspended on GitHub. The item's own repository is never listed here: a suspended installation there refuses the claim with `repository_not_reachable`. Always present, as an empty list when nothing was left out. items: properties: reason: description: Why the claim leaves the repository out. enum: - installation_suspended type: string repository: description: The repository, as lower-case `owner/repo`. type: string required: - repository - reason type: object type: array workItemId: description: The id of the work item the lease is on. type: string required: - id - host - kind - createdAt - expiresAt - branch - repositories - itemKey - workItemId - appId - size type: object reason: description: >- Why the build the gateway picked was not claimed, as an error code. Absent when it was. type: string reservation: description: >- The build the gateway holds room for on this machine. The machine takes no build that would leave it without that room. nullable: true properties: size: enum: - small - large type: string workItemId: type: string required: - workItemId - size type: object stops: description: >- The builds on this machine that a person asked to stop. items: properties: claimId: type: string note: nullable: true type: string requestedByName: type: string required: - claimId - requestedByName - note type: object type: array required: - claim - reservation - stops type: object required: - data type: object description: The decision. `claim` is `null` when no build fits. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: The body is malformed. '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, or a runner key's signature was refused: `runner_key_signature_required` (the request carries no signature), `runner_key_signature_invalid` (it does not verify against the host key the key is bound to, or the body does not match its digest), `runner_key_signature_stale` (`created` is more than five minutes from the gateway's clock) or `runner_key_signature_replayed` (the nonce was accepted in the last five minutes). '403': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: >- The request comes from an address the machine does not allow (`machine_source_refused`), or the machine was revoked (`machine_revoked`). '404': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: This gateway does not serve fleet machines. security: - FleetMachineKey: [] 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 FleetMachineKey: description: >- Fleet machine key (olfm_*), made by a platform admin. Belongs to a machine OuterLayer operates, not to a factory. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.