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.

How it works

• GET /factory - List the 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 a factory or start work on it. Use the agent and 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	GET /factory?search= (factory endpoints)
Start new work on a factory	POST /factory/{uid}/runs (factory endpoints)
Continue, monitor, or cancel a run (factory or standalone)	GET /agent/runs/{runId}, POST /agent/runs/{runId}/followups, POST /agent/runs/{runId}/cancel (agent and run endpoints)
Run a standalone cloud agent with no factory involved	POST /agent/runs (agent and run endpoints)
Build a multi-agent orchestration	The agent and run endpoints; see multi-agent orchestration

Discover a factory

Search factories by name

import os
from warp_platform_sdk import WarpClient

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

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

# Iterating over the result fetches every page of matches
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 work item back to it, or omit both for an ad hoc 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, dispatches work, and continues it from a custom chat integration.
• Factory MCP - Connect a local coding agent to a factory instead of calling the REST API directly.
• Agent and run endpoints - Full endpoint reference, SDKs, and error codes for the underlying Warp Platform API.
• How Warp Factories work - The stages a dispatched work item moves through after the foreman picks it up.