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

The agent and 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/).

## Use the agent and run endpoints

The agent and 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 the Warp desktop app. With the API you can:

-   Run an agent by submitting a prompt plus optional configuration, such as the model, environment, MCP servers, and base prompt.
-   Monitor execution by listing runs and tracking state transitions over time, from queued through in progress to succeeded or failed.
-   Inspect results and provenance by fetching a run’s full details, including the original prompt, source and 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 [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/runs` 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 the official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk). Both SDKs wrap the Warp Platform API with:

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

Use the SDK for strong typing, standardized error handling, and concurrency patterns. Use raw REST for minimal dependencies or full control over your HTTP client; the SDKs can also call undocumented endpoints when needed.

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

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

The request’s `AmbientAgentConfig` object shapes how an agent runs:

-   `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 set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent, such as 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` - The model to run.
-   `base_prompt` - Instructions that shape the agent’s behavior.
-   `environment_id` - The `CloudEnvironment` to run in.
-   `worker_host` - A [self-hosted worker](https://docs.warp.dev/factories/self-hosting/) to run a standalone cloud agent on.
-   `skill_spec` - A [skill](https://docs.warp.dev/agents/capabilities/skills/) to use as the base prompt, in `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md` form.
-   `mcp_servers` - MCP servers whose tools the agent can use.

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.

#### Skill actions in conversation data

The Conversation API returns skill loads as `read_skill` actions. When `input.bundled_skill_id` is present, it identifies a Warp-provided bundled reference. `input.skill_path` is the path used to resolve a skill, but doesn’t prove ownership: file-based skills and path-referenced bundled skills, including skills from a remote host, can both use this field.

The following stable, user-facing IDs are bundled directly with Warp:

| Bundled skill ID | Purpose |
| --- | --- |
| `add-mcp-server` | Add an MCP server to Warp configuration. |
| `change-keybinding` | Change or remove Warp keyboard shortcuts. |
| `claude-api` | Build and maintain applications that use the Anthropic SDK. |
| `create-skill` | Create, improve, and evaluate skills. |
| `create-tab-config` | Create a Warp tab configuration. |
| `factory-files` | Create and validate file-based Warp factory definitions. |
| `factory-mcp` | Send work to a factory and collaborate through Factory MCP. |
| `modify-settings` | View or change Warp settings using the bundled settings schema. |
| `oz-platform` | Run, configure, and inspect cloud agents through the API and CLI. |
| `pr-comments` | Fetch GitHub pull request review comments for the current branch. |
| `tab-configs` | Look up the tab configuration schema and validation rules. |
| `tui-migrate-setup` | Migrate supported settings into the Warp Agent CLI. |
| `update-tab-config` | Update an existing Warp tab configuration. |
| `warpctrl` | Control and inspect a running Warp app with Warp Control. |

The catalog helps group usage across conversations; it isn’t an availability manifest. Use each run’s advertised skills for availability and its conversation’s `read_skill` actions for invocation. The bundled set can vary by Warp release, release channel, enabled features, required files, and connected integrations.

For example, `oz-platform`, `factory-files`, and `factory-mcp` are Warp-provided. `factory-mcp` appears only where Factory MCP is available, `tui-migrate-setup` is specific to the Warp Agent CLI, and connected integrations can add bundled IDs that aren’t listed here.

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

-   `POST /agent/runs` - Create a new agent run with a prompt and optional config and title. Returns the `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 the 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 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 and async clients
-   Typed request and response models
-   Configurable retries and timeouts, and structured errors

Install the package from PyPI:

```bash
pip install warp-platform-sdk
```

Import `WarpClient` from `warp_platform_sdk`. See the [Python SDK GitHub repo](https://github.com/warpdotdev/oz-sdk-python) for the full API reference and up-to-date examples.

### TypeScript SDK

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

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

Install the package from npm:

```bash
npm install @warp-dot-dev/warp-platform-sdk
```

Import `WarpClient` from `@warp-dot-dev/warp-platform-sdk`. See the [TypeScript SDK GitHub repo](https://github.com/warpdotdev/oz-sdk-typescript) for the full API reference and up-to-date examples.

## Related pages

-   [Factory endpoints](https://docs.warp.dev/factories/factory-api/) - Find a factory and send it work by UID.
-   [Warp Platform API quickstart](https://docs.warp.dev/factories/api-and-sdk/quickstart/) - Create and inspect your first run.
-   [API errors](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/) - Every error code, its HTTP status, and how to resolve it.
-   [Multi-agent orchestration](https://docs.warp.dev/platform/orchestration/) - Coordinate parent and child runs through the same API.