Agent

Operations for running and managing cloud agents

List available agents

get

Retrieve a list of available agents (skills) that can be used to run tasks. Agents are discovered from environments or a specific repository.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Query parameters

repostringOptional

Optional repository specification to list agents from (format: "owner/repo"). If not provided, lists agents from all accessible environments.

refreshbooleanOptional

When true, clears the agent list cache before fetching. Use this to force a refresh of the available agents.

Default: false

sort_bystring · enumOptional

Sort order for the returned agents.

• "name": Sort alphabetically by name (default)
• "last_run": Sort by most recently used

Possible values:

include_malformed_skillsbooleanOptional

When true, includes skills whose SKILL.md file exists but is malformed. These variants will have a non-empty error field describing the parse failure. Defaults to false.

Default: false

Responses

200

List of available agents

application/json

400

Invalid repository specification

application/json

401

Authentication required

application/json

500

Internal server error

application/json

get

/agent

HTTPcURLJavaScriptPython

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

{
  "agents": [
    {
      "name": "text",
      "variants": [
        {
          "id": "text",
          "description": "text",
          "base_prompt": "text",
          "source": {
            "owner": "text",
            "name": "text",
            "skill_path": "text"
          },
          "environments": [
            {
              "uid": "text",
              "name": "text"
            }
          ],
          "last_run_timestamp": "2026-04-03T21:39:42.548Z",
          "error": "text"
        }
      ]
    }
  ]
}

Run an agent task

post

Spawn a cloud 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 a Warp API key.

Body

application/json

Request body for creating a new agent run. Either prompt or skill (via skill field or config.skill_spec) is required.

promptstringOptional

The prompt/instruction for the agent to execute. Required unless a skill is specified via the skill field or config.skill_spec.

skillstringOptional

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.

titlestringOptional

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

teambooleanOptional

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

conversation_idstringOptional

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

parent_run_idstringOptional

Optional run ID of the parent that spawned this run. Used for orchestration hierarchies.

interactivebooleanOptional

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

Responses

200

Run created successfully

application/json

run_idstringRequired

Unique identifier for the created run

task_idstringRequiredDeprecated

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

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
• BLOCKED: Run is blocked (e.g., awaiting user input or approval)
• ERROR: Run encountered an error
• CANCELLED: Run was cancelled by user

Possible values:

at_capacitybooleanOptional

Whether the system is at capacity when the run was created

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",
  "at_capacity": true
}

List agent runs

get

Retrieve a paginated list of agent runs with optional filtering. Results default to sort_by=updated_at and sort_order=desc.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Query parameters

limitinteger · min: 1 · max: 500Optional

Maximum number of runs to return

Default: 20

cursorstringOptional

Pagination cursor from previous response

sort_bystring · enumOptional

Sort field for results.

• updated_at: Sort by last update timestamp (default)
• created_at: Sort by creation timestamp
• title: Sort alphabetically by run title
• agent: Sort alphabetically by skill. Runs without a skill are grouped last.

Default: updated_atPossible values:

sort_orderstring · enumOptional

Sort direction

Default: descPossible values:

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
• WEB_APP: Created from the Warp web app
• GITHUB_ACTION: Created from a GitHub action
• CLOUD_MODE: Created from a Cloud Mode
• CLI: Created from the CLI

Possible values:

execution_locationstring · enumOptional

Where the run executed:

• LOCAL: Executed in the user's local Oz environment
• REMOTE: Executed by a remote/cloud worker

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)

updated_afterstring · date-timeOptional

Filter runs updated after this timestamp (RFC3339 format)

environment_idstringOptional

Filter runs by environment ID

skillstringOptional

Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec.

skill_specstringOptional

Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")

schedule_idstringOptional

Filter runs by the scheduled agent ID that created them

artifact_typestring · enumOptional

Filter runs by artifact type

Possible values:

qstringOptional

