Factory endpoints

The factory endpoints are part of the Warp Platform API. Use them to find a factory and start work from a custom integration without managing agent details. Build them 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 and run endpoints used for any run.

Choosing an endpoint family

Use factory endpoints to find or start work on a factory. Use Agent & run endpoints for everything else: a standalone cloud agent, run management, or orchestration.

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

Every factory run is still an ordinary run, so Agent & run endpoints handle status, follow-ups, and cancellation no matter which endpoint family 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 factory endpoints 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.
• Agent & run endpoints - Full endpoint reference, SDKs, and error codes for the underlying Warp Platform API.
• How Warp Factories work - The stages a dispatched task moves through after the foreman picks it up.