Warp agent API

openapi: 3.0.0
info:
  title: Oz agent API
  version: 1.0.0
  description: "API for creating, managing, and querying Oz cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n"
  contact:
    name: Warp Support
    url: https://docs.warp.dev
    email: support@warp.dev
  license:
    name: Proprietary
servers:
- url: https://app.warp.dev/api/v1
  description: Warp Server
tags:
- name: agent
  description: Operations for running and managing cloud agents
paths:
  /agent:
    get:
      summary: List available agents
      description: 'Retrieve a list of available agents (skills) that can be used to run tasks.

        Agents are discovered from environments or a specific repository.

        '
      operationId: listAgents
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: repo
        in: query
        description: 'Optional repository specification to list agents from (format: "owner/repo").

          If not provided, lists agents from all accessible environments.

          '
        required: false
        schema:
          type: string
      - name: refresh
        in: query
        description: 'When true, clears the agent list cache before fetching.

          Use this to force a refresh of the available agents.

          '
        required: false
        schema:
          type: boolean
          default: false
      - name: sort_by
        in: query
        description: 'Sort order for the returned agents.

          - "name": Sort alphabetically by name (default)

          - "last_run": Sort by most recently used

          '
        required: false
        schema:
          type: string
          enum:
          - name
          - last_run
      - name: include_malformed_skills
        in: query
        description: '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.

          '
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of available agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentsResponse'
        '400':
          description: Invalid repository specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/connected-self-hosted-workers:
    get:
      summary: List connected self-hosted workers
      description: '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.

        '
      operationId: listConnectedSelfHostedWorkers
      tags:
      - agent
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of currently connected self-hosted workers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConnectedSelfHostedWorkersResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not authorized to list connected workers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs/{runId}/transcript:
    get:
      summary: Get run transcript
      description: 'Retrieve the raw conversation transcript for an agent run.

        Returns a 302 redirect to a time-limited download URL for the transcript.

        '
      operationId: getRunTranscript
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The unique identifier of the run
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirect to a download URL for the transcript
          headers:
            Location:
              description: URL to download the transcript
              schema:
                type: string
                format: uri
        '400':
          description: Missing run ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access run transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found or has no transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/run:
    post:
      summary: Run an agent task
      description: 'Spawn a cloud agent with a prompt and optional configuration.

        The agent will be queued for execution and assigned a unique run ID.

        '
      operationId: runAgent
      deprecated: true
      tags:
      - agent
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAgentRequest'
            examples:
              simple:
                summary: Simple prompt
                value:
                  prompt: Fix the bug in auth.go
              withConfig:
                summary: With agent config
                value:
                  prompt: Refactor the database layer
                  config:
                    name: my-agent
                    model_id: gpt-5-4-high
                    base_prompt: Focus on Go backend code
                  title: DB Refactoring Run
      responses:
        '200':
          description: Run created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunAgentResponse'
        '400':
          description: Invalid request (missing prompt, invalid config)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access referenced resources (environment, MCP servers)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs:
    post:
      summary: Run a cloud agent
      description: 'Spawn a cloud agent with a prompt and optional configuration.

        The agent will be queued for execution and assigned a unique run ID.

        '
      operationId: createRun
      tags:
      - agent
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAgentRequest'
      responses:
        '200':
          description: Run created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunAgentResponse'
        '400':
          description: Invalid request (missing prompt, invalid config)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access referenced resources (environment, MCP servers)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List agent runs
      description: 'Retrieve a paginated list of agent runs with optional filtering.

        Results default to `sort_by=updated_at` and `sort_order=desc`.

        '
      operationId: listRuns
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        description: Maximum number of runs to return
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 20
      - name: cursor
        in: query
        description: Pagination cursor from previous response
        required: false
        schema:
          type: string
      - name: sort_by
        in: query
        description: '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.

          '
        required: false
        schema:
          type: string
          enum:
          - updated_at
          - created_at
          - title
          - agent
          default: updated_at
      - name: sort_order
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: state
        in: query
        description: 'Filter by run state. Can be specified multiple times to match any of the given states.

          '
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/RunState'
        style: form
        explode: true
      - name: name
        in: query
        description: Filter by agent config name
        required: false
        schema:
          type: string
      - name: model_id
        in: query
        description: Filter by model ID
        required: false
        schema:
          type: string
      - name: creator
        in: query
        description: Filter by creator UID (user or service account)
        required: false
        schema:
          type: string
      - name: executor
        in: query
        description: '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.

          '
        required: false
        schema:
          type: string
      - name: source
        in: query
        description: Filter by run source type
        required: false
        schema:
          $ref: '#/components/schemas/RunSourceType'
      - name: execution_location
        in: query
        description: Filter by where the run executed
        required: false
        schema:
          $ref: '#/components/schemas/RunExecutionLocation'
      - name: created_after
        in: query
        description: Filter runs created after this timestamp (RFC3339 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: created_before
        in: query
        description: Filter runs created before this timestamp (RFC3339 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_after
        in: query
        description: Filter runs updated after this timestamp (RFC3339 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: environment_id
        in: query
        description: Filter runs by environment ID
        required: false
        schema:
          type: string
      - name: skill
        in: query
        description: 'Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md").

          Alias for skill_spec.

          '
        required: false
        schema:
          type: string
      - name: skill_spec
        in: query
        description: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
        required: false
        schema:
          type: string
      - name: schedule_id
        in: query
        description: Filter runs by the scheduled agent ID that created them
        required: false
        schema:
          type: string
      - name: ancestor_run_id
        in: query
        description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.
        required: false
        schema:
          type: string
      - name: artifact_type
        in: query
        description: Filter runs by artifact type
        required: false
        schema:
          type: string
          enum:
          - PLAN
          - PULL_REQUEST
          - SCREENSHOT
          - FILE
      - name: q
        in: query
        description: Fuzzy search query across run title, prompt, and skill_spec
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunsResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs/{runId}:
    get:
      summary: Get run details
      description: "Retrieve detailed information about a specific agent run, \nincluding the full prompt, session link, and resolved configuration.\n"
      operationId: getRun
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The unique identifier of the run
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunItem'
        '400':
          description: Missing run ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs/{runId}/timeline:
    get:
      summary: Get run timeline
      description: 'Retrieve chronological setup and lifecycle timeline events for an agent run.

        '
      operationId: getRunTimeline
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The unique identifier of the run
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run timeline events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRunTimelineResponse'
        '400':
          description: Missing run ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs/{runId}/conversation:
    get:
      summary: Get normalized run conversation
      description: '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.

        '
      operationId: getRunConversation
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The unique identifier of the run
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Normalized conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '400':
          description: Missing run ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found, or the run has no conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Conversation format is not yet supported by the normalized endpoint

            (error_code: operation_not_supported)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs/{runId}/cancel:
    post:
      summary: Cancel a run
      description: '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.

        '
      operationId: cancelRun
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The unique identifier of the run to cancel
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run cancelled successfully
          content:
            application/json:
              schema:
                type: string
                description: The ID of the cancelled run
        '400':
          description: 'Missing run ID, or the run is already in a terminal state

            (error_code: invalid_request)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to cancel run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Run is in PENDING state and cannot be cancelled yet.

            Retry after a moment (error_code: conflict, retryable: true).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Run cannot be cancelled because the operation is not supported

            for this run type (e.g., self-hosted, local, or GitHub Action runs)

            (error_code: operation_not_supported)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/runs/{runId}/followups:
    post:
      summary: Submit a follow-up message for a run
      description: '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}`.

        '
      operationId: submitRunFollowup
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The unique identifier of the run
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunFollowupRequest'
      responses:
        '200':
          description: Follow-up accepted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: 'Invalid request (e.g. no active sandbox without conversation ID,

            malformed payload). Empty messages are accepted when continuing a

            run from saved conversation context; otherwise they are rejected.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to submit follow-ups for this run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/conversations/{conversation_id}:
    get:
      summary: Get normalized conversation
      description: 'Retrieve a conversation directly by conversation ID in Warp''s

        normalized task/message format.

        '
      operationId: getConversation
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: conversation_id
        in: path
        description: The unique identifier of the conversation
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Normalized conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '400':
          description: Missing conversation ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Conversation format is not yet supported by the normalized endpoint

            (error_code: operation_not_supported)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/environments:
    get:
      summary: List environments
      description: '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.

        '
      operationId: listEnvironments
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: sort_by
        in: query
        required: false
        description: 'Sort order for the returned environments.

          - `name`: alphabetical by environment name

          - `last_updated`: most recently updated first (default)

          '
        schema:
          type: string
          enum:
          - name
          - last_updated
          default: last_updated
      responses:
        '200':
          description: List of accessible environments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnvironmentsResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/models:
    get:
      summary: List available models
      description: '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).

        '
      operationId: listModels
      tags:
      - agent
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of available models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/artifacts/{artifactUid}:
    get:
      summary: Get artifact details
      description: '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.

        '
      operationId: getArtifact
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: artifactUid
        in: path
        description: The unique identifier (UUID) of the artifact
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Artifact details with download information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactResponse'
        '400':
          description: Missing artifact UID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access artifact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Artifact not found or unsupported artifact type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/identities:
    post:
      summary: Create an agent
      description: 'Create a new agent for the caller''s team.

        Agents can be used as the execution principal for team-owned runs.

        '
      operationId: createAgent
      tags:
      - agent
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Invalid request (empty name, user on multiple teams, or on no team)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Only human users can manage agents, or plan limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List agents
      description: '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.

        '
      operationId: listAgents
      tags:
      - agent
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentIdentitiesResponse'
        '400':
          description: User on multiple teams, or on no team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Only human users can list agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/identities/{uid}:
    get:
      summary: Retrieve an agent
      description: '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.

        '
      operationId: getAgent
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: uid
        in: path
        description: The unique identifier of the agent
        required: true
        schema:
          type: string
      responses:
        '200':
    

# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/warp/refs/heads/main/openapi/warp-agent-api-openapi.yml