> 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

Caution

This page is a high-level overview.  
  
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.

## SDKs

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).

Caution

For the full SDK surface area and latest usage, refer to the GitHub repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript).

* * *

## 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.