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 task 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 task (auto-generated if not provided)

Responses

200

Task created successfully

application/json

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

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

List agent tasks

get

Retrieve a paginated list of agent tasks 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 tasks 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 task:

• LINEAR: Created from Linear integration
• API: Created via the public 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 tasks created after this timestamp (RFC3339 format)

created_beforestring · date-timeOptional

Filter tasks created before this timestamp (RFC3339 format)

Responses

200

List of tasks

application/json

400

Invalid request parameters

application/json

401

Authentication required

application/json

get

/agent/tasks

HTTPcURLJavaScriptPython

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

{
  "tasks": [
    {
      "task_id": "text",
      "title": "text",
      "state": "QUEUED",
      "prompt": "text",
      "created_at": "2025-12-18T19:27:28.907Z",
      "updated_at": "2025-12-18T19:27:28.907Z",
      "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 task details

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via personal API key or service account credentials.

Path parameters

taskIdstringRequired

The unique identifier of the task

Responses

200

Task details

application/json

400

Missing task ID

application/json

401

Authentication required

application/json

403

No permission to access task

application/json

404

Task not found

application/json

get

/agent/tasks/{taskId}

HTTPcURLJavaScriptPython

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

{
  "task_id": "text",
  "title": "text",
  "state": "QUEUED",
  "prompt": "text",
  "created_at": "2025-12-18T19:27:28.907Z",
  "updated_at": "2025-12-18T19:27:28.907Z",
  "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"
        }
      }
    }
  }
}