Warp agent API
Operations for running and managing cloud agents
Warp agent API is one of 5 APIs that Warp publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 3 JSON Schema definitions.
Tagged areas include agent. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and 3 JSON Schemas.
This API exposes 20 operations across 16 paths, and defines 79 schemas. It is described by OpenAPI 3.0.0, at version 1.0.0.
Requests are made against a single base URL, https://app.warp.dev/api/v1.
20 operations
16 paths
79 schemas
1 DELETE13 GET5 POST1 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
Warp agent API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (bearerAuth).
bearerAuth— Authentication via a Warp API key.
Paths & Operations 20
Across 16 paths, the API surfaces 20 operations — 1 DELETE, 13 GET, 5 POST, 1 PUT. Each is listed below with its method, path, parameters, and response codes.
agent 20
Operations for running and managing cloud agents
GET
/agent
List available agents
GET
/agent/connected-self-hosted-workers
List connected self-hosted workers
GET
/agent/runs/{runId}/transcript
Get run transcript
POST
/agent/rundeprecated
Run an agent task
POST
/agent/runs
Run a cloud agent
GET
/agent/runs
List agent runs
GET
/agent/runs/{runId}
Get run details
GET
/agent/runs/{runId}/timeline
Get run timeline
GET
/agent/runs/{runId}/conversation
Get normalized run conversation
POST
/agent/runs/{runId}/cancel
Cancel a run
POST
/agent/runs/{runId}/followups
Submit a follow-up message for a run
GET
/agent/conversations/{conversation_id}
Get normalized conversation
GET
/agent/environments
List environments
GET
/agent/models
List available models
GET
/agent/artifacts/{artifactUid}
Get artifact details
POST
/agent/identities
Create an agent
GET
/agent/identities
List agents
GET
/agent/identities/{uid}
Retrieve an agent
PUT
/agent/identities/{uid}
Update an agent
DELETE
/agent/identities/{uid}
Delete an agent
Schemas 79
The contract defines 79 schemas that model the data the API accepts and returns. The most detailed are RunItem (26 properties), AgentResponse (15 properties), AmbientAgentConfig (15 properties), UpdateAgentRequest (11 properties). Each schema is shown below with its type and property counts.
ListAgentsResponse
object
1 property
1 required
ScreenshotArtifact
object
3 properties
3 required
FileArtifactResponse
object
Response for retrieving a file artifact.
4 properties
4 required
AgentListEnvironment
object
2 properties
2 required
AttachmentInput
object
A base64-encoded file attachment to include with the prompt
3 properties
3 required
CloudEnvironmentConfig
object
Configuration for a cloud environment used by scheduled agents
6 properties
PlanArtifactResponseData
object
Response data for a plan artifact, including current markdown content.
6 properties
4 required
PlanArtifact
object
3 properties
3 required
EventContentBlock
object
4 properties
3 required
PlanArtifactResponse
object
Response for retrieving a plan artifact.
4 properties
4 required
RunAgentResponse
object
4 properties
3 required
UpdateAgentRequest
object
Partial update for an agent. Each field is optional: Omitted or null: leave the field unchanged. Empty value: clear the field. Non-empty: replace the field who…
11 properties
FileArtifactData
object
6 properties
4 required
AgentListItem
object
2 properties
2 required
PullRequestArtifactData
object
2 properties
2 required
ConversationMessage
object
5 properties
2 required
Harness
object
Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness.
1 property
EnvironmentLastTask
object
Summary of the most recently created task for an environment
6 properties
5 required
ConnectedSelfHostedWorker
object
4 properties
4 required
Scope
object
Ownership scope for a resource (team or personal)
2 properties
1 required
AIRunTimelineEvent
object
A setup or lifecycle event recorded for an agent run.
6 properties
4 required
ArtifactResponse
ListAgentIdentitiesResponse
object
1 property
1 required
ProvidersConfig
object
Optional cloud provider configurations for automatic auth
2 properties
RunSourceType
string
Source that created the run: - LINEAR: Created from Linear integration - API: Created via the Warp API - SLACK: Created from Slack integration - LOCAL: Created…
RunStatusMessage
object
Status message for a run. For terminal error states, includes structured error code and retryability info from the platform error catalog.
3 properties
1 required
GcpProviderConfig
object
GCP Workload Identity Federation settings
4 properties
3 required
ConversationResponse
object
2 properties
2 required
GetRunTimelineResponse
object
Response body for listing run timeline events.
1 property
1 required
ConversationStep
object
7 properties
3 required
CreateAgentRequest
object
11 properties
1 required
ScreenshotArtifactData
object
3 properties
2 required
PullRequestArtifact
object
3 properties
3 required
RunItem
object
26 properties
7 required
RunFollowupRequest
object
Request body for submitting a follow-up message to an existing run.
2 properties
SecretRef
object
Reference to a managed secret by name.
1 property
1 required
ListEnvironmentsResponse
object
1 property
1 required
FileArtifactResponseData
object
Response data for a file artifact, including a signed download URL.
7 properties
5 required
ScreenshotArtifactResponseData
object
Response data for a screenshot artifact, including a signed download URL.
4 properties
3 required
InferenceProvidersConfig
object
Inference provider settings used for LLM calls.
1 property
SessionSharingConfig
object
Configures sharing behavior for the run's shared session. When set, the worker emits --share public: and the bundled Warp client applies an anyone-with-link AC…
1 property
AgentResponse
object
15 properties
8 required
AgentSkill
object
Information about the agent skill used for the run. Either fullpath or bundledskillid will be set, but not both.
4 properties
ListRunsResponse
object
2 properties
2 required
ActionState
string
State of an action result
ActionContentBlock
object
6 properties
5 required
RunCreatorInfo
object
5 properties
AgentListVariant
object
7 properties
5 required
AwsProviderConfig
object
AWS IAM role assumption settings
1 property
1 required
ListConnectedSelfHostedWorkersResponse
object
1 property
1 required
FileArtifact
object
3 properties
3 required
ScheduleInfo
object
Information about the schedule that triggered this run (only present for scheduled runs)
3 properties
3 required
RunExecutionLocation
string
Where the run executed: - LOCAL: Executed in the user's local Oz environment - REMOTE: Executed by a remote/cloud worker
PlatformErrorCode
string
Machine-readable error code identifying the problem type. Used in the type URI of Error responses and in the errorcode field of RunStatusMessage. User errors (…
RunState
string
Current state of the run: - QUEUED: Run is waiting to be picked up - PENDING: Run is being prepared - CLAIMED: Run has been claimed by a worker - INPROGRESS: R…
AIRunTimelineEventType
string
Type of timeline event recorded for a run.
AwsInferenceProviderConfig
object
Configures AWS Bedrock as the LLM inference provider for this agent or run.
3 properties
MCPServerConfig
object
Configuration for an MCP server. Must have exactly one of: warpid, command, or url.
6 properties
ArtifactItem
ModelInfo
object
7 properties
4 required
ActionResultContentBlock
object
7 properties
6 required
TextContentBlock
object
3 properties
2 required
PlanArtifactData
object
5 properties
1 required
MemoryStoreRef
object
Reference to a memory store to attach to an agent.
3 properties
3 required
CloudEnvironment
object
A cloud environment for running agents
9 properties
4 required
ConversationMessageRole
string
Role of the normalized message
ScreenshotArtifactResponse
object
Response for retrieving a screenshot artifact.
4 properties
4 required
AmbientAgentConfig
object
Configuration for a cloud agent run
15 properties
PageInfo
object
2 properties
1 required
ListModelsResponse
object
2 properties
2 required
GitHubRepo
object
2 properties
2 required
RunAgentRequest
object
Request body for creating a new agent run. Either prompt or skill (via skill field, config.skillspec, or config.skills) is required, except for handoff request…
11 properties
RequestUsage
object
Resource usage information for the run
3 properties
AgentRunMode
string
Query mode for an agent run. - normal: Standard user query (default). - plan: Planning Mode. The agent researches and creates a plan, then waits for approval b…
ConversationContentBlock
ActionCategory
string
High-level category of an action performed during the conversation
AgentListSource
object
4 properties
3 required
HarnessAuthSecrets
object
Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
2 properties
Error
object
Error response following RFC 7807 (Problem Details for HTTP APIs). Includes backward-compatible extension members. The response uses the application/problem+js…
8 properties
4 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Warp 4
Other APIs Warp publishes across the network.
Warp Enterprise Analytics API
Warp Oz CLI
Warp harness-support API
Warp schedules API
#agent