Sign in
agent

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.

post/agent/runs

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, and the calling agent must have on_behalf_of enabled in its configuration (on_behalf_of_enabled), which a team admin must intentionally turn on per agent. The target user must be an active member of the run's owner team. Only valid for team-owned runs.

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; otherwise 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. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); values are 0-256 bytes of UTF-8 and cannot contain 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