Skip to content
Warp

Reference > API & SDK

Oz API & SDK reference

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

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

Oz API

Section titled “Oz API”

The Oz API 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

Oz Agent SDK

Section titled “Oz Agent SDK”

Oz provides official Python and TypeScript SDKs that wrap the Oz API 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).

Oz API

Section titled “Oz API”

REST API Base URL

Section titled “REST API Base URL”

All endpoints are served over HTTPS:

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

Core Concepts

Section titled “Core Concepts”

Agent runs

Section titled “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

Section titled “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.

Key Endpoints

Section titled “Key Endpoints”

The Agents API exposes three 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.

All endpoint semantics, query parameters, and error codes are documented on the Agents API Reference.

Models Reference

Section titled “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
  • AmbientAgentConfig
  • MCPServerConfig
  • Error

Oz Agent SDKs

Section titled “Oz Agent SDKs”

Python SDK

Section titled “Python SDK”

The Python SDK is the recommended way to call the Oz 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

Section titled “TypeScript SDK”

The TypeScript SDK is the recommended way to call the Oz 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.