> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Agent & run endpoints

Start, manage, and inspect cloud agent runs with the Agent and run endpoints in the Warp Platform API.

Agent & run endpoints are part of the Warp Platform API. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](https://docs.warp.dev/factories/factory-api/).

Note

Some examples use `oz` commands, such as `oz environment list`, from the Oz CLI. Existing commands remain supported during the transition.

## Use Agent & run endpoints

Agent & run endpoints let you create and inspect [cloud agent](https://docs.warp.dev/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without requiring the Warp desktop app.

**With the API you can:**

-   Run an agent by submitting a prompt plus optional config (model, environment, MCP servers, base prompt, etc.)
-   Monitor execution by listing runs and tracking state transitions over time (queued → in progress → succeeded/failed)
-   Inspect results and provenance by fetching a run’s full details, including the original prompt, source/creator metadata, session link, and resolved agent configuration

For endpoint details, use the [**Warp Platform API reference**](https://docs.warp.dev/api). For SDK schemas, use the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repositories.

To send work to a [Warp factory](https://docs.warp.dev/factories/), use [factory endpoints](https://docs.warp.dev/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/run` with a foreman’s `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched.

## Choose the SDK or raw REST

Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the Warp Platform API with:

-   **Typed requests and responses** (editor autocomplete, fewer schema mistakes)
-   **Built-in retries and timeouts** (with per-request overrides)
-   [**Consistent error types**](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes
-   **Helpers for raw responses** when you need headers/status or custom parsing

If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point.

![Warp Platform API reference overview video](https://i.ytimg.com/vi/0cf7383MZSk/sddefault.jpg)

**SDK vs raw REST**

-   Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns.
-   Use raw REST when you want minimal dependencies or full control over your HTTP client (the SDKs also support calling undocumented endpoints when needed).

* * *

## API base URL

All endpoints are served over HTTPS:

```http
https://app.warp.dev/api/v1
```

### Agent runs

An agent run represents a single execution of a cloud agent, created with a prompt and optional configuration. Each run has:

-   A unique `run_id`
-   A human-readable `title`
-   A `prompt` that the agent executes
-   A `state` (for example `QUEUED`, `INPROGRESS`, `SUCCEEDED`, `FAILED`)
-   Timestamps (`created_at`, `updated_at`)
-   Optional session information (`session_id`, `session_link`)
-   Optional resolved configuration (`agent_config`)

See the [**Warp Platform API reference**](https://docs.warp.dev/api) for details on how runs are created and listed.

### Agent configuration

You can influence how an agent runs using AmbientAgentConfig, including:

-   `name` — a human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](https://docs.warp.dev/agents/capabilities/skills/), `name` is automatically set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent — for example, grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name.
-   `model_id` for LLM selection
-   `base_prompt` to shape behavior
-   `environment_id` to choose a `CloudEnvironment`
-   `worker_host` to run a standalone cloud agent on a [self-hosted worker](https://docs.warp.dev/factories/self-hosting/)
-   `skill_spec` to use a [skill](https://docs.warp.dev/agents/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`)
-   `mcp_servers` to enable specific tools via MCP

See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema.

* * *

## Route a run to a self-hosted worker

Set `worker_host` in the request configuration to select a connected self-hosted worker. Omit it, or set it to `warp`, to use Warp-hosted workers.

```json
{
  "prompt": "Run the dependency audit",
  "config": {
    "worker_host": "WORKER_HOST"
  }
}
```

Replace `WORKER_HOST` with the ID of a connected worker. For factory work, set `workerHost` in the [factory definition](https://docs.warp.dev/factories/factory-as-code/#agentdefaultsworkerhost) instead.

## Key endpoints

Agent & run endpoints include:

-   `POST /agent/run`
    
    Create a new agent run with a prompt and optional config and title. Returns run\_id and initial state.
    
-   `GET /agent/runs`
    
    List runs with pagination and filters for state, config\_name, model\_id, creator, source, and creation time.
    
-   `GET /agent/runs/{runId}`
    
    Fetch full details for a single run, including session link and resolved configuration.
    
-   `POST /agent/runs/{runId}/followups`
    
    Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use.
    
-   `POST /agent/runs/{runId}/cancel`
    
    Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run.
    

All endpoint semantics, query parameters, and [error codes](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/) are documented in the [Warp Platform API reference](https://docs.warp.dev/api).

* * *

## Models

The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include:

-   `RunAgentRequest`
-   `RunAgentResponse`
-   `ListRunsResponse`
-   `RunItem`
-   `PageInfo`
-   `RunStatusMessage`
-   `RunCreatorInfo`
-   `RunState`
-   `RunSourceType`
-   `RunFollowupRequest`
-   `AmbientAgentConfig`
-   `MCPServerConfig`
-   `Error`

* * *

## SDKs

### Python SDK

The Python SDK is the recommended way to call the API from Python services and scripts. It provides:

-   Sync + async clients
-   Typed request/response models
-   Configurable retries/timeouts and structured errors

See the [**Python SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-python) for installation, full API reference (api.md), and up-to-date examples.

### TypeScript SDK

The TypeScript SDK is the recommended way to call the API from Node.js services and modern TS/JS runtimes. It provides:

-   Fully typed params/responses
-   First-class error handling, retries/timeouts
-   Support across common runtimes where fetch is available or polyfilled

See the [**TypeScript SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-typescript) for installation, full API reference (api.md), and up-to-date examples.