Sign in

v1

latestOpenAPI 3.0.0Proprietary2026-07-132885152.8 KB
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.

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.

interactiveboolean

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

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