Warp Platform API reference

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. Passing the literal value `empty-environment` matches runs with no environment configured, rather than omitting the parameter, which applies no environment filter at all. `empty-environment` can never collide with a real environment ID: every environment ID is exactly 22 characters drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen and is a different length.
• 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.
• metadata (query): Filter by exact metadata key/value pairs using object notation (e.g. `metadata[ticket_id]=VIS-238`), combining multiple pairs with AND semantics, up to 5 per request. Returns `feature_not_available` when metadata filtering is not enabled.
• artifact_type (query): Filter runs by artifact type
• q (query): Fuzzy search query across run title, prompt, and skill_spec

GET /agent/run-by-external-reference

Find the run that produced a given external reference URL

Reverse-looks up the agent run that created an EXTERNAL_REFERENCE artifact with the given URL. The URL is matched against the canonical locator stored when the artifact was reported via POST /harness-support/report-artifact with artifact_type EXTERNAL_REFERENCE. Returns 404 when no matching run exists or when the caller lacks access, to avoid leaking run existence.

• url (query, required): The canonical URL of the external reference artifact to look up.

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 transitions to a cancelled state. Not all runs can be cancelled: a run already in a terminal state, in PENDING, or of an unsupported type (self-hosted, local, GitHub Action) is rejected instead — see the error responses below for each case.

• 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}`. A run that failed during environment setup keeps its retained session reachable for a bounded debug window. A follow-up sent to an eligible run in that window is delivered into the retained session to start or continue a debug agent, without reopening the run: it stays in its failed state, with its original failure message and error code unchanged. This applies uniformly to every follow-up origin (this endpoint, the Warp client, and integrations) and requires the same authorization as any other follow-up. Once the debug window closes, or when the run is not eligible, a follow-up falls back to the run's ordinary continuation behavior (which may start a new execution).

• 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

GET /agent/conversations/{conversation_id}/transcript

Get conversation transcript

Retrieve the raw conversation transcript for a conversation. Returns a 302 redirect to a time-limited download URL for the transcript. Supported for third-party harness conversations (Claude Code, Codex, Gemini).

• 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: a time-limited signed download URL for downloadable file-like artifacts, or the current plan content inline for plan artifacts. Public artifacts can be read without authentication; private artifacts require the caller to be authenticated and authorized.

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

GET /agent/artifacts/{artifactUid}/download

Download an artifact

Redirect to a temporary signed download URL for a downloadable artifact. Public artifacts can be downloaded without authentication; private artifacts require the caller to be authenticated and authorized.

• 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.

• ()

POST /agent/runs/{runId}/scores

Report evaluation scores for a run

Report one or more evaluation verdicts for a run, called by the judge run dispatched to score it and authenticated with that judge run's API key. Each verdict is processed independently — the response reports per-verdict acceptance, and a rejected verdict does not block the others — so reporting a subset of the run's evaluations is valid.

• runId (path, required): The run being scored

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