Fuzzy search query across run title, prompt, and skill_spec

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",
      "execution_location": "LOCAL",
      "prompt": "text",
      "created_at": "2026-04-03T21:39:42.548Z",
      "updated_at": "2026-04-03T21:39:42.548Z",
      "started_at": "2026-04-03T21:39:42.548Z",
      "status_message": {
        "message": "text",
        "error_code": "insufficient_credits",
        "retryable": true
      },
      "source": "LINEAR",
      "schedule": {
        "schedule_id": "text",
        "schedule_name": "text",
        "cron_schedule": "text"
      },
      "session_id": "text",
      "session_link": "https://example.com",
      "creator": {
        "type": "user",
        "uid": "text",
        "display_name": "text",
        "email": "text",
        "photo_url": "https://example.com"
      },
      "request_usage": {
        "inference_cost": 1,
        "compute_cost": 1
      },
      "agent_config": {
        "name": "text",
        "model_id": "text",
        "base_prompt": "text",
        "environment_id": "text",
        "skill_spec": "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"
            }
          }
        },
        "computer_use_enabled": true,
        "idle_timeout_minutes": 1,
        "worker_host": "text",
        "harness": {
          "type": "text"
        }
      },
      "conversation_id": "text",
      "is_sandbox_running": true,
      "artifacts": [
        {
          "artifact_type": "PLAN",
          "created_at": "2026-04-03T21:39:42.548Z",
          "data": {
            "document_uid": "text",
            "notebook_uid": "text",
            "title": "text"
          }
        }
      ],
      "agent_skill": {
        "name": "text",
        "description": "text",
        "full_path": "text",
        "bundled_skill_id": "text"
      },
      "scope": {
        "type": "User",
        "uid": "text"
      }
    }
  ],
  "page_info": {
    "has_next_page": true,
    "next_cursor": "text"
  }
}

Run an agent task (preferred)

post

Alias for POST /agent/run. This is the preferred endpoint for creating new agent runs. Behavior is identical to POST /agent/run.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Body

application/json

Request body for creating a new agent run. Either prompt or skill (via skill field or config.skill_spec) is required.

promptstringOptional

The prompt/instruction for the agent to execute. Required unless a skill is specified via the skill field or config.skill_spec.

skillstringOptional

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.

titlestringOptional

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

teambooleanOptional

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

conversation_idstringOptional

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

parent_run_idstringOptional

Optional run ID of the parent that spawned this run. Used for orchestration hierarchies.

interactivebooleanOptional

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

Responses

200

Run created successfully

application/json

run_idstringRequired

Unique identifier for the created run

task_idstringRequiredDeprecated

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

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
• BLOCKED: Run is blocked (e.g., awaiting user input or approval)
• ERROR: Run encountered an error
• CANCELLED: Run was cancelled by user

Possible values:

at_capacitybooleanOptional

Whether the system is at capacity when the run was created

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/runs

HTTPcURLJavaScriptPython

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

{
  "prompt": "text",
  "skill": "text",
  "config": {
    "name": "text",
    "model_id": "text",
    "base_prompt": "text",
    "environment_id": "text",
    "skill_spec": "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"
        }
      }
    },
    "computer_use_enabled": true,
    "idle_timeout_minutes": 1,
    "worker_host": "text",
    "harness": {
      "type": "text"
    }
  },
  "title": "text",
  "team": true,
  "conversation_id": "text",
  "attachments": [
    {
      "file_name": "text",
      "mime_type": "text",
      "data": "Ynl0ZXM="
    }
  ],
  "parent_run_id": "text",
  "interactive": true
}

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

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 a Warp API key.

Path parameters

runIdstringRequired

The unique identifier of the run

Responses

200

Run details

application/json

run_idstringRequired

Unique identifier for the run

task_idstringRequiredDeprecated

Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead.

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
• BLOCKED: Run is blocked (e.g., awaiting user input or approval)
• ERROR: Run encountered an error
• CANCELLED: Run was cancelled by user

Possible values:

execution_locationstring · enumOptional

Where the run executed:

• LOCAL: Executed in the user's local Oz environment
• REMOTE: Executed by a remote/cloud worker

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
• WEB_APP: Created from the Warp web app
• GITHUB_ACTION: Created from a GitHub action
• CLOUD_MODE: Created from a Cloud Mode
• CLI: Created from the CLI

Possible values:

session_idstringOptional

UUID of the shared session (if available)

session_linkstring · uriOptional

URL to view the agent session

conversation_idstringOptional

UUID of the conversation associated with the run

is_sandbox_runningbooleanOptional

Whether the sandbox environment is currently running

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",
  "execution_location": "LOCAL",
  "prompt": "text",
  "created_at": "2026-04-03T21:39:42.548Z",
  "updated_at": "2026-04-03T21:39:42.548Z",
  "started_at": "2026-04-03T21:39:42.548Z",
  "status_message": {
    "message": "text",
    "error_code": "insufficient_credits",
    "retryable": true
  },
  "source": "LINEAR",
  "schedule": {
    "schedule_id": "text",
    "schedule_name": "text",
    "cron_schedule": "text"
  },
  "session_id": "text",
  "session_link": "https://example.com",
  "creator": {
    "type": "user",
    "uid": "text",
    "display_name": "text",
    "email": "text",
    "photo_url": "https://example.com"
  },
  "request_usage": {
    "inference_cost": 1,
    "compute_cost": 1
  },
  "agent_config": {
    "name": "text",
    "model_id": "text",
    "base_prompt": "text",
    "environment_id": "text",
    "skill_spec": "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"
        }
      }
    },
    "computer_use_enabled": true,
    "idle_timeout_minutes": 1,
    "worker_host": "text",
    "harness": {
      "type": "text"
    }
  },
  "conversation_id": "text",
  "is_sandbox_running": true,
  "artifacts": [
    {
      "artifact_type": "PLAN",
      "created_at": "2026-04-03T21:39:42.548Z",
      "data": {
        "document_uid": "text",
        "notebook_uid": "text",
        "title": "text"
      }
    }
  ],
  "agent_skill": {
    "name": "text",
    "description": "text",
    "full_path": "text",
    "bundled_skill_id": "text"
  },
  "scope": {
    "type": "User",
    "uid": "text"
  }
}

