Warp Platform API reference

GET /networking/egress-ranges

List Warp-hosted agent egress ranges

Return the canonical IP network ranges used by outbound requests from Warp-hosted agents.

• ()

GET /factory

List factories

List factories accessible to the authenticated principal, restricted to the request's active team when one is set. An optional team_uid query parameter overrides the active team and restricts results to a single team, and an optional search query parameter filters by a case-insensitive substring match on the factory name or alias.

• ()
• team_uid (query): Optional team UID to filter factories by ownership. Takes precedence over the X-Warp-Team-Uid header.
• search (query): Case-insensitive substring search over the factory name and alias.
• limit (query): Maximum number of factories to return (default 50, max 100).
• cursor (query): Opaque cursor returned by a previous list response.

GET /factory/{uid}

Get a factory

Get a factory by its UID.

• uid (path, required): The public UID of the factory.

POST /factory/{uid}/tasks

Create a factory task

Create a task in a factory, bound to an existing agent conversation. title and conversation_id are required. The stage defaults to TRIAGE. The conversation's most recent run must be owned by the factory's team, and a conversation may be bound to at most one live task across all factories.

• uid (path, required): The public UID of the factory.

GET /factory/{uid}/tasks

List factory tasks

List the factory's tasks with optional filtering and search. List responses are lean by default; set full_list=true to include canonical ticket metadata and derived outputs for the returned page.

• uid (path, required): The public UID of the factory.
• stage (query): Filter by task stage. Can be specified multiple times to match any of the given stages.
• created_by (query): Filter to tasks whose seed run was started by any of these teammates, each given as their email address. Can be specified multiple times to match any of the given teammates.
• q (query): Case-insensitive substring search over the task title.
• created_after (query): Filter to tasks created after this timestamp (RFC3339 format).
• created_before (query): Filter to tasks created before this timestamp (RFC3339 format).
• updated_after (query): Filter to tasks updated after this timestamp (RFC3339 format).
• sort_by (query): Sort field for results.
• sort_order (query): Sort direction.
• limit (query): Maximum number of tasks to return (default 50, max 100).
• cursor (query): Opaque cursor returned by a previous list response. Valid only for the sort_by/sort_order it was issued under; omit to restart the listing.
• full_list (query): Include canonical ticket_source and ticket_id metadata from each task's bound run, plus its derived outputs. Defaults to false.
• include_current_run (query): Include each task's current top-level run, resolved in one batch for the returned page. Defaults to false.

POST /factory/{uid}/runs

Dispatch a run to a factory

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.

• uid (path, required): The public UID of the factory.

GET /factory/{uid}/tasks/{task_uid}

Get a factory task

Get a task with its derived outputs, newest-first.

• uid (path, required): The public UID of the factory.
• task_uid (path, required): The public UID of the task.

PATCH /factory/{uid}/tasks/{task_uid}

Update a factory task

Partially update a task's title, description, and/or stage. Last write wins. Stage writes are unrestricted: any stage-to-stage transition is allowed, including moving backwards or to completion.

• uid (path, required): The public UID of the factory.
• task_uid (path, required): The public UID of the task.

DELETE /factory/{uid}/tasks/{task_uid}

Delete a factory task

Soft-delete a task. The task disappears from list and get responses immediately, and its conversation may be bound to a new task. Deleting a task never deletes artifacts or the conversation.

• uid (path, required): The public UID of the factory.
• task_uid (path, required): The public UID of the task.

POST /factory/{uid}/tasks/{task_uid}/cancel

Stop a factory task

Cancel the task's current top-level run and move the task to CANCELLED. Every non-terminal descendant of the root run is cancelled as well.

• uid (path, required): The public UID of the factory.
• task_uid (path, required): The public UID of the task.

GET /factory/{uid}/task-by-conversation

Get a factory task by conversation

Get the factory task bound to an agent conversation. Conversation bindings are unique across factories, but the lookup is factory-scoped: a task owned by a different factory is 404.

• uid (path, required): The public UID of the factory.
• conversation_id (query, required): The agent conversation ID the task is bound to.

GET /factory/{uid}/task-by-run

Get a factory task by run

Get the factory task that owns a run: the task bound to the conversation of the run's root ancestor. The lookup is factory-scoped: a task owned by a different factory is 404.

• uid (path, required): The public UID of the factory.
• run_id (query, required): Any run ID in the task's run tree.

GET /agent

