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} - retrieve one factory by UID.
• POST /factory/{uid}/runs - dispatch a run to the factory’s foreman agent. Pass a prompt and a title; 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. See migrating from agent_identity_uid if your integration dispatches to factories today by looking up their foreman agent directly.

When to use 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

Retrieve a factory when the UID is already known

factory = client.factories.retrieve(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, a prompt, and a title:

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",  # optional; omitted -> adhoc ref
)
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"
}

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. 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

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

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

Migrating from agent_identity_uid

If your integration currently dispatches to a factory with the lower-level Agent API, replace the foreman lookup and agent_identity_uid with a single factory API call.

Before - the caller has to already know the foreman’s agent UID:

client.agent.run(prompt="Fix the flaky test", agent_identity_uid="YOUR_FOREMAN_AGENT_UID")

After - the caller only needs the factory’s UID; the server resolves the foreman:

run = client.factories.runs.create(
    factory.uid,
    prompt="Fix the flaky test",
    title="Fix the flaky test",
)

The run executes exactly the same way, and existing run-management APIs keep working on it. The agent_identity_uid path still works for existing integrations.

Note

The Oz API & SDK is in the middle of a rename to align with the Automation Platform: today’s oz_agent_sdk package and OzAPI client will eventually carry renamed Warp Agent and factory API names. The endpoints and fields on this page keep working across that rename; watch the Python SDK and TypeScript SDK repos for the updated names.

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.