Warp Oz 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.

    These endpoints allow users to programmatically spawn agents, list runs, 
    and retrieve detailed run information.
  contact:
    name: Warp Support
    url: 'https://docs.warp.dev'
    email: [email protected]
  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
  - name: schedules
    description: Operations for creating and managing scheduled 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, 
        including the full prompt, session link, and resolved configuration.
      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/schedules:
    post:
      summary: Create a scheduled agent
      description: |
        Create a new scheduled agent that runs on a cron schedule.
        The agent will be triggered automatically based on the cron expression.
      operationId: createScheduledAgent
      tags:
        - schedules
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledAgentRequest'
            examples:
              simple:
                summary: Simple daily schedule
                value:
                  name: Daily Code Review
                  cron_schedule: 0 9 * * *
                  prompt: Review open pull requests and provide feedback
                  enabled: true
              withConfig:
                summary: With agent config
                value:
                  name: Weekly Report
                  cron_schedule: 0 10 * * 1
                  prompt: Generate weekly status report
                  enabled: true
                  agent_config:
                    model_id: claude-4-6-opus-high
      responses:
        '201':
          description: Scheduled agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAgentItem'
        '400':
          description: 'Invalid request (missing required fields, invalid cron expression)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission or feature not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List scheduled agents
      description: |
        Retrieve all scheduled agents accessible to the authenticated user.
        Results are sorted alphabetically by name.
      operationId: listScheduledAgents
      tags:
        - schedules
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of scheduled agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListScheduledAgentsResponse'
        '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/schedules/{scheduleId}':
    get:
      summary: Get scheduled agent details
      description: |
        Retrieve detailed information about a specific scheduled agent,
        including its configuration, history, and next scheduled run time.
      operationId: getScheduledAgent
      tags:
        - schedules
      security:
        - bearerAuth: []
      parameters:
        - name: scheduleId
          in: path
          description: The unique identifier of the scheduled agent
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Scheduled agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAgentItem'
        '400':
          description: Missing schedule 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 schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a scheduled agent
      description: |
        Update an existing scheduled agent's configuration.
        All fields except agent_config are required.
      operationId: updateScheduledAgent
      tags:
        - schedules
      security:
        - bearerAuth: []
      parameters:
        - name: scheduleId
          in: path
          description: The unique identifier of the scheduled agent
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduledAgentRequest'
      responses:
        '200':
          description: Scheduled agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAgentItem'
        '400':
          description: 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 update schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a scheduled agent
      description: |
        Delete a scheduled agent. This will stop all future scheduled runs.
      operationId: deleteScheduledAgent
      tags:
        - schedules
      security:
        - bearerAuth: []
      parameters:
        - name: scheduleId
          in: path
          description: The unique identifier of the scheduled agent
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Scheduled agent deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteScheduledAgentResponse'
        '401':
          description: Authentication requir

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