List available agent skills

Retrieve a list of available agents (skills) that can be used to run tasks. Agents are discovered from environments or a specific repository.

• ()
• repo (query): Optional repository specification to list agents from (format: "owner/repo"). If not provided, lists agents from all accessible environments.
• refresh (query): When true, clears the agent list cache before fetching. Use this to force a refresh of the available agents.
• sort_by (query): Sort order for the returned agents. - "name": Sort alphabetically by name (default) - "last_run": Sort by most recently used
• include_malformed_skills (query): When true, includes skills whose SKILL.md file exists but is malformed. These variants will have a non-empty `error` field describing the parse failure. Defaults to false.

GET /agent/connected-self-hosted-workers

List connected self-hosted workers

Retrieve currently connected self-hosted workers for the authenticated principal's team. Worker presence is derived from worker websocket heartbeats and may be briefly stale.

• ()

GET /agent/runs/{runId}/transcript

Get run transcript

Retrieve the raw conversation transcript for an agent run. Returns a 302 redirect to a time-limited download URL for the transcript.

• runId (path, required): The unique identifier of the run

GET /agent/runs/{runId}/harness-usage

Get raw third-party harness usage

Return the latest cumulative raw usage snapshot retained for a Claude Code or Codex run. Missing metrics are represented as an unavailable result rather than zero. Access uses the same run view authorization as transcript reads.

• runId (path, required)

POST /agent/run

Run an agent task

Spawn a cloud agent with a prompt and optional configuration. The agent will be queued for execution and assigned a unique run ID.

• ()

POST /agent/runs

Run a cloud agent

Spawn a cloud agent with a prompt and optional configuration. The agent will be queued for execution and assigned a unique run ID.

• ()

GET /agent/runs

List agent runs

Retrieve a paginated list of agent runs with optional filtering. Results default to `sort_by=updated_at` and `sort_order=desc`.

• ()
• limit (query): Maximum number of runs to return
• cursor (query): Pagination cursor from previous response
• sort_by (query): Sort field for results. - `updated_at`: Sort by last update timestamp (default) - `created_at`: Sort by creation timestamp - `title`: Sort alphabetically by run title - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
• sort_order (query): Sort direction
• state (query): Filter by run state. Can be specified multiple times to match any of the given states.
• task_status (query): Filter by high-level task status. Can be specified multiple times to match any value. `running` matches when the root or any descendant is queued, pending, claimed, or in progress. `failed`, `blocked`, `cancelled`, and `complete` match the root state only.
• name (query): Filter by agent config name
• model_id (query): Filter by model ID
• creator (query): Filter by creator UID (user or service account)
• executor (query): Filter by the user or agent that executed the run. This will often be the same as the creator, but not always: users may delegate tasks to agents.
• source (query): Filter by run source type. Can be specified multiple times to match any of the given sources.
• execution_location (query): Filter by where the run executed
• created_after (query): Filter runs created after this timestamp (RFC3339 format)
• created_before (query): Filter runs created before this timestamp (RFC3339 format)
• updated_after (query): Filter runs updated after this timestamp (RFC3339 format)
• environment_id (query): Filter runs by environment ID. Passing the literal value `empty-environment` matches runs with no environment configured, rather than omitting the parameter, which applies no environment filter at all. `empty-environment` can never collide with a real environment ID: every environment ID is exactly 22 characters drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen and is a different length.
• skill (query): Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec.
• skill_spec (query): Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
• schedule_id (query): Filter runs by the scheduled agent ID that created them
• factory_uid (query): Filter runs by one or more factories. Repeating this parameter matches runs executed by an agent from any selected factory. A UID outside the caller's accessible factories matches nothing.
• ancestor_run_id (query): Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.
• metadata (query): Filter by exact metadata key/value pairs using object notation (e.g. `metadata[ticket_id]=ACME-238`), combining multiple pairs with AND semantics, up to 5 per request. Returns `feature_not_available` when metadata filtering is not enabled.
• artifact_type (query): Filter runs by artifact type
• q (query): Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec

GET /agent/run-by-external-reference

Find the run that produced a given external reference URL

Reverse-looks up the agent run that created an external reference with the given URL. The URL is matched against the canonical locator stored when the artifact was reported. Returns 404 when no matching run exists or when the caller lacks access.

• url (query, required): The canonical URL of the external reference artifact to look up.

GET /agent/runs/{runId}

Get run details

