> ## Documentation Index > Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Open or edit a work item's pull request > 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 pull request number, so it reaches only this item's own pull request. Only the item key a claim returns may call it; any other credential is refused as if it lacked the permission. The pull request is linked to the item. Answers 201 when it opened one and 200 when it edited one. Refusals: `claim_expired` (410), `claim_has_no_branch` (409, a lease recorded before claims named a branch), `work_item_has_no_repository` (422), `repository_not_connected` (422), `repository_not_in_installation` (422), `repository_permissions_pending` (409, the installation has not accepted the App's pull request write permission), `branch_has_no_commits` (422, the branch has nothing the default branch lacks), `branch_not_pushed` (422, the branch is not on the remote; push it first), `repository_tokens_unavailable` (503, this gateway has no GitHub App) and `github_unavailable` (503, GitHub was rate limiting or failing; retry). ## OpenAPI ````yaml /openapi.yaml put /v1/work-items/{workItemId}/pull-request 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: >- 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}/pull-request: put: tags: - Work Items summary: Open or edit a work item's pull request description: >- 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 pull request number, so it reaches only this item's own pull request. Only the item key a claim returns may call it; any other credential is refused as if it lacked the permission. The pull request is linked to the item. Answers 201 when it opened one and 200 when it edited one. Refusals: `claim_expired` (410), `claim_has_no_branch` (409, a lease recorded before claims named a branch), `work_item_has_no_repository` (422), `repository_not_connected` (422), `repository_not_in_installation` (422), `repository_permissions_pending` (409, the installation has not accepted the App's pull request write permission), `branch_has_no_commits` (422, the branch has nothing the default branch lacks), `branch_not_pushed` (422, the branch is not on the remote; push it first), `repository_tokens_unavailable` (503, this gateway has no GitHub App) and `github_unavailable` (503, GitHub was rate limiting or failing; retry). operationId: put-work-item-pull-request parameters: - in: path name: workItemId required: true schema: type: string requestBody: content: application/json: schema: properties: body: maxLength: 65536 type: string title: maxLength: 256 minLength: 1 type: string required: - title - body type: object responses: '200': content: application/json: schema: properties: data: properties: created: description: >- `true` when this call opened the pull request, `false` when it edited an open one. type: boolean number: type: integer repository: type: string url: type: string required: - repository - number - url - created type: object required: - data type: object description: >- The open pull request on the branch was edited and linked to the item. '201': content: application/json: schema: properties: data: properties: created: description: >- `true` when this call opened the pull request, `false` when it edited an open one. type: boolean number: type: integer repository: type: string url: type: string required: - repository - number - url - created type: object required: - data type: object description: A pull request was opened and linked to the 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: 'The body is not `{ "title": string, "body": string }`.' '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 credential. '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 caller does not hold an item key, or the key belongs to another work item. '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. '409': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: >- The item is withdrawn (`work_item_withdrawn`), the lease names no branch (`claim_has_no_branch`), or the App installation has not accepted the pull request write permission (`repository_permissions_pending`). '410': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: The item has no live lease (`claim_expired`). '422': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: >- The item names no repository (`work_item_has_no_repository`), the factory has not connected it (`repository_not_connected`), the App installation does not include it (`repository_not_in_installation`), the branch has no commits the default branch lacks (`branch_has_no_commits`), or the branch was never pushed to the remote (`branch_not_pushed`). '503': 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 has no GitHub App configured (`repository_tokens_unavailable`), or GitHub was rate limiting or failing (`github_unavailable`, safe to retry). 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.