---
title: "Dispatch a run to a factory"
method: POST
path: "/factory/{uid}/runs"
tags: ["Factories"]
---

# Dispatch a run to a factory

`POST /factory/{uid}/runs`

## Request

- Base URL: `https://app.warp.dev/api/v1`
- URL: `https://app.warp.dev/api/v1/factory/{uid}/runs`
- Auth: HTTP bearer

Dispatch a run to a factory, using prompt as the run's
prompt and an optional title, ticket_ref, and ticket_url. Returns
the created run; its factory task is created asynchronously and can
be resolved afterwards with GET /factory/{uid}/task-by-run.

## Path parameters

- `uid` string, required

## Request body

- FactoryRunRequest: Request body for dispatching a run to a factory.
  - `attachments` AttachmentInput[]
    - `file_name` string, required: Name of the attached file
    - `mime_type` string, required: MIME type of the attachment. Supported image types: image/jpeg, image/png, image/gif, image/webp
    - `data` string, byte, required: Base64-encoded attachment data
  - `branch` string, nullable: Exact named head in the registered source repository, optionally prefixed with refs/heads/. Case and slashes are preserved. Omission, null, or the registered production branch uses production. Empty strings, revision expressions, tags, forks, and alternate repository coordinates are not accepted. Non-production selection is rejected when factory_branches is off.
  - `prompt` string, required: The prompt sent to the factory's foreman, not wrapped in any factory intake envelope. Required and non-empty.
  - `title` string: Human-readable title for the dispatched run and its factory task. Omit to derive one automatically from the prompt.
  - `ticket_ref` string: Originating ticket reference in <source>:<id> form (for example, linear:REMOTE-123); omit to mint an adhoc reference. Stamped onto the run as ticket_id/ticket_source metadata.
  - `ticket_url` string: Optional URL of the ticket named by ticket_ref. Stamped onto the run as ticket_url metadata when given.

## Response `201`

Run dispatched successfully

- FactoryRunResponse: Response body for a dispatched factory run.
  - `config_source` FactoryConfigSource: Branch namespace and registered source-generation identity derived from the run's execution Agent and required root/Branch associations. Omitted for production or unavailable provenance; omission does not establish production scope. No historical configuration revision or retention guarantee is provided.
    - `branch` string, required: Case-sensitive named head, without refs/heads/.
    - `branch_uid` string, required: Immutable tracking namespace UID.
    - `source_generation` string, required: Fingerprint of the registered source generation.
  - `run_id` string, required: Unique identifier for the dispatched run.
  - `run_url` string: URL to view the dispatched run in the Factory app. Empty when the Factory app origin is not configured.
  - `state` 'QUEUED' | 'PENDING' | 'CLAIMED' | 'INPROGRESS' | 'SUCCEEDED' | 'FAILED' | 'BLOCKED' | 'ERROR' | 'CANCELLED', required: Current state of the run: - QUEUED: Run is waiting to be picked up - PENDING: Run is being prepared - CLAIMED: Run has been claimed by a worker - INPROGRESS: Run is actively being executed - SUCCEEDED: Run completed successfully - FAILED: Run failed - BLOCKED: Run is blocked (e.g., awaiting user input or approval) - ERROR: Run encountered an error - CANCELLED: Run was cancelled by user
  - `factory_uid` string, required: Public UID of the factory the run was dispatched to.
  - `foreman_agent` string, required: Name of the factory's foreman agent that received the run.
  - `ticket_ref` string, required: The canonical <source>:<id> ticket reference the run was stamped with, either the caller-supplied ticket_ref or a minted adhoc reference.

## Other responses

- `400`: Invalid request body or ticket_ref
- `401`: Authentication required
- `403`: Factory access is not enabled for the authenticated principal
- `404`: Factory not found or not accessible
- `409`: The factory has no foreman agent to receive work
- `500`: Internal server error

## Changes

- **2026-10-21** `7ee3ba55debc`: 1 info
  - added the new optional request property `attachments`
- **2026-10-19** `2c45dcc0a13e`: 2 info
  - added the new optional request property `branch`
  - added the optional property `config_source` to the response with the `201` status
- **2026-10-13** `96d1e59a65c5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/factory/:uid/runs/post.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)