Oz API & SDK reference

The Oz API & SDK lets you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations.

Note

Some examples in this reference and the CLI reference use oz commands (for example, oz environment list) from the Oz CLI. Those commands remain supported through the end of September 2026. The Warp Agent CLI reference does not yet document a warp equivalent.

API overview

The Oz API & SDK lets you create and inspect Cloud Agent runs over HTTP from any system (CI, cron, backend services, 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 full API endpoint details, refer to the Agents API Reference. For schema definitions, see the SDK repos: Python SDK and TypeScript SDK.

To send work to a Warp factory, use the factory API to discover it and dispatch by UID instead of calling POST /agent/run with a foreman’s agent_identity_uid. Everything on this page - follow-ups, cancellation, status - still applies once a factory run is dispatched.

SDK overview

Warp provides official Python and TypeScript SDKs that wrap the Oz API & SDK with:

• Typed requests and responses (editor autocomplete, fewer schema mistakes)
• Built-in retries and timeouts (with per-request overrides)
• Consistent error types 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.

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 and TypeScript SDK.

---

API reference

REST API base URL

All endpoints are served over HTTPS:

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

Core concepts

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 Agents API Reference 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, 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
• skill_spec to use a skill 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 or TypeScript SDK 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.

---

Key endpoints

The Agents API exposes these primary endpoints:

• 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 are documented on the Agents API Reference.

---

Models reference

The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos (Python, 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 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 for installation, full API reference (api.md), and up-to-date examples.