Retrieve detailed information about a specific agent run, including the full prompt, session link, and resolved configuration.

• runId (path, required): The unique identifier of the run

GET /agent/runs/{runId}/timeline

Get run timeline

Retrieve chronological setup and lifecycle timeline events for an agent run.

• runId (path, required): The unique identifier of the run

GET /agent/runs/{runId}/conversation

Get normalized run conversation

Retrieve a run's conversation as a normalized sequence of messages and nested steps. The response groups text, tool activity, and event content into structured blocks.

• runId (path, required): The unique identifier of the run

POST /agent/runs/{runId}/cancel

Cancel a run

Cancel an agent run that is currently queued or in progress; once cancelled, the run transitions to a cancelled state. Not all runs can be cancelled: a run already in a terminal state, in PENDING, or of an unsupported type (e.g. local, GitHub Action) is rejected instead — see the error responses below for each case.

• runId (path, required): The unique identifier of the run to cancel

POST /agent/runs/{runId}/followups

Submit a follow-up message for a run

Send a follow-up message to an existing run. The server transparently routes the message based on the current state of the run (still queued, actively running, or ended) and will resume the agent in a new sandbox if necessary. A 200 response means the follow-up was accepted; updated run state can be observed via `GET /agent/runs/{runId}`. A run that failed during environment setup keeps its retained session reachable for a bounded debug window. A follow-up sent to an eligible run in that window is delivered into the retained session to start or continue a debug agent, without reopening the run: it stays in its failed state, with its original failure message and error code unchanged.

• runId (path, required): The unique identifier of the run

POST /agent/runs/{runId}/interrupt

Interrupt the turn currently running on a run

Cancel the request the agent is currently working on without ending the run or tearing down its sandbox. The run stays in progress and accepts follow-ups afterwards. Only live runs on the Warp harness can be interrupted; use `POST /agent/runs/{runId}/cancel` to end a run outright. A 202 means the platform accepted the cancel; the agent applies it asynchronously.

• runId (path, required): The unique identifier of the run

POST /agent/conversations/{conversation_id}/followups

Submit a follow-up message to the run behind a conversation

The same operation as `POST /agent/runs/{runId}/followups`, targeted by the conversation the run is serving rather than the run itself. `attachments` must name ids prepared through `POST /agent/conversations/{conversation_id}/attachments/prepare` (or the run-keyed prepare) for the run that is newest at that time. If a new run appears for the conversation between prepare and follow-up, the follow-up resolves to the new run and answers 422 `unknown_attachment`; prepare again. A handoff is a new execution of the same run and does not have this problem. `mode` only takes effect when the follow-up is queued ahead of the run starting or starts a new execution; a follow-up injected into a live session runs in the session's current mode.

• conversation_id (path, required): The UUID of the Warp-native conversation

POST /agent/conversations/{conversation_id}/interrupt

Interrupt the turn running on the run behind a conversation

The same operation as `POST /agent/runs/{runId}/interrupt`, addressed by the conversation the run is serving. The run is picked with the same policy as the conversation follow-up route, and the caller must be able to view the conversation and the resolved run.

• conversation_id (path, required): The UUID of the Warp-native conversation

GET /agent/conversations/{conversation_id}

Get normalized conversation

Retrieve a conversation directly by conversation ID in Warp's normalized task/message format.

• conversation_id (path, required): The unique identifier of the conversation

GET /agent/conversations/{conversation_id}/transcript

Get conversation transcript

Retrieve the raw conversation transcript for a conversation. Returns a 302 redirect to a time-limited download URL for the transcript. Supported for third-party harness conversations (Claude Code, Codex, Gemini).

• conversation_id (path, required): The unique identifier of the conversation

GET /agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download

Download a stored computer-use screenshot

Download a computer-use screenshot that was offloaded from the conversation's task history into object storage. The response is a redirect to a short-lived signed URL, so clients must follow redirects to receive the image. Requires view access to the conversation named in the path; a fork's history may reference screenshots stored under its source conversation's ID.

• conversation_id (path, required): The unique identifier of the conversation that owns the screenshot
• screenshot_uid (path, required): The unique identifier of the stored screenshot

POST /agent/schedules

Create a scheduled agent

Create a new scheduled agent that runs on a cron schedule. The agent will be triggered automatically based on the cron expression.

• ()

GET /agent/schedules

List scheduled agents

Retrieve all scheduled agents accessible to the authenticated user. Results are sorted alphabetically by name.

