API for creating, managing, and querying factory and cloud agent runs. Send work to factories, start standalone agents, list runs, and retrieve detailed run information.
Base URL: https://app.warp.dev/api/v1
Authentication: Bearer token (Warp API key). Obtain from account settings. Pass as Authorization: Bearer YOUR_API_KEY.
Full machine-readable spec: openapi.json
List built-in network policies
Return Warp-managed network policies grouped by name, with every published version and its included allowed hosts. Use a name and version in networkPolicy.extends. Policies do not include the platform's system-required egress rules.
List Warp-hosted agent egress ranges
Return the canonical IP network ranges used by outbound requests from Warp-hosted agents.
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.
Get a factory
Get a factory by its UID.
List Factory inbox notifications
List unresolved notifications across factories authorized for the authenticated principal and active team. The default `mine` scope preserves the personal Inbox and requires user credentials. The `team` scope lists notifications assigned to any recipient and can be used by user or agent credentials. Personal read state (`is_read`) is included only in `mine` scope and omitted in `team` scope, including when filtering by recipient.
Mark inbox notifications as read
Mark a batch of notifications as read for the authenticated user after checking access to each factory. The caller must be a recipient of each existing notification, and the notification must remain active; otherwise its outcome is unsuccessful. Missing notifications are successful no-ops. Outcomes are returned in request order.
Mark inbox notifications as unread
Mark a batch of notifications as unread for the authenticated user after checking access to each factory. The caller must be a recipient of each existing notification, and the notification must remain active; otherwise its outcome is unsuccessful. Missing notifications are successful no-ops. Outcomes are returned in request order.
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.
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.
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.
Observe a tracked Factory Branch
Requires Factory view and matching parent Factory/team ownership. Does not create tracking, request repair, or mutate projections. Retired tracking remains DELETED until normal permadeletion. Unverifiable source freshness is UNKNOWN. Requires factory_branches.
Stop tracking a Factory Branch
Requires Factory view plus source.apply. Retirement blocks future execution boundaries without deleting the Git head, cancelling already-loaded work, or deleting production resources. Repeated authorized deletion, including after purge, returns 204. Requires factory_branches.
Apply a Factory Branch sync
Requires Factory view and source.apply. Queues a Temporal reconciliation to the current registered head and returns before synchronization completes. Publication requires complete projection authorization. Duplicate requests converge. Read branch status to observe completion or source errors. Does not accept a target SHA or repository, create tracking, revive retired identity, or replace settings on existing runs. Requires factory_branches.
Get a factory task
Get a task with its derived outputs, newest-first.
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.
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.
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.
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.
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.
Get factory metrics
Aggregate productivity metrics for a factory over a UTC date range: run count, distinct PR count (from PR artifacts, deduped by URL at first appearance), autonomy, impact, and PR latency. Cost metrics live under /factory/{uid}/costs. Pass group_by_period to additionally receive per-period series aligned to period_list.
Get factory cost per PR
Mean per-PR attributed cost for a factory over a UTC date range, with per-component dollar breakdowns. Previously served as cost_per_pr on GET /factory/{uid}/metrics. Pass group_by_period to additionally receive per-period series aligned to period_list.
Get factory spend grouped by a dimension
The factory's spend over a UTC date range, grouped by source, user, agent, or model. groups lists every entity with nonzero spend in the range (uncapped); UNKNOWN sorts last. Pass group_by_period to additionally receive per-period series aligned to period_list.
Get the factory's most expensive PRs
The costliest PRs first seen in the range, most expensive first, with per-component cost breakdowns, attribution from each PR's earliest live root run, and PR detail collected from code-forge webhooks. PRs that predate webhook PR-fact collection still appear, with null detail fields.
List the factory's pull requests
One record per pull request produced by the factory's runs, newest opened first. A PR someone opened in one of the factory's repositories without a factory run (by hand, for example) is not listed. Each record carries the PR's identity, state and times, size, human interactions, the runs that produced it, and its cycle time. Pages are keyset-paginated: pass page_info.next_cursor back as cursor to continue. Pass updated_after to sync incrementally.
Get the factory's run counts grouped by a dimension
The factory's run counts over a UTC date range, grouped by one dimension. Pass group_by_period to additionally receive per-period series aligned to period_list.
Get the factory's PR cost distribution grouped by PR size
The mean per-PR attributed cost of the factory's PRs first seen in a UTC date range, grouped by PR size. Pass group_by_period to additionally receive per-period mean series aligned to period_list.
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.
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 run transcript
Retrieve the raw conversation transcript for an agent run. Returns a 302 redirect to a time-limited download URL for the transcript.
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.
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.
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.
List agent runs
Retrieve a paginated list of agent runs with optional filtering. Results default to `sort_by=updated_at` and `sort_order=desc`.
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.
Get multiple runs by ID
Retrieve run details for 1–100 run IDs. Returns a top-level array in input order, preserving duplicates with one result per input occurrence. Each result contains the requested run_id and exactly one of `run`, the same run object returned by getRun, or `error`, the standard API error getRun would return for that ID. Authorization and per-run errors follow getRun semantics. Completed batches return HTTP 200 even when every result is an error; shared infrastructure failures fail the request with HTTP 500.
Get run details
Retrieve detailed information about a specific agent run, including the full prompt, session link, and resolved configuration.
Get run timeline
Retrieve chronological setup and lifecycle timeline events for an agent run.
Get run diagnostics
Retrieve diagnostics recorded for an agent run.
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.
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.
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.
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.
List handoff snapshot attachments for a run
Return fresh presigned download URLs for handoff snapshot files uploaded by the latest ended execution of this run. An empty list is returned when no ended execution exists or no snapshot files were uploaded. This endpoint is useful for third-party harnesses that want to download the snapshot files produced by a previous execution before starting a handoff execution themselves.
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.
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.
Get normalized conversation
Retrieve a conversation directly by conversation ID in Warp's normalized task/message format.
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).
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.
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.
List scheduled agents
Retrieve all scheduled agents accessible to the authenticated user. Results are sorted alphabetically by name.
Get scheduled agent details
Retrieve detailed information about a specific scheduled agent, including its configuration, history, and next scheduled run time.
Update a scheduled agent
Update an existing scheduled agent's configuration. All fields except agent_config are required.
Delete a scheduled agent
Delete a scheduled agent. This will stop all future scheduled runs.
Pause a scheduled agent
Pause a scheduled agent. The agent will not run until resumed.
Resume a scheduled agent
Resume a paused scheduled agent. The agent will start running according to its cron schedule.
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.
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 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.
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.
Update a scorer's definition
Apply a partial update to a scorer's definition; omitted fields are left unchanged, but at least one field must be provided, and the owning factory is immutable. Each update bumps the scorer's version without invalidating any scoring judge already in flight, since judges validate against the definition snapshot taken at dispatch time, and historical scores keep their recorded classification values. Supplying `scope_mode` or `agent_uids` replaces the scorer's scope in full.
Delete a scorer
Permanently delete a scorer. This is not reversible and it is not an archive: the scorer's scoring attempts, scores, judge reasoning, self-improvement config, and self-improvement triage results go with it, and the scorer stops being readable through this API as soon as the call returns. The underlying rows and the judge-reasoning blobs stored outside the database are destroyed shortly afterwards by the deletion sweep, which removes each blob before the record that references it and retries until both are gone.
Download a conversation's block snapshot
Redirect to a signed storage URL for the serialized block snapshot. Set redirect=false to return the URL as JSON instead. Both modes require permission to view the conversation.
Create an agent
Create a new agent in the caller's active team. Agents act autonomously with their own permissions, configuration, and identity.
List agents
List all agents on the caller's team.
Create a scorer
Create an active run scorer for a factory with either selected-agent or all-agent scope. Creating a scorer does not start scoring. Pass self_improvement_enabled to also turn on self-improvement for the new scorer in the same request; the scorer and its self-improvement config are created atomically.
List agent scorers
List the scorers in the factory named in the path, including scope agents and aggregate scoring stats.
List results for a scorer
List the scorer's most recent scoring attempts, newest first. A failed attempt carries no classification. Pagination is a keyset cursor over attempted_at with the attempt id as a stable tiebreak. Repeat `run_id` to return all matching results without pagination; unknown runs are omitted. Reasons are read from object storage only when include_reasons is true.
Get scorer metrics over a date range
Returns a period-aligned pass-rate series plus a full-range aggregate for the scorer, computed directly from every live score in [start_date, end_date). Binning follows the same day/week/month rules and 365-period cap as `GET /factory/{uid}/metrics`.
Manually dispatch scorers for a run
Evaluate one run with the scorers in `scorer_uids`. To evaluate multiple runs with one scorer, use `/factory/{factory_uid}/scorers/{scorer_uid}/dispatch`. Manual dispatch skips automatic scoring's cool-down and sampling (including 0%) and supports older or previously scored runs. Requires manage access to the factory and view access to the run. The run must have a conversation and be executed by a factory agent, not be a scoring job. The run and scorers must belong to this factory and team. Each scorer must be configured for the run's agent and must not be benchmark-managed. Provide 1–100 scorer UUIDs. Run and scorer UUIDs must be nonzero. Invalid selections reject the whole request before any scoring jobs start. Returns dispatch outcomes, not completed scores. Valid requests can have individual failures; inspect each result's `status` and `error`.
Manually dispatch a scorer for selected runs
Evaluate the runs in `run_ids` with one scorer. To evaluate one run with multiple scorers, use `/factory/{factory_uid}/runs/{run_id}/scorer_dispatch`. Manual dispatch skips automatic scoring's cool-down and sampling (including 0%) and supports older or previously scored runs. Requires manage access to the factory and view access to every run. Runs must have conversations and be executed by factory agents, not be scoring jobs. The scorer and runs must belong to this factory and team. The scorer must be configured for each run's agent and must not be benchmark-managed. Provide 1–100 run UUIDs. Run and scorer UUIDs must be nonzero. Invalid selections reject the whole request before any scoring jobs start. Returns dispatch outcomes, not completed scores. Valid requests can have individual failures; inspect each result's `status` and `error`.
Read a run's current scores
List the current live attempt for each evaluation that has attempted the given run, most recent attempt first. Excludes a deleted evaluation's data. Requires only view access to the run, since reading scores is part of viewing the run.
Retrieve an agent
Retrieve a single agent by its unique identifier.
Update an agent
Update an existing agent.
Delete an agent
Delete an agent. All API keys associated with the agent are deleted atomically.
Get session redirect
Check whether a shared session should redirect to a conversation transcript, returning a conversation_id if the agent sandbox has finished and conversation data is available (or an empty object if no redirect is needed). Public and unauthenticated, so anonymous viewers can resolve a shared session link before signing in; access to the underlying transcript is still gated by conversation link-sharing.
Get conversation redirect
Check whether a conversation should redirect to a live shared session, returning a session_id if the underlying ambient agent task still has one (or an empty object if no redirect is needed). Public and unauthenticated, so anonymous viewers can resolve a shared conversation link before signing in; access to the underlying live session is still gated by the session-sharing service ACLs.
Create a benchmark suite
List benchmark suites
Get a benchmark suite with its tasks and configurations
Edit a benchmark suite
Soft-delete a benchmark suite
Create a benchmark suite task
This adds a single hand-authored task to a suite, without needing to resend the whole task list. A title, prompt, and success criteria are required, and if a `source_run_id` is included, the caller must have permission to read that run. Adding the exact same task twice simply returns the existing one (so retrying is safe), while reusing a title with different content is rejected as a conflict — and on a `code.storage`-managed Factory, the task is saved as a file and returned from that file.
Get one benchmark suite task
Edit one benchmark suite task
Edits a single task in place without resending the suite's full task list. Omitted fields keep their current values. title, prompt, and success_criteria reject null and empty-after-trim values. An explicit null source_run_id clears provenance. An explicit empty starting_repo_refs or tags clears that field.
Delete one benchmark suite task
Launch a benchmark run from the current suite version
Each successful request creates a new run. Launch is not idempotent: disable automatic retries for this request and reconcile an uncertain outcome by listing runs before launching again. Retries are a client transport option, not a request-body field. In the TypeScript SDK, pass { maxRetries: 0 } as the request options. In the Python SDK, call create through client.with_options(max_retries=0). These options do not change execution retries within the benchmark run.
List benchmark runs
List runs launched from this benchmark suite. Each entry contains the run's status and execution/scoring progress. Use `include` to add launch settings, aggregate results, or the creator's display name to each entry. The response contains a page of runs in `data` and continuation information in `page_info`. Retained runs remain readable after the suite is deleted; an unknown suite returns an empty list.
Get benchmark run detail
Retrieve a benchmark run's status and execution/scoring progress. By default, the response omits launch settings and aggregate results. Use `include` to add these fields or the creator's display name. Retrieve trials separately for individual scores and execution history.
Cancel an in-flight benchmark run
Get benchmark run results
Retrieve aggregate outcomes, coverage, and costs for the run. Task and tag filters select the trials used to calculate the results. By default, the response contains summary fields without detailed metric arrays; use `include` to add those arrays. Configuration and scorer filters limit returned metric rows without changing the summary or comparison populations. Results cover the whole selected dataset, independently of trial-list pages, and are not paginated.
List benchmark trials or find the trial for an agent run
Each trial represents one task, configuration, and repetition within the benchmark run. The response contains a page of trials in `data` and continuation information in `page_info`. Use `include` to add scores, metrics, or retained execution history to each trial. Repeated values match any value within a filter; different filters must all match. To find the trial for a primary agent execution, pass `agent_run_id`. This returns zero or one trial, with `matched_attempt_number` identifying the matching attempt. Judge runs and spawned descendant runs do not match. This lookup accepts `include` and an omitted `limit` or `limit=1`, but no cursor or other filters. Filtering by scorer is not supported.
Retrieve an individual benchmark trial within a run
Retrieve the trial's execution and scoring status for one task, configuration, and repetition within the run. Include results to retrieve its scores and metrics, or details to retrieve retained execution attempts and judge history. Each requested expansion is complete. Selection and pagination parameters are not supported.
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.
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.
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 ```
See something wrong? Edit this page or open an issue.