Use the factory API

Use the factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn’t connect to directly.

Note

Warp Factories is in Early Access and available to a limited set of teams. Request access to use it with your team.

How it works

• GET /factory - list factories your account can access. Add search to filter by name or alias, case-insensitive.
• GET /factory/{uid} - get one factory by UID.
• POST /factory/{uid}/runs - dispatch a run to the factory’s foreman agent. Pass a prompt; the server resolves the foreman for you.

A dispatched run is an ordinary cloud agent run: retrieve it, send it follow-ups, or cancel it through the same Agent API you’d use for any run.

Choosing how work reaches a factory

The factory API is one of several ways to get work into a factory, and each fits a different caller:

• A bot, service, or script you control - use the factory API to find a factory and dispatch to it.
• A coding agent session, local or in another MCP client - use Factory MCP to send work in or pull a task down to work on locally.
• A chat platform or issue tracker your team already uses - connect it as an integration so matching events start work automatically, with no code to write.

See connect your factory for the full comparison across every intake path.

The factory API vs the Agent API

Use the factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration.

Task	Recommended API
Find a factory by name before dispatching to it	factory API - GET /factory?search=
Start a new task on a factory	factory API - POST /factory/{uid}/runs
Continue, monitor, or cancel a run (factory or standalone)	Agent API - GET /agent/runs/{runId}, POST /agent/runs/{runId}/followups, POST /agent/runs/{runId}/cancel
Run a standalone cloud agent with no factory involved	Agent API - POST /agent/run
Build a multi-agent orchestration	Agent API - see multi-agent orchestration

The Agent API isn’t deprecated: every factory run is still an ordinary run, so the same endpoints handle status, follow-ups, and cancellation no matter which API started it.

Discover a factory

Search factories by name

import os
from oz_agent_sdk import OzAPI

client = OzAPI(api_key=os.environ.get("WARP_API_KEY"))

# Find a factory by name or alias — no UIDs needed up front
page = client.factories.list(search="payments")
factory = page.factories[0]

# With the pagination scheme wired, iteration auto-pages
for f in client.factories.list(search="payments"):
    print(f.uid, f.name)

The REST equivalent:

GET /api/v1/factory?search=payments
Authorization: Bearer YOUR_API_KEY

Get a factory when the UID is already known

factory = client.factories.get(factory.uid)

GET /api/v1/factory/YOUR_FACTORY_UID
Authorization: Bearer YOUR_API_KEY

Dispatch a run to a factory

Dispatch with just the factory’s UID and a prompt:

run = client.factories.runs.create(
    factory.uid,
    prompt="Investigate and fix the flaky payment webhook retry test",
    title="Fix flaky payment webhook retry test",
    ticket_ref="linear:PAY-123",
)
print(run.run_id, run.run_url, run.state)

POST /api/v1/factory/YOUR_FACTORY_UID/runs
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "prompt": "Investigate and fix the flaky payment webhook retry test",
  "title": "Fix flaky payment webhook retry test",
  "ticket_ref": "linear:PAY-123"
}

Every field except prompt is optional. Omit title and the server derives one from the prompt. ticket_ref identifies the originating ticket in <source>:<id> form (for example linear:PAY-123 or jira:PROJ-456); pass ticket_url to link the factory’s task record back to it, or omit both for an adhoc reference.

Continue and monitor the run

status = client.agent.runs.retrieve(run.run_id)

Send a follow-up the same way you would for any run:

POST /api/v1/agent/runs/YOUR_RUN_ID/followups
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "message": "Also add a regression test for the retry backoff"
}

See key endpoints for the full set of run-management operations, including cancellation.

Related pages

• Connect your factory - Every way work can enter a factory, including the factory API alongside Slack, GitHub, and Factory MCP.
• Build a Mattermost bot for Warp Factories - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration.
• Factory MCP - Connect a local coding agent to a factory instead of calling the REST API directly.
• Oz API & SDK - Full endpoint reference, SDKs, and error codes for the underlying Agent API.
• How Warp Factories work - The stages a dispatched task moves through after the foreman picks it up.