• ()

GET /agent/schedules/{scheduleId}

Get scheduled agent details

Retrieve detailed information about a specific scheduled agent, including its configuration, history, and next scheduled run time.

• scheduleId (path, required): The unique identifier of the scheduled agent

PUT /agent/schedules/{scheduleId}

Update a scheduled agent

Update an existing scheduled agent's configuration. All fields except agent_config are required.

• scheduleId (path, required): The unique identifier of the scheduled agent

DELETE /agent/schedules/{scheduleId}

Delete a scheduled agent

Delete a scheduled agent. This will stop all future scheduled runs.

• scheduleId (path, required): The unique identifier of the scheduled agent

POST /agent/schedules/{scheduleId}/pause

Pause a scheduled agent

Pause a scheduled agent. The agent will not run until resumed.

• scheduleId (path, required): The unique identifier of the scheduled agent

POST /agent/schedules/{scheduleId}/resume

Resume a scheduled agent

Resume a paused scheduled agent. The agent will start running according to its cron schedule.

• scheduleId (path, required): The unique identifier of the scheduled agent

GET /agent/environments

List environments

Retrieve cloud environments accessible to the authenticated principal. Returns environments the caller owns, has been granted guest access to, or has accessed via link sharing.

• ()
• sort_by (query): Sort order for the returned environments. - `name`: alphabetical by environment name - `last_updated`: most recently updated first (default)

GET /agent/models

List available models

Retrieve the list of LLM models available to the authenticated user for agent runs. The response includes which model is the default, as well as per-model metadata such as provider, cost, and whether the model is currently disabled (and why).

GET /agent/artifacts/{artifactUid}

Get artifact details

Retrieve an artifact by its UUID: a time-limited signed download URL for downloadable file-like artifacts, or the current plan content inline for plan artifacts. Public artifacts can be read without authentication; private artifacts require the caller to be authenticated and authorized.

• artifactUid (path, required): The unique identifier (UUID) of the artifact

GET /agent/artifacts/{artifactUid}/download

Download an artifact

Redirect to a temporary signed download URL for a downloadable artifact. Public artifacts can be downloaded without authentication; private artifacts require the caller to be authenticated and authorized.

• artifactUid (path, required): The unique identifier (UUID) of the artifact

POST /agent/identities

Create an agent

Create a new agent in the caller's active team. Agents act autonomously with their own permissions, configuration, and identity.

• ()

GET /agent/identities

List agents

List all agents on the caller's team.

• ()
• factory_uid (query): Optional UID of a Factory to filter by. When provided, only agents linked to that factory are returned.

GET /agent/identities/{uid}

Retrieve an agent

Retrieve a single agent by its unique identifier.

• uid (path, required): The unique identifier of the agent

PUT /agent/identities/{uid}

Update an agent

Update an existing agent.

• uid (path, required): The unique identifier of the agent

DELETE /agent/identities/{uid}

Delete an agent

Delete an agent. All API keys associated with the agent are deleted atomically.

• uid (path, required): The unique identifier of the agent

GET /factory-files/schemas

List the supported Factory file schema versions

Returns every Factory file schema version this server can describe, with a link to each version's schema bundle.

• If-None-Match (header): A previously returned ETag. A match returns 304 with no body.

GET /factory-files/schemas/{schema_version}

Get the JSON Schema bundle for one Factory file schema version

Returns every JSON Schema 2020-12 document describing one Factory file schema version, as a single bundle so the relative `$id` and `$ref` identities between the documents keep resolving.

• schema_version (path, required): A Factory file schema version, for example `v1alpha1`.
• If-None-Match (header): A previously returned ETag. A match returns 304 with no body.

GET /factory-files/schemas/{schema_version}/{document}

Get one Factory file schema document

Returns a single generated JSON Schema document on its own, rather than inside the bundle envelope, so it can be used directly as a schema reference. A document served here resolves its relative `$ref`s against its siblings at this same path, which is what each document's `$id` assumes, making the URL usable directly from an editor or YAML language server, for example: ```yaml # yaml-language-server: $schema=/api/v1/factory-files/schemas/v1alpha1/factory.schema.json ```

• schema_version (path, required): Factory file schema version, such as v1alpha1
• document (path, required): Document file name: common.schema.json, factory.schema.json, agent.schema.json, automation.schema.json, runner.schema.json, or scorer.schema.json