Oz Agent API

API for creating, managing, and querying Oz cloud agent runs. These endpoints allow users to programmatically spawn agents, list runs, and retrieve detailed run information.

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

Authentication: Bearer token (Warp API key). Obtain from account settings. Pass as Authorization: Bearer YOUR_API_KEY.

Full machine-readable spec: openapi.json

GET /agent

List available agents

Retrieve a list of available agents (skills) that can be used to run tasks. Agents are discovered from environments or a specific repository.

  • repo (query): Optional repository specification to list agents from (format: "owner/repo"). If not provided, lists agents from all accessible environments.
  • refresh (query): When true, clears the agent list cache before fetching. Use this to force a refresh of the available agents.
  • sort_by (query): Sort order for the returned agents. - "name": Sort alphabetically by name (default) - "last_run": Sort by most recently used
  • include_malformed_skills (query): When true, includes skills whose SKILL.md file exists but is malformed. These variants will have a non-empty `error` field describing the parse failure. Defaults to false.

GET /agent/runs/{runId}/transcript

Get run transcript

Retrieve the raw conversation transcript for an agent run. Returns a 302 redirect to a time-limited download URL for the transcript.

  • runId (path, required): The unique identifier of the run

POST /agent/run

Run an agent task

Spawn a cloud agent with a prompt and optional configuration. The agent will be queued for execution and assigned a unique run ID.

POST /agent/runs

Run an agent task (preferred)

Alias for POST /agent/run. This is the preferred endpoint for creating new agent runs. Behavior is identical to POST /agent/run.

GET /agent/runs

List agent runs

Retrieve a paginated list of agent runs with optional filtering. Results default to `sort_by=updated_at` and `sort_order=desc`.

  • limit (query): Maximum number of runs to return
  • cursor (query): Pagination cursor from previous response
  • sort_by (query): Sort field for results. - `updated_at`: Sort by last update timestamp (default) - `created_at`: Sort by creation timestamp - `title`: Sort alphabetically by run title - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
  • sort_order (query): Sort direction
  • state (query): Filter by run state. Can be specified multiple times to match any of the given states.
  • name (query): Filter by agent config name
  • model_id (query): Filter by model ID
  • creator (query): Filter by creator UID (user or service account)
  • source (query): Filter by run source type
  • execution_location (query): Filter by where the run executed
  • created_after (query): Filter runs created after this timestamp (RFC3339 format)
  • created_before (query): Filter runs created before this timestamp (RFC3339 format)
  • updated_after (query): Filter runs updated after this timestamp (RFC3339 format)
  • environment_id (query): Filter runs by environment ID
  • skill (query): Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec.
  • skill_spec (query): Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
  • schedule_id (query): Filter runs by the scheduled agent ID that created them
  • ancestor_run_id (query): Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.
  • artifact_type (query): Filter runs by artifact type
  • q (query): Fuzzy search query across run title, prompt, and skill_spec

GET /agent/runs/{runId}

Get run details

Retrieve detailed information about a specific agent run, including the full prompt, session link, and resolved configuration.

  • runId (path, required): The unique identifier of the run

GET /agent/runs/{runId}/conversation

Get normalized run conversation

Retrieve a run's conversation as a normalized sequence of messages and nested steps. The response groups text, tool activity, and event content into structured blocks.

  • runId (path, required): The unique identifier of the run

POST /agent/runs/{runId}/cancel

Cancel a run

