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/connected-self-hosted-workers

List connected self-hosted workers

Retrieve currently connected self-hosted workers for the authenticated principal's team. Worker presence is derived from worker websocket heartbeats and may be briefly stale.

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 a cloud agent

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

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)
• executor (query): Filter by the user or agent that executed the run. This will often be the same as the creator, but not always: users may delegate tasks to agents.
• 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}/timeline

Get run timeline

Retrieve chronological setup and lifecycle timeline events for an agent run.

• 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

POST /agent/runs/{runId}/followups

Submit a follow-up message for a run

Send a follow-up message to an existing run. The server transparently routes the message based on the current state of the run (still queued, actively running, or ended). A 200 response means the follow-up was accepted; updated run state can be observed via `GET /agent/runs/{runId}`.

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

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/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

GET /harness-support/transcript

Download the raw third-party harness transcript

Redirects to a signed download URL for the raw third-party harness transcript (e.g. `claude_code.json`) of the current task's conversation. Only supported for conversations produced by non-Oz harnesses; Oz conversations 400. This may only be called from within a cloud agent execution environment whose task already has an associated conversation (e.g. on a resumed run).

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.

GET /agent/identities/{uid}

Retrieve an agent

Retrieve a single agent by its unique identifier. The response includes an `available` flag indicating whether the agent is within the team's plan limit and may be used for runs.

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

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