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

# Oz API & SDK reference

Create and inspect cloud agent runs over HTTP, or use the Python and TypeScript SDKs for typed requests, retries, and error handling.

The Oz API & SDK lets you create, monitor, and inspect [cloud agent](/platform/) runs from any system that can make HTTP requests — CI pipelines, cron jobs, backend services, and internal tools — without the Warp desktop app. Call the REST API from any HTTP client, or use the official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs for typed requests, built-in retries, and structured error handling.

For every endpoint’s parameters, schemas, and error responses, see the interactive [Agent API reference](/api). To make your first request, start with the [API & SDK quickstart](/reference/api-and-sdk/quickstart/).

With the API you can:

-   **Run agents** - Submit a prompt plus optional configuration: model, environment, MCP servers, and base prompt.
-   **Monitor execution** - List runs and track state transitions (queued → in progress → succeeded or failed).
-   **Inspect results** - Fetch a run’s full details, including the original prompt, creator metadata, session link, and resolved configuration.

To send work to a [Warp factory](/factories/), use the [factory API](/factories/factory-api/) to discover the factory and dispatch by UID instead of calling `POST /agent/run` with a foreman’s `agent_identity_uid`. A dispatched factory run is still an ordinary run, so everything on this page — follow-ups, cancellation, status — applies to it.

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

## REST API

All endpoints are served over HTTPS from this base URL, and authenticated with a [Warp API key](/reference/cli/api-keys/) passed as a bearer token:

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

### Agent runs

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

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

### Agent configuration

Shape how an agent runs with the `AmbientAgentConfig` object. The most commonly set fields:

-   `name` - A label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is set to the skill name automatically; set it explicitly (via the API, SDK, or `--name` on the CLI) to categorize runs by intent, and filter with the `name` query parameter on `GET /agent/runs`.
-   `model_id` - The LLM the run uses.
-   `base_prompt` - Standing instructions that shape the agent’s behavior.
-   `environment_id` - The [cloud environment](/platform/environments/) the run executes in.
-   `skill_spec` - A [skill](/agents/capabilities/skills/) to use as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`).
-   `mcp_servers` - MCP servers that give the run specific tools.

### Key endpoints

-   `POST /agent/run` - Create a run from a prompt and optional config and title. Returns `run_id` and the initial state.
-   `GET /agent/runs` - List runs, with pagination and filters for state, config name, model, creator, source, and creation time.
-   `GET /agent/runs/{runId}` - Fetch one run’s full details, including its session link and resolved configuration.
-   `POST /agent/runs/{runId}/followups` - Send a follow-up message to steer or continue a run — the same capability the Slack and Linear integrations use.
-   `POST /agent/runs/{runId}/cancel` - Cancel a queued or in-progress run.

The [Agent API reference](/api) documents all endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) — including the factory and scorer endpoints and shared models such as `RunAgentRequest`, `RunItem`, `AmbientAgentConfig`, and `Error`.

## SDKs

The SDKs wrap the same API with typed request and response models, configurable retries and timeouts, [consistent error types](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes, and helpers for reading raw responses. Use an SDK when you want strong typing and standardized error handling; use raw REST when you want minimal dependencies or full control over your HTTP client.

-   **[Python SDK](https://github.com/warpdotdev/oz-sdk-python)** - Sync and async clients for Python services and scripts. The repo covers installation, the full API surface (`api.md`), and current examples.
-   **[TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript)** - Fully typed client for Node.js and other runtimes where `fetch` is available. The repo covers installation, the full API surface (`api.md`), and current examples.

## Related pages

-   [Agent API reference](/api) - Interactive reference for every endpoint, parameter, and schema.
-   [Use the factory API](/factories/factory-api/) - Discover a factory and dispatch work to it by UID.
-   [API error reference](/reference/api-and-sdk/troubleshooting/errors/) - Error codes, response format, and resolution steps.
-   [API keys](/reference/cli/api-keys/) - Create and manage the keys that authenticate API requests.
-   [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - A webhook handler that triggers agents from production errors.