Cancel an agent run that is currently queued or in progress. Once cancelled, the run will transition to a cancelled state. Not all runs can be cancelled. Runs that are in a terminal state (SUCCEEDED, FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in PENDING state return 409 (retry after a moment). Self-hosted, local, and GitHub Action runs return 422.

  • runId (path, required): The unique identifier of the run to cancel

GET /agent/conversations/{conversation_id}

Get normalized conversation

Retrieve a conversation directly by conversation ID in Warp's normalized task/message format.

  • conversation_id (path, required): The unique identifier of the conversation

POST /agent/messages

Send a message to one or more runs

Send a point-to-point message to one or more agent runs. Each recipient gets an independent message row with its own delivery state. Requires the OrchestrationV2 feature flag.

GET /agent/messages/{runId}

List inbox message headers

  • runId (path, required)
  • unread (query)
  • since (query)
  • limit (query)

POST /agent/messages/{messageId}/read

Read a message body

Returns the full message body and sets read_at.

  • messageId (path, required)

POST /agent/messages/{messageId}/delivered

Mark a message as delivered

Sets delivered_at if not already set. Idempotent.

  • messageId (path, required)

GET /agent/events

Poll for events

Batch poll for events across multiple watched runs. Returns events ordered by monotonic sequence number. Client advances the cursor (since parameter) on each poll.

  • run_ids (query, required)
  • since (query)
  • limit (query)

POST /agent/events/{runId}

Report a lifecycle event

Client reports a lifecycle event for a run. This is the canonical mechanism for all lifecycle events.

  • runId (path, required)

POST /agent/schedules

Create a scheduled agent

Create a new scheduled agent that runs on a cron schedule. The agent will be triggered automatically based on the cron expression.

GET /agent/schedules

List scheduled agents

Retrieve all scheduled agents accessible to the authenticated user. Results are sorted alphabetically by name.

GET /agent/schedules/{scheduleId}

Get scheduled agent details

Retrieve detailed information about a specific scheduled agent, including its configuration, history, and next scheduled run time.

  • scheduleId (path, required): The unique identifier of the scheduled agent

PUT /agent/schedules/{scheduleId}

Update a scheduled agent

Update an existing scheduled agent's configuration. All fields except agent_config are required.

  • scheduleId (path, required): The unique identifier of the scheduled agent

DELETE /agent/schedules/{scheduleId}

Delete a scheduled agent

Delete a scheduled agent. This will stop all future scheduled runs.

  • scheduleId (path, required): The unique identifier of the scheduled agent

POST /agent/schedules/{scheduleId}/pause

Pause a scheduled agent

Pause a scheduled agent. The agent will not run until resumed.

  • scheduleId (path, required): The unique identifier of the scheduled agent

POST /agent/schedules/{scheduleId}/resume

Resume a scheduled agent

Resume a paused scheduled agent. The agent will start running according to its cron schedule.

  • scheduleId (path, required): The unique identifier of the scheduled agent

GET /agent/environments

List environments

Retrieve cloud environments accessible to the authenticated principal. Returns environments the caller owns, has been granted guest access to, or has accessed via link sharing.

  • sort_by (query): Sort order for the returned environments. - `name`: alphabetical by environment name - `last_updated`: most recently updated first (default)

GET /agent/models

List available models

Retrieve the list of LLM models available to the authenticated user for agent runs. The response includes which model is the default, as well as per-model metadata such as provider, cost, and whether the model is currently disabled (and why).

GET /agent/artifacts/{artifactUid}

Get artifact details

Retrieve an artifact by its UUID. For downloadable file-like artifacts, returns a time-limited signed download URL. For plan artifacts, returns the current plan content inline.

  • artifactUid (path, required): The unique identifier (UUID) of the artifact

POST /agent/identities

Create an agent

Create a new agent for the caller's team. Agents can be used as the execution principal for team-owned runs.

GET /agent/identities

List agents

List all agents for the caller's team. Each agent includes an `available` flag indicating whether it is within the team's plan limit and may be used for runs.

PUT /agent/identities/{uid}

Update an agent

Update an existing agent.

  • uid (path, required): The unique identifier of the agent

DELETE /agent/identities/{uid}

Delete an agent

Delete an agent. All API keys associated with the agent are deleted atomically.

  • uid (path, required): The unique identifier of the agent

GET /agent/sessions/{sessionUuid}/redirect

Get session redirect

Check whether a shared session should redirect to a conversation transcript. Returns a conversation_id if the agent sandbox has finished and conversation data is available, or an empty object if no redirect is needed.

  • sessionUuid (path, required): The UUID of the shared session
Was this helpful? Yes No