Agent

Run an agent task

post

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

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via personal API key or service account credentials.

Body

application/json

promptstringRequired

The prompt/instruction for the agent to execute

titlestringOptional

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

teambooleanOptional

Make the run visible to all team members, not only the calling user

Default: false

Responses

200

Run created successfully

application/json

run_idstringRequired

Unique identifier for the created run

statestring · enumRequired

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

Possible values:

400

Invalid request (missing prompt, invalid config)

application/json

401

Authentication required

application/json

403

No permission to access referenced resources (environment, MCP servers)

application/json

post

/agent/run

HTTPcURLJavaScriptPython

POST /api/v1/agent/run HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "prompt": "Fix the bug in auth.go"
}

Simple promptWith agent config

{
  "run_id": "text",
  "state": "QUEUED"
}

List agent runs

get

Retrieve a paginated list of agent runs with optional filtering. Results are ordered by creation time (newest first).

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via personal API key or service account credentials.

Query parameters

limitinteger · min: 1 · max: 500Optional

Maximum number of runs to return

Default: 20

cursorstringOptional

Pagination cursor from previous response

config_namestringOptional

Filter by agent config name

model_idstringOptional

Filter by model ID

creatorstringOptional

Filter by creator UID (user or service account)

sourcestring · enumOptional

Source that created the run:

• LINEAR: Created from Linear integration
• API: Created via the Warp API
• SLACK: Created from Slack integration
• LOCAL: Created from local CLI/app
• SCHEDULED_AGENT: Created by a scheduled agent

Possible values:

created_afterstring · date-timeOptional

Filter runs created after this timestamp (RFC3339 format)

created_beforestring · date-timeOptional

Filter runs created before this timestamp (RFC3339 format)

Responses

200

List of runs

application/json

400

Invalid request parameters

application/json

401

Authentication required

application/json

get

/agent/runs

HTTPcURLJavaScriptPython

GET /api/v1/agent/runs HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "runs": [
    {
      "run_id": "text",
      "title": "text",
      "state": "QUEUED",
      "prompt": "text",
      "created_at": "2026-02-21T22:38:19.077Z",
      "updated_at": "2026-02-21T22:38:19.077Z",
      "started_at": "2026-02-21T22:38:19.077Z",
      "status_message": {
        "message": "text"
      },
      "source": "LINEAR",
      "session_id": "text",
      "session_link": "https://example.com",
      "creator": {
        "type": "user",
        "uid": "text"
      },
      "agent_config": {
        "name": "text",
        "model_id": "text",
        "base_prompt": "text",
        "environment_id": "text",
        "mcp_servers": {
          "ANY_ADDITIONAL_PROPERTY": {
            "warp_id": "text",
            "command": "text",
            "args": [
              "text"
            ],
            "url": "https://example.com",
            "env": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            }
          }
        }
      }
    }
  ],
  "page_info": {
    "has_next_page": true,
    "next_cursor": "text"
  }
}

Get run details

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via personal API key or service account credentials.

Path parameters

runIdstringRequired

The unique identifier of the run

Responses

200

Run details

application/json

run_idstringRequired

Unique identifier for the run

titlestringRequired

Human-readable title for the run

statestring · enumRequired

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

Possible values:

promptstringRequired

The prompt/instruction for the agent

created_atstring · date-timeRequired

Timestamp when the run was created (RFC3339)

updated_atstring · date-timeRequired

Timestamp when the run was last updated (RFC3339)

started_atstring · date-time · nullableOptional

Timestamp when the agent started working on the run (RFC3339)

sourcestring · enumOptional

Source that created the run:

• LINEAR: Created from Linear integration
• API: Created via the Warp API
• SLACK: Created from Slack integration
• LOCAL: Created from local CLI/app
• SCHEDULED_AGENT: Created by a scheduled agent

Possible values:

session_idstringOptional

UUID of the shared session (if available)

session_linkstring · uriOptional

URL to view the agent session

400

Missing run ID

application/json

401

Authentication required

application/json

403

No permission to access run

application/json

404

Run not found

application/json

get

/agent/runs/{runId}

HTTPcURLJavaScriptPython

GET /api/v1/agent/runs/{runId} HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "run_id": "text",
  "title": "text",
  "state": "QUEUED",
  "prompt": "text",
  "created_at": "2026-02-21T22:38:19.077Z",
  "updated_at": "2026-02-21T22:38:19.077Z",
  "started_at": "2026-02-21T22:38:19.077Z",
  "status_message": {
    "message": "text"
  },
  "source": "LINEAR",
  "session_id": "text",
  "session_link": "https://example.com",
  "creator": {
    "type": "user",
    "uid": "text"
  },
  "agent_config": {
    "name": "text",
    "model_id": "text",
    "base_prompt": "text",
    "environment_id": "text",
    "mcp_servers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "warp_id": "text",
        "command": "text",
        "args": [
          "text"
        ],
        "url": "https://example.com",
        "env": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      }
    }
  }
}