Cancel a run

post

Cancel an agent run that is currently queued or in progress. Once cancelled, the run will transition to a cancelled state.

Not all runs can be cancelled. Runs that are in a terminal state (SUCCEEDED, FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in PENDING state return 409 (retry after a moment). Self-hosted, local, and GitHub Action runs return 422.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

runIdstringRequired

The unique identifier of the run to cancel

Responses

200

Run cancelled successfully

application/json

stringOptional

The ID of the cancelled run

400

Missing run ID, or the run is already in a terminal state (error_code: invalid_request)

application/json

401

Authentication required

application/json

403

No permission to cancel run

application/json

404

Run not found

application/json

409

Run is in PENDING state and cannot be cancelled yet. Retry after a moment (error_code: conflict, retryable: true).

application/json

422

Run cannot be cancelled because the operation is not supported for this run type (e.g., self-hosted, local, or GitHub Action runs) (error_code: operation_not_supported)

application/json

post

/agent/runs/{runId}/cancel

HTTPcURLJavaScriptPython

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

text

Get run transcript

get

Retrieve the raw conversation transcript for an agent run. Returns a 302 redirect to a time-limited download URL for the transcript.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

runIdstringRequired

The unique identifier of the run

Responses

302

Redirect to a download URL for the transcript

400

Missing run ID

application/json

401

Authentication required

application/json

403

No permission to access run transcript

application/json

404

Run not found or has no transcript

application/json

500

Internal server error

application/json

get

/agent/runs/{runId}/transcript

HTTPcURLJavaScriptPython

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

No content

Send a message to one or more runs

post

Send a point-to-point message to one or more agent runs. Each recipient gets an independent message row with its own delivery state. Requires the OrchestrationV2 feature flag.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Body

application/json

tostring[]Required

List of recipient run IDs

subjectstring · max: 1024Required

Message subject

bodystring · max: 131072Required

Message body (max 128KB)

sender_run_idstringRequired

The sender's run ID

Responses

200

Message sent successfully

application/json

message_idsstring[]Optional

One message ID per recipient, in the same order as the to array

422

One or more recipients are in a terminal state

post

/agent/messages

HTTPcURLJavaScriptPython

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

{
  "to": [
    "text"
  ],
  "subject": "text",
  "body": "text",
  "sender_run_id": "text"
}

{
  "message_ids": [
    "text"
  ]
}

List inbox message headers

get

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

runIdstringRequired

Query parameters

unreadbooleanOptional

sincestring · date-timeOptional

limitinteger · max: 100OptionalDefault: 50

Responses

200

List of message headers

application/json

message_idstringOptional

sender_run_idstringOptional

subjectstringOptional

sent_atstring · date-timeOptional

delivered_atstring · date-time · nullableOptional

read_atstring · date-time · nullableOptional

get

/agent/messages/{runId}

HTTPcURLJavaScriptPython

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

200

List of message headers

[
  {
    "message_id": "text",
    "sender_run_id": "text",
    "subject": "text",
    "sent_at": "2026-04-03T21:39:42.548Z",
    "delivered_at": "2026-04-03T21:39:42.548Z",
    "read_at": "2026-04-03T21:39:42.548Z"
  }
]

Read a message body

post

Returns the full message body and sets read_at.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

messageIdstringRequired

Responses

200

Full message content

application/json

message_idstringOptional

sender_run_idstringOptional

subjectstringOptional

bodystringOptional

sent_atstring · date-timeOptional

delivered_atstring · date-time · nullableOptional

read_atstring · date-time · nullableOptional

post

/agent/messages/{messageId}/read

HTTPcURLJavaScriptPython

POST /api/v1/agent/messages/{messageId}/read HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Full message content

{
  "message_id": "text",
  "sender_run_id": "text",
  "subject": "text",
  "body": "text",
  "sent_at": "2026-04-03T21:39:42.548Z",
  "delivered_at": "2026-04-03T21:39:42.548Z",
  "read_at": "2026-04-03T21:39:42.548Z"
}

Mark a message as delivered

post

Sets delivered_at if not already set. Idempotent.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

messageIdstringRequired

Responses

204

Delivered

post

/agent/messages/{messageId}/delivered

HTTPcURLJavaScriptPython

POST /api/v1/agent/messages/{messageId}/delivered HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Delivered

No content

Poll for events

get

Batch poll for events across multiple watched runs. Returns events ordered by monotonic sequence number. Client advances the cursor (since parameter) on each poll.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Query parameters

run_idsstring[]Required

sinceinteger · int64OptionalDefault: 0

limitinteger · max: 500OptionalDefault: 100

Responses

200

List of events

application/json

event_typestringOptional

run_idstringOptional

ref_idstring · nullableOptional

execution_idstring · nullableOptional

occurred_atstring · date-timeOptional

sequenceinteger · int64Optional

get

/agent/events

HTTPcURLJavaScriptPython

GET /api/v1/agent/events?run_ids=text HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of events

[
  {
    "event_type": "text",
    "run_id": "text",
    "ref_id": "text",
    "execution_id": "text",
    "occurred_at": "2026-04-03T21:39:42.548Z",
    "sequence": 1
  }
]

Report a lifecycle event

post

Client reports a lifecycle event for a run. This is the canonical mechanism for all lifecycle events.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

runIdstringRequired

Body

application/json

event_typestring · enumRequiredPossible values:

execution_idstringOptional

Client-assigned execution ID for correlation

ref_idstringOptional

Event-type-specific reference (e.g., message ID for new_message events)

Responses

200

Event recorded

application/json

sequenceinteger · int64Optional

post

/agent/events/{runId}

HTTPcURLJavaScriptPython

POST /api/v1/agent/events/{runId} HTTP/1.1
Host: app.warp.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "event_type": "run_idle",
  "execution_id": "text",
  "ref_id": "text"
}

