WAwarp
Agents

Run a cloud agent

Changed on

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

Request

  • Base URL
    https://app.warp.dev/api/v1
  • Auth
    HTTP bearer

Headers

X-Warp-Team-Uidstring

UID of the team to use as the request's active team. Ignored for service-account callers, which always act as their bound team.

Request body

promptstring

The prompt/instruction for the agent to execute. Required unless a skill is specified via the skill field, config.skill_spec, or config.skills. Handoff requests may omit prompt when conversation_id is set.

mode'normal' | 'plan' | 'orchestrate'

Query mode for an agent run.

  • normal: Standard user query (default).
  • plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.
  • orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
skillstring

Skill specification to use as the base prompt for the agent. Supported formats:

  • "repo:skill_name" - Simple name in specific repo
  • "repo:skill_path" - Full path in specific repo
  • "org/repo:skill_name" - Simple name with org and repo
  • "org/repo:skill_path" - Full path with org and repo When provided, this takes precedence over config.skill_spec.
titlestring

Custom title for the run (auto-generated if not provided)

teamboolean

Whether to create a team-owned run. Defaults to true for users on a single team.

agent_identity_uidstring

Optional agent identity UID to use as the execution principal for the run. This is only valid for runs that are team owned.

on_behalf_ofstring

Optional email address or user ID of a Warp user to attribute the run to; when set, the resolved user becomes the run's creator instead of the caller. Only agent API keys may use this field, only when the calling agent has on_behalf_of enabled in its configuration (a team admin must turn this on per agent), and only for team-owned runs. The target user must be an active member of the run's owner team.

conversation_idstring

Optional conversation ID to continue an existing conversation. If provided, the agent will continue from where the previous run left off.

parent_run_idstring

Optional run ID of the parent that spawned this run, used for orchestration hierarchies; the parent run must exist and be visible to the caller, or the request is rejected with a 400. Child runs are also subject to the server's maximum orchestration depth, and requests that would exceed it are rejected with a 400.

interactiveboolean

Whether the run should be interactive. If not set, defaults to false.

metadataRunMetadata

Custom key/value metadata attached to a run at creation time and immutable afterward; at most 20 keys, with keys 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with no NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).

Response

Run created successfully

run_idstring required

Unique identifier for the created run

task_idstring required

Unique identifier for the task (same as run_id). Deprecated - use run_id instead.

state'QUEUED' | 'PENDING' | 'CLAIMED' | 'INPROGRESS' | 'SUCCEEDED' | 'FAILED' | 'BLOCKED' | 'ERROR' | 'CANCELLED' required

Current state of the run:

  • QUEUED: Run is waiting to be picked up
  • PENDING: Run is being prepared
  • CLAIMED: Run has been claimed by a worker
  • INPROGRESS: Run is actively being executed
  • SUCCEEDED: Run completed successfully
  • FAILED: Run failed
  • BLOCKED: Run is blocked (e.g., awaiting user input or approval)
  • ERROR: Run encountered an error
  • CANCELLED: Run was cancelled by user
at_capacityboolean

Whether the system is at capacity when the run was created

Changes

  • 2c45dcc0a13eRevision changes
    • breaking

      the request property / became not nullable

    • breaking

      removed the enum value CREATOR of the request property /

    • breaking

      removed the enum value EXECUTOR of the request property /

    • breaking

      removed the enum value claude of the request property //

    • breaking

      removed the enum value codex of the request property //

    • breaking

      removed the enum value gemini of the request property //

    • breaking

      removed the enum value oz of the request property //

    • breaking

      the // request property type changed from string to no type

    • info

      added the new optional request property //

    • info

      request property / list-of-types was widened by adding types null to media type application/json

    • info

      added subschema #1 to the // request property oneOf list

  • 96d1e59a65c5Revision changes
    • info

      added the new optional request property /