Oz API & SDK reference

The Oz API & SDK lets you create, monitor, and inspect cloud agent 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 and 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. To make your first request, start with the API & 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, use the 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.

REST API

All endpoints are served over HTTPS from this base URL, and authenticated with a Warp API key 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, 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 the run executes in.
• skill_spec - A skill 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 documents all endpoint semantics, query parameters, and error codes — 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 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 - Sync and async clients for Python services and scripts. The repo covers installation, the full API surface (api.md), and current examples.
• TypeScript SDK - 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 - Interactive reference for every endpoint, parameter, and schema.
• Use the factory API - Discover a factory and dispatch work to it by UID.
• API error reference - Error codes, response format, and resolution steps.
• API keys - Create and manage the keys that authenticate API requests.
• Demo: Sentry monitoring with SDK - A webhook handler that triggers agents from production errors.