200

Event recorded

{
  "sequence": 1
}

List available models

get

Retrieve the list of LLM models available to the authenticated user for agent runs. The response includes which model is the default, as well as per-model metadata such as provider, cost, and whether the model is currently disabled (and why).

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Responses

200

List of available models

application/json

default_model_idstringRequired

The ID of the default model for agent runs

401

Authentication required

application/json

500

Internal server error

application/json

get

/agent/models

HTTPcURLJavaScriptPython

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

{
  "default_model_id": "text",
  "models": [
    {
      "id": "text",
      "display_name": "text",
      "provider": "OPENAI",
      "vision_supported": true,
      "description": "text",
      "reasoning_level": "text",
      "disable_reason": "PROVIDER_OUTAGE"
    }
  ]
}

Get artifact details

get

Retrieve an artifact by its UUID. For screenshot artifacts, returns a time-limited signed download URL.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

artifactUidstringRequired

The unique identifier (UUID) of the artifact

Responses

200

Artifact details with download information

application/json

Response for artifact retrieval. Currently supports screenshot artifacts.

artifact_uidstringRequired

Unique identifier (UUID) for the artifact

artifact_typestringRequired

Type of the artifact (e.g., SCREENSHOT)

created_atstring · date-timeRequired

Timestamp when the artifact was created (RFC3339)

400

Missing artifact UID

application/json

401

Authentication required

application/json

403

No permission to access artifact

application/json

404

Artifact not found or unsupported artifact type

application/json

get

/agent/artifacts/{artifactUid}

HTTPcURLJavaScriptPython

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

{
  "artifact_uid": "text",
  "artifact_type": "text",
  "created_at": "2026-04-03T21:39:42.548Z",
  "data": {
    "download_url": "https://example.com",
    "expires_at": "2026-04-03T21:39:42.548Z",
    "content_type": "text",
    "description": "text"
  }
}

Get session redirect

get

Check whether a shared session should redirect to a conversation transcript. Returns a conversation_id if the agent sandbox has finished and conversation data is available, or an empty object if no redirect is needed.

Authorizations

bearerAuth

AuthorizationstringRequired

Authentication via a Warp API key.

Path parameters

sessionUuidstringRequired

The UUID of the shared session

Responses

200

Redirect information. Contains conversation_id if redirect is needed, otherwise an empty object.

application/json

conversation_idstringOptional

The conversation ID to redirect to (only present when redirect is needed)

500

Internal server error

application/json

get

/agent/sessions/{sessionUuid}/redirect

HTTPcURLJavaScriptPython

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

{
  "conversation_id": "text"
}