openapi: 3.0.0
info:
  title: Warp Agent API
  version: 1.0.0
  description: "API for creating, managing, and querying Warp 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
- 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:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      - 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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      - 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. 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.
        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: metadata
        in: query
        description: |
          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.
        required: false
        schema:
          type: object
          maxProperties: 5
          additionalProperties:
            type: string
        style: deepObject
        explode: true
      - name: artifact_type
        in: query
        description: Filter runs by artifact type
        required: false
        schema:
          type: string
          enum:
          - PLAN
          - PULL_REQUEST
          - SCREENSHOT
          - FILE
          - EXTERNAL_REFERENCE
      - 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'
        '403':
          description: Metadata filtering is not enabled for this environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/run-by-external-reference:
    get:
      summary: Find the run that produced a given external reference URL
      description: |
        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.
      operationId: getRunByExternalReferenceURL
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: url
        in: query
        required: true
        description: The canonical URL of the external reference artifact to look up.
        schema:
          type: string
          maxLength: 2048
      responses:
        '200':
          description: Run found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunByExternalReferenceResponse'
        '400':
          description: url query parameter is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No run found with the given external reference URL, or caller lacks access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          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 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.
      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}`.

        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).
      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/conversations/{conversation_id}/transcript:
    get:
      summary: Get conversation transcript
      description: |
        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).
      operationId: getConversationTranscript
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: conversation_id
        in: path
        description: The unique identifier of the conversation
        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: Conversation format does not support raw transcript download
          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 transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation 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/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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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 required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to delete schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/schedules/{scheduleId}/pause:
    post:
      summary: Pause a scheduled agent
      description: |
        Pause a scheduled agent. The agent will not run until resumed.
      operationId: pauseScheduledAgent
      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 paused successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAgentItem'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to pause schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agent/schedules/{scheduleId}/resume:
    post:
      summary: Resume a scheduled agent
      description: |
        Resume a paused scheduled agent. The agent will start running
        according to its cron schedule.
      operationId: resumeScheduledAgent
      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 resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAgentItem'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to resume schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          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:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      - 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: 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.
      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 for private artifacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access private 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/artifacts/{artifactUid}/download:
    get:
      summary: Download an artifact
      description: |
        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.
      operationId: downloadArtifact
      tags:
      - agent
      security:
      - bearerAuth: []
      - {}
      parameters:
      - name: artifactUid
        in: path
        description: The unique identifier (UUID) of the artifact
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirect to a temporary signed artifact download URL
          headers:
            Location:
              description: Temporary signed download URL
              schema:
                type: string
                format: uri
            Cache-Control:
              description: Cache directive for the redirect response
              schema:
                type: string
            X-Content-Type-Options:
              description: Browser content sniffing protection
              schema:
                type: string
        '400':
          description: Missing artifact UID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required for private artifacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No permission to access private 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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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: []
      parameters:
      - $ref: '#/components/parameters/TeamUidHeaderParam'
      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/runs/{runId}/scores:
    post:
      summary: Report evaluation scores for a run
      description: |
        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.
      operationId: reportRunScores
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: runId
        in: path
        description: The run being scored
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRunScoresRequest'
      responses:
        '200':
          description: Every reported verdict was accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRunScoresResponse'
        '206':
          description: The request was well-formed but at least one verdict was rejected; inspect each result's status and error before deciding whether to resubmit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRunScoresResponse'
        '400':
          description: Malformed request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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/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':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update an agent
      description: |
        Update an existing agent.
      operationId: updateAgent
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: uid
        in: path
        description: The unique identifier of the agent
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Missing or invalid request body
          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'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete an agent
      description: |
        Delete an agent. All API keys associated with the
        agent are deleted atomically.
      operationId: deleteAgent
      tags:
      - agent
      security:
      - bearerAuth: []
      parameters:
      - name: uid
        in: path
        description: The unique identifier of the agent
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Agent deleted successfully
        '400':
          description: Cannot delete the default agent
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Authentication via a Warp API key.
  parameters:
    TeamUidHeaderParam:
      name: X-Warp-Team-Uid
      in: header
      required: false
      description: |
        UID of the team to use as the request's active team. Ignored for
        service-account callers, which always act as their bound team.
      schema:
        type: string
  responses: {}
  schemas:
    RunAgentRequest:
      type: object
      description: |
        Request body for creating a new agent run.
        Either prompt or skill (via skill field, config.skill_spec, or config.skills) is required,
        except for handoff requests that set conversation_id.
      properties:
        prompt:
          type: string
          description: |
            The prompt/instruction for the agent to execute.
            Required unless a skill is specified via the skill field, config.skill_spec, or config.skills.
            Handoff requests may omit prompt when conversation_id is set.
        mode:
          $ref: '#/components/schemas/AgentRunMode'
          description: |
            Optional query mode for the run. Defaults to `normal` when omitted.
            The server does not infer mode from prompt prefixes such as `/plan`,
            so callers should pass this field explicitly to request non-normal behavior.
        skill:
          type: string
          description: |
            Skill specification to use as the base prompt for the agent.
            Supported formats:
              - "repo:skill_name" - Simple name in specific repo
              - "repo:skill_path" - Full path in specific repo
              - "org/repo:skill_name" - Simple name with org and repo
              - "org/repo:skill_path" - Full path with org and repo
            When provided, this takes precedence over config.skill_spec.
        config:
          $ref: '#/components/schemas/AmbientAgentConfig'
        title:
          type: string
          description: Custom title for the run (auto-generated if not provided)
        team:
          type: boolean
          description: |
            Whether to create a team-owned run.
            Defaults to true for users on a single team.
        agent_identity_uid:
          type: string
          description: |
            Optional agent identity UID to use as the execution principal for the run.
            This is only valid for runs that are team owned.
        on_behalf_of:
          type: string
          description: |
            Optional email address or user ID of a Warp user to attribute
            the run to; when set, the resolved user becomes the run's
            creator instead of the caller. Only agent API keys may use this
            field, only when the calling agent has on_behalf_of enabled in
            its configuration (a team admin must turn this on per agent),
            and only for team-owned runs. The target user must be an active
            member of the run's owner team.
        conversation_id:
          type: string
          description: |
            Optional conversation ID to continue an existing conversation.
            If provided, the agent will continue from where the previous run left off.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentInput'
          description: |
            Optional file attachments to include with the prompt (max 5).
            Attachments are uploaded to cloud storage and made available to the agent.
        parent_run_id:
          type: string
          description: |
            Optional run ID of the parent that spawned this run, used for
            orchestration hierarchies; the parent run must exist and be
            visible to the caller, or the request is rejected with a 400.
            Child runs are also subject to the server's maximum
            orchestration depth, and requests that would exceed it are
            rejected with a 400.
        interactive:
          type: boolean
          description: |
            Whether the run should be interactive.
            If not set, defaults to false.
        metadata:
          $ref: '#/components/schemas/RunMetadata'
    RunMetadata:
      type: object
      additionalProperties:
        type: string
      description: |
        Custom key/value metadata attached to a run at creation time and
        immutable afterward; at most 20 keys, with keys 1-64 bytes matching
        [a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with
        no NUL characters. Requests with invalid metadata are rejected. A
        run's effective metadata is merged per key at creation: explicit
        request keys override keys inherited from the parent run, which
        override automatic keys (ticket_id and ticket_source on Linear- and
        Jira-triggered runs).
    RunAgentResponse:
      type: object
      required:
      - run_id
      - task_id
      - state
      properties:
        run_id:
          type: string
          description: Unique identifier for the created run
        task_id:
          type: string
          deprecated: true
          description: Unique identifier for the task (same as run_id). Deprecated - use run_id instead.
        state:
          $ref: '#/components/schemas/RunState'
        at_capacity:
          type: boolean
          description: Whether the system is at capacity when the run was created
    AgentRunMode:
      type: string
      description: |
        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 before execution.
          - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
      enum:
      - normal
      - plan
      - orchestrate
      default: normal
    ListRunsResponse:
      type: object
      required:
      - runs
      - page_info
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/RunItem'
        page_info:
          $ref: '#/components/schemas/PageInfo'
    RunItem:
      type: object
      required:
      - run_id
      - task_id
      - title
      - state
      - prompt
      - created_at
      - updated_at
      properties:
        run_id:
          type: string
          description: Unique identifier for the run
        task_id:
          type: string
          deprecated: true
          description: Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead.
        title:
          type: string
          description: Human-readable title for the run
        state:
          $ref: '#/components/schemas/RunState'
        execution_location:
          $ref: '#/components/schemas/RunExecutionLocation'
        prompt:
          type: string
          description: The prompt/instruction for the agent
        created_at:
          type: string
          format: date-time
          description: Timestamp when the run was created (RFC3339)
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the run was last updated (RFC3339)
        run_time:
          type: string
          format: duration
          description: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions.
        started_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the agent started working on the run (RFC3339)
        status_message:
          $ref: '#/components/schemas/RunStatusMessage'
        source:
          $ref: '#/components/schemas/RunSourceType'
        schedule:
          $ref: '#/components/schemas/ScheduleInfo'
        session_id:
          type: string
          description: UUID of the shared session (if available)
        session_link:
          type: string
          format: uri
          description: URL to view the agent session
        trigger_url:
          type: string
          format: uri
          description: URL to the run trigger (e.g. Slack thread, Linear issue, schedule)
        creator:
          $ref: '#/components/schemas/RunCreatorInfo'
        executor:
          $ref: '#/components/schemas/RunCreatorInfo'
        request_usage:
          $ref: '#/components/schemas/RequestUsage'
        agent_config:
          $ref: '#/components/schemas/AmbientAgentConfig'
        conversation_id:
          type: string
          description: UUID of the conversation associated with the run
        parent_run_id:
          type: string
          description: UUID of the parent run that spawned this run
        metadata:
          $ref: '#/components/schemas/RunMetadata'
        is_sandbox_running:
          type: boolean
          description: Whether the sandbox environment is currently running
        is_run_type_cancellable:
          type: boolean
          description: |
            Whether the run's type is eligible for cancellation via the API. State-independent:
            false for GitHub Action and local runs; true for all other run types (including
            self-hosted). Clients should still gate the control on the run's current state.
        debug_agent_available:
          type: boolean
          description: |
            Whether a debug agent can currently be started inside this run's retained
            setup-failure session. Only true for a run that failed during environment setup,
            whose retained execution is still reachable, and whose debug window has not
            closed. See `POST /agent/runs/{runId}/followups`.
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactItem'
          description: Artifacts created during the run (plans, pull requests, etc.)
        agent_skill:
          $ref: '#/components/schemas/AgentSkill'
        scope:
          $ref: '#/components/schemas/Scope'
    GetRunTimelineResponse:
      type: object
      description: Response body for listing run timeline events.
      required:
      - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/AIRunTimelineEvent'
    AIRunTimelineEvent:
      type: object
      description: A setup or lifecycle event recorded for an agent run.
      required:
      - event_uuid
      - run_id
      - event_type
      - occurred_at
      properties:
        event_uuid:
          type: string
          description: Unique client- or server-generated identifier for this event.
        run_id:
          type: string
          description: Run that owns this event.
        execution_id:
          type: integer
          format: int64
          description: Run execution associated with this event, when available.
        event_type:
          $ref: '#/components/schemas/AIRunTimelineEventType'
        occurred_at:
          type: string
          format: date-time
          description: Timestamp when the event occurred.
        payload:
          type: object
          additionalProperties: true
          description: Optional event-specific JSON payload. Contents vary by event type.
    AIRunTimelineEventType:
      type: string
      description: Type of timeline event recorded for a run.
      enum:
      - oz_run_created
      - oz_run_claimed
      - worker_container_ready
      - shared_session_started
      - agent_started
      - oz_run_done
      - oz_run_blocked
      - oz_run_cancelled
      - oz_run_failed
      - oz_run_errored
      - vm_shutdown
    ConversationResponse:
      type: object
      required:
      - conversation_id
      - steps
      properties:
        conversation_id:
          type: string
          description: Unique identifier for the conversation
        steps:
          type: array
          description: Root steps in the conversation
          items:
            $ref: '#/components/schemas/ConversationStep'
    ConversationStep:
      type: object
      required:
      - id
      - messages
      - steps
      properties:
        id:
          type: string
          description: Unique identifier for the step
        description:
          type: string
          description: Original instruction or delegated work description for the step
        summary:
          type: string
          description: Summary of the work completed for the step
        started_at:
          type: string
          format: date-time
          description: Earliest transcript message timestamp contained in this step or any nested step (RFC3339)
        completed_at:
          type: string
          format: date-time
          description: Latest transcript message timestamp contained in this step or any nested step (RFC3339)
        messages:
          type: array
          description: Ordered normalized messages for this step
          items:
            $ref: '#/components/schemas/ConversationMessage'
        steps:
          type: array
          description: Nested delegated work performed as part of this step
          items:
            $ref: '#/components/schemas/ConversationStep'
    ConversationMessage:
      type: object
      required:
      - role
      - content
      properties:
        message_ids:
          type: array
          description: Underlying transcript message IDs grouped into this normalized message
          items:
            type: string
        request_id:
          type: string
          description: Request identifier shared by transcript messages from the same request, when available
        role:
          $ref: '#/components/schemas/ConversationMessageRole'
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the first transcript message included in this normalized message (RFC3339)
        content:
          type: array
          items:
            $ref: '#/components/schemas/ConversationContentBlock'
    ConversationMessageRole:
      type: string
      description: Role of the normalized message
      enum:
      - user
      - assistant
      - tool
      - system
    ConversationContentBlock:
      oneOf:
      - $ref: '#/components/schemas/TextContentBlock'
      - $ref: '#/components/schemas/ActionContentBlock'
      - $ref: '#/components/schemas/ActionResultContentBlock'
      - $ref: '#/components/schemas/EventContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContentBlock'
          action: '#/components/schemas/ActionContentBlock'
          action_result: '#/components/schemas/ActionResultContentBlock'
          event: '#/components/schemas/EventContentBlock'
    TextContentBlock:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - text
        message_id:
          type: string
          description: Underlying transcript message ID that produced this content block, when available
        text:
          type: string
          description: Plain text content
    ActionCategory:
      type: string
      description: High-level category of an action performed during the conversation
      enum:
      - command
      - files
      - search
      - integration
      - documents
      - computer
      - review
      - skill
    ActionState:
      type: string
      description: State of an action result
      enum:
      - running
      - completed
      - failed
      - denied
    ActionContentBlock:
      type: object
      required:
      - type
      - id
      - category
      - name
      - input
      properties:
        type:
          type: string
          enum:
          - action
        message_id:
          type: string
          description: Underlying transcript message ID that produced this content block, when available
        id:
          type: string
          description: Unique identifier for the action
        category:
          $ref: '#/components/schemas/ActionCategory'
        name:
          type: string
          description: Public action name, such as run_command or edit_files
        input:
          type: object
          additionalProperties: true
          description: Curated public input for this action. This object is owned by the API and is not a raw internal tool payload.
    ActionResultContentBlock:
      type: object
      required:
      - type
      - action_id
      - category
      - name
      - state
      - output
      properties:
        type:
          type: string
          enum:
          - action_result
        message_id:
          type: string
          description: Underlying transcript message ID that produced this content block, when available
        action_id:
          type: string
          description: Identifier of the corresponding action
        category:
          $ref: '#/components/schemas/ActionCategory'
        name:
          type: string
          description: Public action name matching the corresponding action block
        state:
          $ref: '#/components/schemas/ActionState'
        output:
          type: object
          additionalProperties: true
          description: Curated public result for this action. Large or binary internal payloads should be summarized rather than passed through raw.
    EventContentBlock:
      type: object
      required:
      - type
      - name
      - data
      properties:
        type:
          type: string
          enum:
          - event
        message_id:
          type: string
          description: Underlying transcript message ID that produced this content block, when available
        name:
          type: string
          description: Event type for intentionally exposed non-core transcript events
        data:
          type: object
          additionalProperties: true
          description: Minimal structured metadata for the event
    ArtifactItem:
      oneOf:
      - $ref: '#/components/schemas/PlanArtifact'
      - $ref: '#/components/schemas/PullRequestArtifact'
      - $ref: '#/components/schemas/ScreenshotArtifact'
      - $ref: '#/components/schemas/FileArtifact'
      - $ref: '#/components/schemas/ExternalReferenceArtifact'
      discriminator:
        propertyName: artifact_type
        mapping:
          PLAN: '#/components/schemas/PlanArtifact'
          PULL_REQUEST: '#/components/schemas/PullRequestArtifact'
          SCREENSHOT: '#/components/schemas/ScreenshotArtifact'
          FILE: '#/components/schemas/FileArtifact'
          EXTERNAL_REFERENCE: '#/components/schemas/ExternalReferenceArtifact'
    ExternalReferenceArtifact:
      type: object
      required:
      - artifact_type
      - created_at
      - data
      properties:
        artifact_type:
          type: string
          enum:
          - EXTERNAL_REFERENCE
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/ExternalReferenceArtifactData'
    PlanArtifact:
      type: object
      required:
      - artifact_type
      - created_at
      - data
      properties:
        artifact_type:
          type: string
          enum:
          - PLAN
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/PlanArtifactData'
    PullRequestArtifact:
      type: object
      required:
      - artifact_type
      - created_at
      - data
      properties:
        artifact_type:
          type: string
          enum:
          - PULL_REQUEST
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/PullRequestArtifactData'
    ScreenshotArtifact:
      type: object
      required:
      - artifact_type
      - created_at
      - data
      properties:
        artifact_type:
          type: string
          enum:
          - SCREENSHOT
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/ScreenshotArtifactData'
    FileArtifact:
      type: object
      required:
      - artifact_type
      - created_at
      - data
      properties:
        artifact_type:
          type: string
          enum:
          - FILE
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/FileArtifactData'
    PlanArtifactData:
      type: object
      required:
      - document_uid
      properties:
        artifact_uid:
          type: string
          description: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint
        document_uid:
          type: string
          description: Unique identifier for the plan document
        notebook_uid:
          type: string
          description: Unique identifier for the associated notebook
        url:
          type: string
          format: uri
          description: URL to open the plan in Warp Drive
        title:
          type: string
          description: Title of the plan
    PullRequestArtifactData:
      type: object
      required:
      - url
      - branch
      properties:
        url:
          type: string
          format: uri
          description: URL of the pull request
        branch:
          type: string
          description: Branch name for the pull request
    ScreenshotArtifactData:
      type: object
      required:
      - artifact_uid
      - mime_type
      properties:
        artifact_uid:
          type: string
          description: Unique identifier for the screenshot artifact
        mime_type:
          type: string
          description: MIME type of the screenshot image
        description:
          type: string
          description: Optional description of the screenshot
    FileArtifactData:
      type: object
      required:
      - artifact_uid
      - filepath
      - filename
      - mime_type
      properties:
        artifact_uid:
          type: string
          description: Unique identifier for the file artifact
        filepath:
          type: string
          description: |
            Conversation-relative filepath for the uploaded file. Omitted on
            an anonymous read of a public file artifact.
        filename:
          type: string
          description: Last path component of filepath
        title:
          type: string
          description: |
            Short, badge-visible label for the artifact. For recording artifacts,
            this is the agent-authored title shown in Warp web and blocklist badges.
            Distinct from description, which is longer and shown in detail views.
        description:
          type: string
          description: Optional description of the file
        mime_type:
          type: string
          description: MIME type of the uploaded file
        size_bytes:
          type: integer
          format: int64
          description: Size of the uploaded file in bytes
    ScheduleInfo:
      type: object
      description: Information about the schedule that triggered this run (only present for scheduled runs)
      required:
      - schedule_id
      - schedule_name
      - cron_schedule
      properties:
        schedule_id:
          type: string
          description: Unique identifier for the schedule
        schedule_name:
          type: string
          description: Name of the schedule at the time the run was created
        cron_schedule:
          type: string
          description: Cron expression at the time the run was created
    PageInfo:
      type: object
      required:
      - has_next_page
      properties:
        has_next_page:
          type: boolean
          description: Whether there are more results available
        next_cursor:
          type: string
          description: Opaque cursor for fetching the next page
    RunStatusMessage:
      type: object
      description: |
        Status message for a run. For terminal error states, includes structured
        error code and retryability info from the platform error catalog.
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable status message
        error_code:
          $ref: '#/components/schemas/PlatformErrorCode'
        retryable:
          type: boolean
          description: |
            Whether the error is transient and the client may retry by submitting
            a new run. Only present on terminal error states. When false, retrying
            without addressing the underlying cause will not succeed.
        session_debug_until:
          type: string
          format: date-time
          description: |
            When a failed run's shared session stops being held open for debugging.
            Only present while that window is open.

            The window is an idle window owned by the agent process: activity in the
            session pushes this deadline out. The agent republishes it periodically
            rather than on every keystroke, so the value can lag the true deadline by
            up to a throttle interval, and always in the conservative direction.
        debug_agent_active:
          type: boolean
          description: |
            Whether a setup-failure debug turn is actively pinning the idle timer open
            right now. While true, session_debug_until can lag behind the real deadline;
            clients should show an active-debugging state instead of a countdown.
    RequestUsage:
      type: object
      description: Resource usage information for the run
      properties:
        inference_cost:
          type: number
          format: double
          description: Credits consumed by LLM inference for the run
        compute_cost:
          type: number
          format: double
          description: Credits consumed by compute resources for the run
        platform_cost:
          type: number
          format: double
          description: Credits consumed by platform usage for the run
        inference_cost_usd:
          type: number
          format: double
          description: |
            inference_cost in US dollars, converted at the owning team's
            current credit price. An approximate cost, not a billed amount.
        compute_cost_usd:
          type: number
          format: double
          description: |
            compute_cost in US dollars, converted at the owning team's
            current credit price. An approximate cost, not a billed amount.
        platform_cost_usd:
          type: number
          format: double
          description: |
            platform_cost in US dollars, converted at the owning team's
            current credit price. An approximate cost, not a billed amount.
        total_tokens:
          type: integer
          format: int64
          description: |
            Total LLM token count (summed across every usage category and model) for the run's
            conversation. Omitted when the data is not available.
        inference_cost_breakdown_usd:
          $ref: '#/components/schemas/InferenceCostBreakdownUsd'
        usage_by_category:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ChargedUsageDetail'
          description: |
            Full-granularity token and dollar-cost breakdown for the run's
            conversation, keyed by usage category (for example,
            primary_agent or conversation_compaction) and model id; differs
            from total_tokens/inference_cost_breakdown_usd, which combine
            usage across all categories and models. Omitted when the data
            is not available.
    InferenceCostBreakdownUsd:
      type: object
      description: |
        Charged dollar cost of LLM inference, split by token type.
        Omitted when the data is not available.
      required:
      - input_cost_usd
      - input_cache_read_cost_usd
      - input_cache_write_cost_usd
      - output_cost_usd
      properties:
        input_cost_usd:
          type: number
          format: double
          description: Cost of non-cached input tokens, in US dollars.
        input_cache_read_cost_usd:
          type: number
          format: double
          description: Cost of cache-read input tokens, in US dollars.
        input_cache_write_cost_usd:
          type: number
          format: double
          description: Cost of cache-write input tokens, in US dollars.
        output_cost_usd:
          type: number
          format: double
          description: Cost of output tokens, in US dollars.
    TokenCountBreakdown:
      type: object
      description: A per-token-type token count.
      required:
      - input
      - output
      - input_cache_read
      - input_cache_write
      properties:
        input:
          type: integer
          format: int64
          description: Count of non-cached input tokens.
        output:
          type: integer
          format: int64
          description: Count of output tokens.
        input_cache_read:
          type: integer
          format: int64
          description: Count of cache-read input tokens.
        input_cache_write:
          type: integer
          format: int64
          description: Count of cache-write input tokens.
    InferenceUsageDetail:
      type: object
      description: |
        Full token count and dollar-cost detail inference usage.
        The counts and cost describe the same usage (e.g. token_count.input
        tokens cost cost_usd.input_cost_usd in total).
      required:
      - token_count
      - cost_usd
      - web_search_count
      - web_search_cost_usd
      properties:
        token_count:
          $ref: '#/components/schemas/TokenCountBreakdown'
        cost_usd:
          $ref: '#/components/schemas/InferenceCostBreakdownUsd'
        web_search_count:
          type: integer
          format: int64
          description: Number of web searches performed by this model.
        web_search_cost_usd:
          type: number
          format: double
          description: Total cost of those web searches, in US dollars.
    ChargedUsageDetail:
      type: object
      description: |
        Usage charged for a single usage category, broken down by usage type
        (direct API/BYOK/custom endpoint) and, within each, by model ID.
      required:
      - platform_usage_usd
      properties:
        direct_api_inference_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InferenceUsageDetail'
          description: Inference usage incurred through Warp-provided model access, keyed by model ID.
        byok_inference_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InferenceUsageDetail'
          description: Inference usage charged using a user's own API key, keyed by model ID.
        custom_endpoint_inference_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InferenceUsageDetail'
          description: |
            Inference usage charged using a custom endpoint, keyed by the
            custom model's config key.
        platform_usage_usd:
          type: number
          format: double
          description: Platform usage charged for this category, in US dollars.
    RunCreatorInfo:
      type: object
      properties:
        type:
          type: string
          enum:
          - user
          - service_account
          description: Type of the creator principal
        uid:
          type: string
          description: Unique identifier of the creator
        display_name:
          type: string
          description: Display name of the creator
        email:
          type: string
          description: Email address of the creator
        photo_url:
          type: string
          format: uri
          description: URL to the creator's photo
    RunState:
      type: string
      enum:
      - QUEUED
      - PENDING
      - CLAIMED
      - INPROGRESS
      - SUCCEEDED
      - FAILED
      - BLOCKED
      - ERROR
      - CANCELLED
      description: |
        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: Run is actively being executed
        - SUCCEEDED: Run completed successfully
        - FAILED: Run failed
        - BLOCKED: Run is blocked (e.g., awaiting user input or approval)
        - ERROR: Run encountered an error
        - CANCELLED: Run was cancelled by user
    RunSourceType:
      type: string
      enum:
      - LINEAR
      - API
      - SLACK
      - LOCAL
      - SCHEDULED_AGENT
      - WEB_APP
      - GITHUB_ACTION
      - CLOUD_MODE
      - CLI
      - JIRA
      - SELF_IMPROVEMENT
      - GITHUB_WEBHOOK
      - GITLAB_WEBHOOK
      - AUTOFIX
      - RUN_SCORER
      - ORCHESTRATION
      description: |-
        Source that created the run:
        - LINEAR: Created from Linear integration
        - API: Created via the Warp API
        - SLACK: Created from Slack integration
        - LOCAL: Created from local CLI/app
        - SCHEDULED_AGENT: Created by a scheduled agent
        - WEB_APP: Created from the Warp web app
        - GITHUB_ACTION: Created from a GitHub action
        - CLOUD_MODE: Created from a Cloud Mode
        - CLI: Created from the CLI
        - JIRA: Created from Jira integration
        - SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline
        - GITHUB_WEBHOOK: Created from a GitHub webhook event
        - GITLAB_WEBHOOK: Created from a GitLab webhook event
        - AUTOFIX: Created by Warp's autofix pipeline
        - RUN_SCORER: Created by Warp's run-scoring judge
        - ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set)
    RunExecutionLocation:
      type: string
      enum:
      - LOCAL
      - REMOTE
      description: |
        Where the run executed:
        - LOCAL: Executed in the user's local Warp environment
        - REMOTE: Executed by a remote/cloud worker
    AmbientAgentConfig:
      type: object
      description: Configuration for a cloud agent run
      properties:
        name:
          type: string
          description: |
            Human-readable label for grouping, filtering, and traceability.
            Automatically set to the skill name when running a skill-based agent.
            Set this explicitly to categorize runs by intent (e.g., "nightly-dependency-check")
            so you can filter and track them via the name query parameter on GET /agent/runs.
        model_id:
          type: string
          description: LLM model to use (uses team default if not specified)
        base_prompt:
          type: string
          description: Custom base prompt for the agent
        environment_id:
          type: string
          description: UID of the environment to run the agent in
        runner_id:
          type: string
          description: |
            UID of the runner providing the run's compute (platform, instance
            shape, and setup commands). When omitted on a request, the runner is
            resolved at run creation from the agent's default runner, then the
            environment's default runner, and the resolved UID is recorded on
            the run.
        skill_spec:
          type: string
          description: |
            Skill specification identifying the primary agent skill to use,
            in `{owner}/{repo}:{skill_path}` format (e.g.
            `warpdotdev/warp-server:.claude/skills/deploy/SKILL.md`);
            mutually exclusive with `skills` in create/update requests.
            Responses include the first `skills` entry here for backward
            compatibility; use the list agents endpoint to discover
            available skills.
        skills:
          type: array
          items:
            type: string
          description: |
            Ordered skill specifications to attach to the run.
            Format: "{owner}/{repo}:{skill_path}"
            Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"
            Mutually exclusive with skill_spec in create/update requests.
        mcp_servers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MCPServerConfig'
          description: Map of MCP server configurations by name
        computer_use_enabled:
          type: boolean
          description: |
            Controls whether computer use is enabled for this agent.
            If not set, defaults to true.
        computer_use_model_id:
          type: string
          description: |
            Model the computer use subagent runs on; if omitted, the subagent
            picks its own model automatically. Only applies to the built-in
            Warp harness — the value is accepted but has no effect under a
            third-party harness or when computer use is disabled. Requires an
            agent CLI version that supports the --computer-use-model flag.
        idle_timeout_minutes:
          type: integer
          format: int32
          minimum: 1
          maximum: 60
          description: |
            Number of minutes to keep the agent environment alive after task completion.
            If not set, defaults to 10 minutes.
            Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).
        worker_host:
          type: string
          description: |
            Self-hosted worker ID that should execute this task.
            If not specified or set to "warp", the task runs on Warp-hosted workers.
        harness:
          $ref: '#/components/schemas/Harness'
        harness_auth_secrets:
          $ref: '#/components/schemas/HarnessAuthSecrets'
        session_sharing:
          $ref: '#/components/schemas/SessionSharingConfig'
        memory_stores:
          type: array
          items:
            $ref: '#/components/schemas/MemoryStoreRef'
          description: Memory stores to attach to this run.
        inference_providers:
          allOf:
          - $ref: '#/components/schemas/InferenceProvidersConfig'
          description: |
            Optional inference provider settings for this run. Run-level
            config takes precedence over the agent's stored config and
            the workspace's admin-configured defaults.
        credential_strategy:
          type: string
          nullable: true
          enum:
          - CREATOR
          - EXECUTOR
          description: |
            Controls which principal's credentials are used when the
            platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on
            behalf of this run.
            - EXECUTOR (default when unset): credentials are sourced from
              the run's execution principal — a GitHub App installation
              token for agent principals, a personal OAuth token for user
              principals.
            - CREATOR: credentials are always sourced from the run creator
              regardless of the execution principal, useful when a service
              account executes the run but Git operations should
              authenticate as the triggering human.
    SessionSharingConfig:
      type: object
      description: |
        Configures sharing behavior for the run's shared session; when set,
        the worker emits `--share public:<level>` and the bundled Warp
        client applies an anyone-with-link ACL to the shared session once it
        has bootstrapped. The same ACL is mirrored onto the backing
        conversation so link viewers can read it without being on the run's
        team, subject to the workspace-level anyone-with-link sharing
        setting.
      properties:
        public_access:
          type: string
          enum:
          - VIEWER
          - EDITOR
          description: |
            Grants anyone-with-link access at the specified level to the
            run's shared session and backing conversation; link viewers
            must still be authenticated Warp users (anonymous reads are not
            supported in this release).
            - VIEWER: link viewers can read the session and conversation.
            - EDITOR: link viewers can also interact with the session.
    Harness:
      type: object
      description: |
        Specifies which execution harness to use for the agent run.
        Default (nil/empty) uses Warp's built-in harness.
        When stored as a named agent's default (create/update agent identity),
        this field replaces the deprecated base_harness/base_model pair: a
        harness other than `oz` here requires the agent's base_model to be
        empty, since the two describe mutually exclusive default models.
      properties:
        type:
          type: string
          enum:
          - oz
          - claude
          - gemini
          - codex
          description: |
            The harness type identifier.
            - oz: Warp's built-in harness (default)
            - claude: Claude Code harness
            - gemini: Gemini CLI harness
            - codex: Codex CLI harness
        model_id:
          type: string
          description: |
            Model to use with a third-party harness (e.g. "claude-haiku-4-5").
            Only applies when type is a harness other than `oz`; the
            top-level config model_id targets the built-in Warp harness
            instead. When omitted or empty, the harness uses its own default
            model.
        reasoning_level:
          type: string
          description: |
            Reasoning effort for harnesses that support it (e.g. Codex).
            Only applies when type is a harness other than `oz`. Ignored by
            harnesses that do not support reasoning levels.
    HarnessAuthSecrets:
      type: object
      description: |
        Authentication secrets for third-party harnesses.
        Only the secret for the harness specified gets injected into the environment.
      properties:
        claude_auth_secret_name:
          type: string
          description: |
            Name of a managed secret for Claude Code harness authentication.
            The secret must exist within the caller's personal or team scope.
            Only applicable when harness type is "claude".
        codex_auth_secret_name:
          type: string
          description: |
            Name of a managed secret for Codex harness authentication.
            The secret must exist within the caller's personal or team scope.
            Only applicable when harness type is "codex".
    MCPServerConfig:
      type: object
      description: |
        Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.
      properties:
        warp_id:
          type: string
          description: |
            Reference to a Warp shared MCP server by UUID, or a well-known
            integration MCP id (e.g. "linear") backed by the team's integration
            connection.
        command:
          type: string
          description: Stdio transport - command to run
        args:
          type: array
          items:
            type: string
          description: Stdio transport - command arguments
        url:
          type: string
          format: uri
          description: SSE/HTTP transport - server URL
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables for the server
        headers:
          type: object
          additionalProperties:
            type: string
          description: HTTP headers for SSE/HTTP transport
    Error:
      type: object
      description: |
        Error response following RFC 7807 (Problem Details for HTTP APIs),
        using the `application/problem+json` content type. Includes
        backward-compatible extension members; additional ones (e.g.,
        `auth_url`, `provider`) may be present depending on the error code.
      required:
      - type
      - title
      - status
      - error
      properties:
        type:
          type: string
          format: uri
          description: |
            A URI reference that identifies the problem type (RFC 7807).
            Format: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`
            See PlatformErrorCode for the list of possible error codes.
        title:
          type: string
          description: A short, human-readable summary of the problem type (RFC 7807)
        status:
          type: integer
          description: The HTTP status code for this occurrence of the problem (RFC 7807)
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem (RFC 7807)
        instance:
          type: string
          description: The request path that generated this error (RFC 7807)
        error:
          type: string
          description: |
            Human-readable error message combining title and detail.
            Backward-compatible extension member for older clients.
        retryable:
          type: boolean
          description: |
            Whether the request can be retried. When true, the error is transient
            and the request may be retried. When false, retrying without addressing
            the underlying cause will not succeed.
        trace_id:
          type: string
          description: OpenTelemetry trace ID for debugging and support requests
        provider:
          type: string
          description: External provider that requires authorization, such as `linear`.
        auth_url:
          type: string
          format: uri
          description: URL where the caller can reconnect the external provider.
    ArtifactResponse:
      oneOf:
      - $ref: '#/components/schemas/PlanArtifactResponse'
      - $ref: '#/components/schemas/ScreenshotArtifactResponse'
      - $ref: '#/components/schemas/FileArtifactResponse'
      discriminator:
        propertyName: artifact_type
        mapping:
          PLAN: '#/components/schemas/PlanArtifactResponse'
          SCREENSHOT: '#/components/schemas/ScreenshotArtifactResponse'
          FILE: '#/components/schemas/FileArtifactResponse'
    PlanArtifactResponse:
      type: object
      description: Response for retrieving a plan artifact.
      required:
      - artifact_uid
      - artifact_type
      - created_at
      - data
      properties:
        artifact_uid:
          type: string
          description: Unique identifier (UUID) for the artifact
        artifact_type:
          type: string
          enum:
          - PLAN
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/PlanArtifactResponseData'
    PlanArtifactResponseData:
      type: object
      description: Response data for a plan artifact, including current markdown content.
      required:
      - document_uid
      - notebook_uid
      - content
      - content_type
      properties:
        document_uid:
          type: string
          description: Unique identifier for the plan document
        notebook_uid:
          type: string
          description: Unique identifier for the associated notebook
        url:
          type: string
          format: uri
          description: URL to open the plan in Warp Drive
        title:
          type: string
          description: Current title of the plan
        content:
          type: string
          description: Current markdown content of the plan
        content_type:
          type: string
          description: MIME type of the returned plan content
    ScreenshotArtifactResponse:
      type: object
      description: Response for retrieving a screenshot artifact.
      required:
      - artifact_uid
      - artifact_type
      - created_at
      - data
      properties:
        artifact_uid:
          type: string
          description: Unique identifier (UUID) for the artifact
        artifact_type:
          type: string
          enum:
          - SCREENSHOT
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/ScreenshotArtifactResponseData'
    ScreenshotArtifactResponseData:
      type: object
      description: Response data for a screenshot artifact, including a signed download URL.
      required:
      - download_url
      - expires_at
      - content_type
      properties:
        download_url:
          type: string
          format: uri
          description: Time-limited signed URL to download the screenshot
        expires_at:
          type: string
          format: date-time
          description: Timestamp when the download URL expires (RFC3339)
        content_type:
          type: string
          description: MIME type of the screenshot (e.g., image/png)
        description:
          type: string
          description: Optional description of the screenshot
    FileArtifactResponse:
      type: object
      description: Response for retrieving a file artifact.
      required:
      - artifact_uid
      - artifact_type
      - created_at
      - data
      properties:
        artifact_uid:
          type: string
          description: Unique identifier (UUID) for the artifact
        artifact_type:
          type: string
          enum:
          - FILE
          description: Type of the artifact
        created_at:
          type: string
          format: date-time
          description: Timestamp when the artifact was created (RFC3339)
        data:
          $ref: '#/components/schemas/FileArtifactResponseData'
    FileArtifactResponseData:
      type: object
      description: Response data for a file artifact, including a signed download URL.
      required:
      - download_url
      - expires_at
      - content_type
      - filename
      properties:
        download_url:
          type: string
          format: uri
          description: Time-limited signed URL to download the file
        expires_at:
          type: string
          format: date-time
          description: Timestamp when the download URL expires (RFC3339)
        content_type:
          type: string
          description: MIME type of the uploaded file
        filepath:
          type: string
          description: |
            Conversation-relative filepath for the uploaded file. Omitted for
            anonymous reads of public artifacts.
        filename:
          type: string
          description: Last path component of filepath
        title:
          type: string
          description: |
            Short, badge-visible label for the artifact. For recording artifacts,
            this is the agent-authored title shown in Warp web and blocklist badges.
            Distinct from description, which is longer and shown in detail views.
        description:
          type: string
          description: Optional description of the file
        size_bytes:
          type: integer
          format: int64
          description: Size of the uploaded file in bytes
    AttachmentInput:
      type: object
      description: A base64-encoded file attachment to include with the prompt
      required:
      - file_name
      - mime_type
      - data
      properties:
        file_name:
          type: string
          description: Name of the attached file
        mime_type:
          type: string
          description: |
            MIME type of the attachment.
            Supported image types: image/jpeg, image/png, image/gif, image/webp
        data:
          type: string
          format: byte
          description: Base64-encoded attachment data
    ScheduledAgentItem:
      type: object
      required:
      - id
      - name
      - cron_schedule
      - enabled
      - prompt
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the scheduled agent
        name:
          type: string
          description: Human-readable name for the schedule
        cron_schedule:
          type: string
          description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
        enabled:
          type: boolean
          description: Whether the schedule is currently active
        prompt:
          type: string
          description: The prompt/instruction for the agent to execute
        last_spawn_error:
          type: string
          nullable: true
          description: Error message from the last failed spawn attempt, if any
        agent_config:
          $ref: '#/components/schemas/AmbientAgentConfig'
        agent_uid:
          type: string
          format: uuid
          description: UID of the agent that this schedule runs as
        metadata:
          allOf:
          - $ref: '#/components/schemas/RunMetadata'
          description: Custom metadata stamped onto every run spawned by this schedule
        environment:
          allOf:
          - $ref: '#/components/schemas/CloudEnvironmentConfig'
          description: Resolved environment configuration (if agent_config references an environment_id)
        created_at:
          type: string
          format: date-time
          description: Timestamp when the schedule was created (RFC3339)
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the schedule was last updated (RFC3339)
        created_by:
          $ref: '#/components/schemas/RunCreatorInfo'
        updated_by:
          $ref: '#/components/schemas/RunCreatorInfo'
        history:
          $ref: '#/components/schemas/ScheduledAgentHistoryItem'
        scope:
          $ref: '#/components/schemas/Scope'
    ScheduledAgentHistoryItem:
      type: object
      description: Scheduler-derived history metadata for a scheduled agent
      properties:
        last_ran:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the last successful run (RFC3339)
        next_run:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the next scheduled run (RFC3339)
    CreateScheduledAgentRequest:
      type: object
      description: |
        Request body for creating a new scheduled agent.
        Either prompt or agent_config.skill_spec or agent_config.skills is required.
      required:
      - name
      - cron_schedule
      properties:
        name:
          type: string
          description: Human-readable name for the schedule
        cron_schedule:
          type: string
          description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
        prompt:
          type: string
          description: |
            The prompt/instruction for the agent to execute.
            Required unless agent_config.skill_spec or agent_config.skills is provided.
        mode:
          $ref: '#/components/schemas/AgentRunMode'
          description: |
            Optional query mode applied to every triggered run. Defaults to
            `normal` when omitted. The server does not infer mode from prompt
            prefixes such as `/plan`.
        enabled:
          type: boolean
          description: Whether the schedule should be active immediately
          default: true
        agent_uid:
          type: string
          format: uuid
          description: |
            Agent UID to use as the execution principal for this schedule.
            Only valid for team-owned schedules.
        agent_config:
          $ref: '#/components/schemas/AmbientAgentConfig'
        team:
          type: boolean
          description: |
            Whether to create a team-owned schedule.
            Defaults to true for users on a single team.
        metadata:
          allOf:
          - $ref: '#/components/schemas/RunMetadata'
          description: |
            Custom metadata stamped onto every run spawned by this schedule as the run's
            explicit metadata layer.
    UpdateScheduledAgentRequest:
      type: object
      description: |
        Request body for updating a scheduled agent.
        Either prompt or agent_config.skill_spec or agent_config.skills is required.
      required:
      - name
      - cron_schedule
      - enabled
      properties:
        name:
          type: string
          description: Human-readable name for the schedule
        cron_schedule:
          type: string
          description: Cron expression defining when the agent runs
        prompt:
          type: string
          description: |
            The prompt/instruction for the agent to execute.
            Required unless agent_config.skill_spec or agent_config.skills is provided.
        mode:
          $ref: '#/components/schemas/AgentRunMode'
          description: |
            Optional query mode applied to every triggered run. Defaults to
            `normal` when omitted. The server does not infer mode from prompt
            prefixes such as `/plan`.
        enabled:
          type: boolean
          description: Whether the schedule should be active
        agent_uid:
          type: string
          format: uuid
          description: |
            Agent UID to use as the execution principal for this schedule.
            Only valid for team-owned schedules.
        agent_config:
          $ref: '#/components/schemas/AmbientAgentConfig'
        metadata:
          allOf:
          - $ref: '#/components/schemas/RunMetadata'
          description: |
            Custom metadata stamped onto every run spawned by this schedule.
            Updates follow full-replacement PUT semantics: omitting this field
            clears the schedule's metadata. Changes apply only to future runs.
    ListScheduledAgentsResponse:
      type: object
      required:
      - schedules
      properties:
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledAgentItem'
          description: List of scheduled agents
    DeleteScheduledAgentResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the deletion was successful
    CloudEnvironmentConfig:
      type: object
      description: Configuration for a cloud environment used by scheduled agents
      properties:
        name:
          type: string
          description: Human-readable name for the environment
        description:
          type: string
          nullable: true
          description: Optional description of the environment
        docker_image:
          type: string
          description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")
        github_repos:
          type: array
          items:
            $ref: '#/components/schemas/GitHubRepo'
          description: List of GitHub repositories to clone into the environment
        setup_commands:
          type: array
          items:
            type: string
          description: Shell commands to run during environment setup
        providers:
          $ref: '#/components/schemas/ProvidersConfig'
        failure_session_retention_minutes:
          type: integer
          nullable: true
          minimum: 1
          maximum: 60
          description: |
            When set (1–60 minutes), a failed run using this environment
            keeps its session open for this many minutes so it can be
            inspected; null or absent means immediate teardown (disabled by
            default). This is an idle window held open by the agent process:
            activity in the session pushes the deadline out (so an active
            session is not torn down mid-debug), and it ends early if the
            run's sandbox reaches its own deadline first. Applies only to
            future failures of runs using this environment; opting in keeps
            injected environment data (including secrets) alive and incurs
            compute usage for as long as the session is held open.
    ProvidersConfig:
      type: object
      description: Optional cloud provider configurations for automatic auth
      properties:
        gcp:
          $ref: '#/components/schemas/GcpProviderConfig'
        aws:
          $ref: '#/components/schemas/AwsProviderConfig'
    InferenceProvidersConfig:
      type: object
      description: Inference provider settings used for LLM calls.
      properties:
        aws:
          $ref: '#/components/schemas/AwsInferenceProviderConfig'
    GcpProviderConfig:
      type: object
      description: GCP Workload Identity Federation settings
      required:
      - project_number
      - workload_identity_federation_pool_id
      - workload_identity_federation_provider_id
      externalDocs:
        description: Google documentation on Workload Identity Federation
        url: https://docs.cloud.google.com/iam/docs/workload-identity-federation
      properties:
        project_number:
          type: string
          description: GCP project number
        workload_identity_federation_pool_id:
          type: string
          description: Workload Identity Federation pool ID
        workload_identity_federation_provider_id:
          type: string
          description: Workload Identity Federation provider ID
        service_account_email:
          type: string
          description: Optional GCP service account email to impersonate
    AwsProviderConfig:
      type: object
      description: AWS IAM role assumption settings
      externalDocs:
        description: AWS documentation on IAM OIDC federation
        url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html
      required:
      - role_arn
      properties:
        role_arn:
          type: string
          description: AWS IAM role ARN to assume
    AwsInferenceProviderConfig:
      type: object
      description: |
        Configures AWS Bedrock as the LLM inference provider for this
        agent or run.
      externalDocs:
        description: AWS documentation on IAM OIDC federation
        url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html
      properties:
        disabled:
          type: boolean
          description: If true, opt out of Bedrock at this layer.
        role_arn:
          type: string
          description: IAM role ARN to assume when calling Bedrock.
        region:
          type: string
          description: AWS region used for STS when assuming the Bedrock inference role.
    GitHubRepo:
      type: object
      required:
      - owner
      - repo
      properties:
        owner:
          type: string
          description: GitHub repository owner (user or organization)
        repo:
          type: string
          description: GitHub repository name
    ListAgentsResponse:
      type: object
      required:
      - agents
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentListItem'
          description: List of available agents
    ListConnectedSelfHostedWorkersResponse:
      type: object
      required:
      - workers
      properties:
        workers:
          type: array
          items:
            $ref: '#/components/schemas/ConnectedSelfHostedWorker'
          description: Connected self-hosted workers for the authenticated principal's team
    ConnectedSelfHostedWorker:
      type: object
      required:
      - worker_host
      - connection_count
      - connected_at
      - last_seen_at
      properties:
        worker_host:
          type: string
          description: Logical host identifier provided by the self-hosted worker
        connection_count:
          type: integer
          description: Number of active websocket connections currently observed for this worker host
        connected_at:
          type: string
          format: date-time
          description: Earliest connection timestamp across active connections for this worker host
        last_seen_at:
          type: string
          format: date-time
          description: Most recent heartbeat timestamp across active connections for this worker host
    AgentListItem:
      type: object
      required:
      - name
      - variants
      properties:
        name:
          type: string
          description: Human-readable name of the agent
        variants:
          type: array
          items:
            $ref: '#/components/schemas/AgentListVariant'
          description: Available variants of this agent
    AgentListVariant:
      type: object
      required:
      - id
      - description
      - base_prompt
      - source
      - environments
      properties:
        id:
          type: string
          description: |
            Stable identifier for this skill variant.
            Format: "{owner}/{repo}:{skill_path}"
            Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"
        description:
          type: string
          description: Description of the agent variant
        base_prompt:
          type: string
          description: Base prompt/instructions for the agent
        source:
          $ref: '#/components/schemas/AgentListSource'
        environments:
          type: array
          items:
            $ref: '#/components/schemas/AgentListEnvironment'
          description: Environments where this agent variant is available
        last_run_timestamp:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the last time this skill was run (RFC3339)
        error:
          type: string
          description: |
            Non-empty when the skill's SKILL.md file exists but is malformed.
            Contains a description of the parse failure. Only present when
            include_malformed_skills=true is passed to the list agents endpoint.
    AgentListSource:
      type: object
      required:
      - owner
      - name
      - skill_path
      properties:
        owner:
          type: string
          description: GitHub repository owner
        name:
          type: string
          description: GitHub repository name
        skill_path:
          type: string
          description: Path to the skill definition file within the repository
        worker_host:
          type: string
          description: |
            Self-hosted worker host that reported this skill.
            Present only for skills discovered from self-hosted workers
            (as opposed to skills from GitHub repos linked to environments).
    AgentListEnvironment:
      type: object
      required:
      - uid
      - name
      properties:
        uid:
          type: string
          description: Unique identifier for the environment
        name:
          type: string
          description: Human-readable name of the environment
    Scope:
      type: object
      description: Ownership scope for a resource (team or personal)
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - User
          - Team
          description: Type of ownership ("User" for personal, "Team" for team-owned)
        uid:
          type: string
          description: UID of the owning user or team
    PlatformErrorCode:
      type: string
      description: |
        Machine-readable error code identifying the problem type.
        Used in the `type` URI of Error responses and in the `error_code`
        field of RunStatusMessage.

        User errors (run transitions to FAILED):
        - `insufficient_credits` — Team has no remaining add-on credits
        - `feature_not_available` — Required feature not enabled for user's plan
        - `external_authentication_required` — User hasn't authorized a required external service
        - `not_authorized` — Principal lacks permission for the requested operation
        - `invalid_request` — Request is malformed or contains invalid parameters
        - `resource_not_found` — Referenced resource does not exist
        - `budget_exceeded` — Spending budget limit has been reached
        - `integration_disabled` — Integration is disabled and must be enabled
        - `integration_not_configured` — Integration setup is incomplete
        - `operation_not_supported` — Requested operation not supported for this resource/state
        - `environment_setup_failed` — Client-side environment setup failed
        - `content_policy_violation` — Prompt or setup commands violated content policy
        - `conflict` — Request conflicts with the current state of the resource

        Warp errors (run transitions to ERROR):
        - `authentication_required` — Request lacks valid authentication credentials
        - `resource_unavailable` — Transient infrastructure issue (retryable)
        - `internal_error` — Unexpected server-side error (retryable)
      enum:
      - insufficient_credits
      - feature_not_available
      - external_authentication_required
      - not_authorized
      - invalid_request
      - resource_not_found
      - budget_exceeded
      - integration_disabled
      - integration_not_configured
      - operation_not_supported
      - environment_setup_failed
      - content_policy_violation
      - conflict
      - authentication_required
      - resource_unavailable
      - internal_error
    RunFollowupRequest:
      type: object
      description: Request body for submitting a follow-up message to an existing run.
      properties:
        message:
          type: string
          description: The follow-up message to send to the run.
        mode:
          $ref: '#/components/schemas/AgentRunMode'
          description: |
            Optional query mode for the follow-up. Defaults to `normal` when
            omitted. The server does not infer mode from prompt prefixes such
            as `/plan`.
    ListModelsResponse:
      type: object
      required:
      - default_model_id
      - models
      properties:
        default_model_id:
          type: string
          description: The ID of the default model for agent runs
        models:
          type: array
          items:
            $ref: '#/components/schemas/ModelInfo'
          description: List of available models
    ModelInfo:
      type: object
      required:
      - id
      - display_name
      - provider
      - vision_supported
      properties:
        id:
          type: string
          description: Unique identifier for the model (e.g. "claude-4-6-opus-high" or "gpt-5-4-high")
        display_name:
          type: string
          description: Human-readable name of the model
        provider:
          type: string
          enum:
          - OPENAI
          - ANTHROPIC
          - GOOGLE
          - UNKNOWN
          description: The LLM provider
        vision_supported:
          type: boolean
          description: Whether the model supports vision/image inputs
        description:
          type: string
          description: Optional extra descriptor for the model
        reasoning_level:
          type: string
          description: Reasoning level descriptor, if any (e.g. "low", "medium", "high")
        disable_reason:
          type: string
          enum:
          - PROVIDER_OUTAGE
          - OUT_OF_REQUESTS
          - ADMIN_DISABLED
          - REQUIRES_UPGRADE
          description: If set, the model is currently unavailable for the given reason
    ExternalReferenceArtifactData:
      type: object
      description: Data for a generic external reference artifact.
      required:
      - reference_type
      - url
      properties:
        reference_type:
          type: string
          maxLength: 256
          description: |
            Free-form category identifier for this reference (e.g. "linear_issue",
            "spec_link", "jira_ticket"). Used for filtering and display.
        url:
          type: string
          maxLength: 2048
          description: |
            Canonical URL for the reference. Used as the key for reverse lookups
            ("which run produced this URL?").
        title:
          type: string
          description: Optional human-readable label for the reference.
        metadata:
          type: object
          additionalProperties: true
          description: Optional category-specific extra fields.
    RunByExternalReferenceResponse:
      type: object
      description: Response for a run reverse-lookup by external reference URL.
      required:
      - run_id
      properties:
        run_id:
          type: string
          description: The ID of the run that produced the external reference.
    AgentSkill:
      type: object
      description: |
        Information about the agent skill used for the run.
        Either full_path or bundled_skill_id will be set, but not both.
      properties:
        name:
          type: string
          description: Human-readable name of the skill
        description:
          type: string
          description: Description of the skill
        full_path:
          type: string
          description: Path to the SKILL.md file (for file-based skills)
        bundled_skill_id:
          type: string
          description: Unique identifier for bundled skills
    ListEnvironmentsResponse:
      type: object
      required:
      - environments
      properties:
        environments:
          type: array
          items:
            $ref: '#/components/schemas/CloudEnvironment'
          description: List of accessible cloud environments
    CloudEnvironment:
      type: object
      description: A cloud environment for running agents
      required:
      - uid
      - config
      - last_updated
      - setup_failed
      properties:
        uid:
          type: string
          description: Unique identifier for the environment
        config:
          $ref: '#/components/schemas/CloudEnvironmentConfig'
        last_updated:
          type: string
          format: date-time
          description: Timestamp when the environment was last updated (RFC3339)
        last_task_run_timestamp:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the most recent task run in this environment (RFC3339)
        last_task_created:
          $ref: '#/components/schemas/EnvironmentLastTask'
        setup_failed:
          type: boolean
          description: True when the most recent task failed during setup before it started running
        scope:
          $ref: '#/components/schemas/Scope'
        creator:
          $ref: '#/components/schemas/RunCreatorInfo'
        last_editor:
          $ref: '#/components/schemas/RunCreatorInfo'
    SecretRef:
      type: object
      description: |
        Reference to a managed secret by name.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the managed secret.
    MemoryStoreRef:
      type: object
      description: Reference to a memory store to attach to an agent.
      required:
      - uid
      - access
      - instructions
      properties:
        uid:
          type: string
          description: UID of the memory store.
        access:
          type: string
          enum:
          - read_write
          - read_only
          description: Access level for the store.
        instructions:
          type: string
          description: Instructions for how the agent should use this memory store. Must not be empty.
    MemoryStoreAttachmentResponse:
      type: object
      description: Memory store attached to an agent.
      required:
      - uid
      - access
      - instructions
      - owner_type
      - owner_uid
      properties:
        uid:
          type: string
          description: UID of the memory store.
        access:
          type: string
          enum:
          - read_write
          - read_only
          description: Access level for the store.
        instructions:
          type: string
          description: Instructions for how the agent should use this memory store.
        owner_type:
          type: string
          description: Public owner type.
          enum:
          - user
          - service_account
          - team
        owner_uid:
          type: string
          description: Public UID of the user, service account, or team that owns the memory store.
        description:
          type: string
          description: Optional description for the memory store.
    AgentAutoMemoryCreateConfig:
      type: object
      description: Auto-memory settings for creating an agent.
      properties:
        enabled:
          type: boolean
          description: |
            Whether to create and attach a default service-account-owned memory store for this agent.
            Defaults to true when omitted.
    AgentMemoryCreateConfig:
      type: object
      description: Memory settings for creating an agent.
      properties:
        auto_memory:
          allOf:
          - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig'
          description: Agent-owned memory settings. Defaults to enabled when omitted.
        attached_stores:
          type: array
          items:
            $ref: '#/components/schemas/MemoryStoreRef'
          description: |
            Existing team memory stores to attach to the agent.
            Duplicate UIDs within a single request are rejected.
    AgentMemoryUpdateConfig:
      type: object
      description: Memory settings for updating an agent.
      properties:
        attached_stores:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/MemoryStoreRef'
          description: |
            Replacement list of attached team memory stores. Omit to leave unchanged,
            pass an empty array to clear, or pass a non-empty array to replace.
    AgentAutoMemoryResponse:
      type: object
      description: Auto-memory state for an agent.
      required:
      - enabled
      properties:
        enabled:
          type: boolean
          description: Whether this agent has an agent-owned memory store.
        store:
          $ref: '#/components/schemas/MemoryStoreAttachmentResponse'
    AgentMemoryResponse:
      type: object
      description: Memory settings for an agent.
      required:
      - auto_memory
      - attached_stores
      properties:
        auto_memory:
          $ref: '#/components/schemas/AgentAutoMemoryResponse'
        attached_stores:
          type: array
          items:
            $ref: '#/components/schemas/MemoryStoreRef'
          description: Team memory stores attached to the agent.
    AgentCredentialStrategy:
      type: string
      description: |
        Default credential strategy for runs executed by a named agent; an
        agent may leave this unset (see AgentResponse.credential_strategy
        for the full resolution order).
        - EXECUTOR: runs authenticate with the named agent's own credentials
          (e.g. a GitHub App installation token for the agent's team).
        - CREATOR: runs authenticate with the credentials of the principal
          that created the run.
      enum:
      - CREATOR
      - EXECUTOR
    ReportedRunScore:
      type: object
      required:
      - scorer_id
      properties:
        scorer_id:
          type: integer
          description: The evaluation this verdict belongs to
        classification:
          type: string
          description: |
            The chosen classification. Must exactly match one of the allowed
            label values captured when the evaluation was dispatched. Ignored
            when `failed` is true.
        reason:
          type: string
          description: |
            Optional judge reasoning. Stored outside the database and truncated
            beyond 8KB; a storage failure does not reject the verdict.
        failed:
          type: boolean
          description: |
            True when the judge could not evaluate this evaluation. Failed
            verdicts are accepted but record no score.
    ReportRunScoresRequest:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ReportedRunScore'
    ReportedRunScoreOutcome:
      type: object
      required:
      - scorer_id
      - status
      properties:
        scorer_id:
          type: integer
          description: The evaluation this outcome belongs to
        status:
          type: string
          description: 'Whether the verdict was recorded: "accepted" or "rejected"'
        error:
          type: string
          description: Why the verdict was rejected; absent when accepted
    ReportRunScoresResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ReportedRunScoreOutcome'
    CreateAgentRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: A name for the agent
        description:
          type: string
          nullable: true
          description: Optional description of the agent
        prompt:
          type: string
          nullable: true
          description: |
            Optional base prompt for this agent
        environment_id:
          type: string
          nullable: true
          description: |
            Optional default cloud environment ID for runs executed by this agent.
            The environment must be owned by the same team as the agent.
        default_runner_uid:
          type: string
          nullable: true
          description: |
            Optional default runner UID for runs executed by this agent. When set,
            it overrides the selected environment's default runner for runs that
            do not specify their own `runner_id`. The editor must have View
            permission on the referenced runner.
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/SecretRef'
          description: |
            Optional list of secrets associated with the agent.
            Duplicate names within a single request are rejected.
            Each entry is unioned into the run-time secret scope when the agent executes.
        skills:
          type: array
          items:
            type: string
          description: |
            Optional list of skill specs to associate with the agent.
            Format: "{owner}/{repo}:{skill_path}" (e.g., "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md").
            Each spec is validated and normalized at attach time using the team's GitHub
            credentials; inaccessible or malformed specs are rejected.
        base_model:
          type: string
          nullable: true
          description: |
            Optional base model for runs executed by this agent.
        inference_providers:
          allOf:
          - $ref: '#/components/schemas/InferenceProvidersConfig'
          description: |
            Optional inference provider settings for this agent.
            Agent-level config takes precedence over the workspace's
            admin-configured defaults.
        memory:
          allOf:
          - $ref: '#/components/schemas/AgentMemoryCreateConfig'
          description: Optional memory settings for the agent.
        mcp_servers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MCPServerConfig'
          description: |
            Optional map of MCP server configurations by name to attach to runs executed by this agent.
            Run-level MCP config takes precedence over this agent-level default.
        base_harness:
          type: string
          nullable: true
          deprecated: true
          description: |
            Optional default harness for runs executed by this agent.
            Deprecated - use harness instead. Kept for backward compatibility;
            when both are sent, harness is authoritative and a conflicting
            type is rejected with invalid_request.
        harness:
          allOf:
          - $ref: '#/components/schemas/Harness'
          description: |
            Optional default harness for runs executed by this agent.
            Omission or an empty object stores no harness default.
        credential_strategy:
          allOf:
          - $ref: '#/components/schemas/AgentCredentialStrategy'
          nullable: true
          description: |
            Optional default credential strategy for runs executed by this
            agent. When omitted or null, the agent has no opinion and runs fall
            back to the factory default (for factory-seeded agents) and then to
            EXECUTOR.
        harness_auth_secrets:
          allOf:
          - $ref: '#/components/schemas/HarnessAuthSecrets'
          description: |
            Optional per-harness authentication secrets for this agent.
            Each field names a managed secret for the corresponding harness.
            Secrets are resolved at execution time from the agent's team scope.
        on_behalf_of_enabled:
          type: boolean
          description: |
            Whether runs created with this agent's API key may use the on_behalf_of
            field to attribute runs to another team member. Defaults to false.
            Only team admins may set this field.
        worker_host:
          type: string
          nullable: true
          description: |
            Optional default worker host for runs executed by this agent;
            omission, null, or an empty value stores no Agent default, in
            which case the workspace default applies. A non-empty value is
            trimmed and stored (use "warp" to force Warp-hosted execution
            over a self-hosted workspace default), and is resolved in this
            order:
            1. The host specified on the run itself
            2. The agent's default host
            3. The workspace default host
    UpdateAgentRequest:
      type: object
      description: |
        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 wholesale with the provided value.
      properties:
        name:
          type: string
          description: The new name for the agent
        description:
          type: string
          nullable: true
          description: |
            Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear.
        prompt:
          type: string
          nullable: true
          description: |
            Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear.
        environment_id:
          type: string
          nullable: true
          description: |
            Replacement default cloud environment ID. Omit or pass `null` to leave unchanged,
            or pass an empty string to clear.
        default_runner_uid:
          type: string
          nullable: true
          description: |
            Replacement default runner UID. Omit or pass `null` to leave unchanged,
            or pass an empty string to clear. A non-empty value must reference a
            runner the editor can View.
        secrets:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SecretRef'
          description: |
            Replacement list of secrets. Omit to leave unchanged, pass an
            empty array to clear, or pass a non-empty array to replace.
            Duplicate names are rejected.
        skills:
          type: array
          nullable: true
          items:
            type: string
          description: |
            Replacement list of skill specs. Omit to leave unchanged, pass an empty array
            to clear, or pass a non-empty array to replace.
        base_model:
          type: string
          nullable: true
          description: |
            Replacement base model. Omit or pass `null` to leave unchanged,
            or pass an empty string to clear.
        memory:
          allOf:
          - $ref: '#/components/schemas/AgentMemoryUpdateConfig'
          nullable: true
          description: Replacement memory settings for this agent.
        mcp_servers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MCPServerConfig'
          description: |
            Replacement map of MCP server configurations by name. Omit to leave
            unchanged, pass an empty object to clear, or pass a non-empty object
            to replace. Run-level MCP config takes precedence over this agent-level
            default.
        inference_providers:
          type: object
          allOf:
          - $ref: '#/components/schemas/InferenceProvidersConfig'
          nullable: true
          description: |
            Replacement inference provider settings for this agent, which
            take precedence over the workspace's admin-configured defaults;
            omit or pass `null` to leave unchanged, or pass an empty object
            `{}` to clear.
        base_harness:
          type: string
          nullable: true
          deprecated: true
          description: |
            Replacement default harness; omit or pass `null` to leave
            unchanged, or pass an empty string to clear. Deprecated - use
            harness instead, kept only for backward compatibility: when both
            are sent, harness is authoritative and a conflicting type is
            rejected with invalid_request.
        harness:
          allOf:
          - $ref: '#/components/schemas/Harness'
          nullable: true
          description: |
            Replacement default harness for runs executed by this agent. Omit
            or pass `null` to leave unchanged, pass `{}` to clear the stored
            default, or pass a populated object to replace it wholesale.
        credential_strategy:
          allOf:
          - $ref: '#/components/schemas/AgentCredentialStrategy'
          nullable: true
          description: |
            Replacement default credential strategy. Omit or pass `null` to
            leave unchanged, or pass an empty string to clear the agent's
            default. An agent belonging to a file-managed factory cannot clear
            it: its agent file expresses the strategy by declaring it, and a
            file that declares none keeps the strategy already projected, so a
            clear is rejected with a 400.
        harness_auth_secrets:
          allOf:
          - $ref: '#/components/schemas/HarnessAuthSecrets'
          nullable: true
          description: |
            Replacement per-harness authentication secrets. Omit or pass `null`
            to leave unchanged, or pass an empty object to clear all secrets.
        on_behalf_of_enabled:
          type: boolean
          nullable: true
          description: |
            Whether runs created with this agent's API key may use the on_behalf_of
            field to attribute runs to another team member. Omit or pass `null` to
            leave unchanged. Only team admins may set this field.
        worker_host:
          type: string
          nullable: true
          description: |
            Replacement default worker host. Omit or pass `null` to leave
            unchanged, or pass an empty string to clear (the workspace default
            then applies). A non-empty value is trimmed and replaces the
            stored default; use "warp" to force Warp-hosted execution over a
            self-hosted workspace default.
    AgentResponse:
      type: object
      required:
      - uid
      - name
      - available
      - created_at
      - updated_at
      - secrets
      - skills
      - memory
      - default_runner_uid
      properties:
        uid:
          type: string
          description: Unique identifier for the agent
        name:
          type: string
          description: Name of the agent
        description:
          type: string
          nullable: true
          description: Optional description of the agent
        prompt:
          type: string
          nullable: true
          description: |
            Optional base prompt for this agent
        environment_id:
          type: string
          description: |
            Default cloud environment ID for runs executed by this agent;
            the precedence order for environment resolution is:
            1. The environment specified on the run itself
            2. The agent's default environment
            3. An empty environment
        default_runner_uid:
          type: string
          description: |
            Default runner UID for runs executed by this agent; when set,
            it overrides the selected environment's default runner for
            runs that do not specify their own `runner_id`. The precedence
            order for runner resolution is:
            1. The runner specified on the run itself
            2. The agent's default runner
            3. The selected environment's default runner
            4. The environment's legacy inline compute fields
            5. System defaults
        available:
          type: boolean
          description: Whether the agent is currently enabled. Defaults to true.
        created_at:
          type: string
          format: date-time
          description: When the agent was created (RFC3339)
        updated_at:
          type: string
          format: date-time
          description: When the agent was last updated (RFC3339)
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/SecretRef'
          description: |
            Secrets that this agent may access by default.
        skills:
          type: array
          items:
            type: string
          description: |
            Ordered list of normalized skill specs associated with this agent.
            Always present; empty when no skills are attached.
        base_model:
          type: string
          description: |
            Base model for runs executed by this agent; the precedence
            order for model resolution is:
            1. The model specified on the run itself
            2. The agent's base model
            3. The team's default model
        inference_providers:
          allOf:
          - $ref: '#/components/schemas/InferenceProvidersConfig'
          description: |
            The agent's stored inference provider settings. May be overridden
            by run-level config; if empty, falls back to the workspace's
            admin-configured defaults.
        memory:
          allOf:
          - $ref: '#/components/schemas/AgentMemoryResponse'
          description: |
            Memory settings for this agent.
            Always present; attached_stores is empty when no team stores are attached.
        mcp_servers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MCPServerConfig'
          description: |
            MCP server configurations attached to this agent by default.
            Run-level MCP config takes precedence over this agent-level default.
        base_harness:
          type: string
          deprecated: true
          description: |
            Default harness for runs executed by this agent; the
            precedence order for harness resolution is:
            1. The harness specified on the run itself
            2. The agent's base harness
            3. Warp
            Deprecated: use harness instead, which carries the full
            {type, model_id, reasoning_level} default.
        harness:
          allOf:
          - $ref: '#/components/schemas/Harness'
          description: |
            Default harness for runs executed by this agent. Absent when the
            agent has no harness default. A stored model_id/reasoning_level
            pair is still returned even if the model has since left the
            harness's catalog.
        credential_strategy:
          allOf:
          - $ref: '#/components/schemas/AgentCredentialStrategy'
          description: |
            Default credential strategy for runs executed by this agent.
            Absent when the agent has no default. The precedence order for
            credential strategy resolution is:
            1. The strategy specified on the run itself
            2. The agent's default strategy
            3. The factory's default strategy, for factory-seeded agents
            4. EXECUTOR
            The resolved strategy is credential-validated at run creation;
            an unavailable credential rejects the request before execution.
        harness_auth_secrets:
          allOf:
          - $ref: '#/components/schemas/HarnessAuthSecrets'
          description: |
            Per-harness authentication secrets configured on this agent.
            Each field names a managed secret for the corresponding harness.
            Secrets can be overridden per run.
        on_behalf_of_enabled:
          type: boolean
          description: |
            Whether runs created with this agent's API key may use the on_behalf_of
            field to attribute runs to another team member.
        worker_host:
          type: string
          description: |
            Default worker host for runs executed by this agent, or empty
            when unset; the precedence order for worker host resolution is:
            1. The host specified on the run itself
            2. The agent's default host
            3. The workspace default host
    ListAgentIdentitiesResponse:
      type: object
      required:
      - agents
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentResponse'
    EnvironmentLastTask:
      type: object
      description: Summary of the most recently created task for an environment
      required:
      - id
      - title
      - state
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier of the task
        title:
          type: string
          description: Title of the task
        state:
          $ref: '#/components/schemas/RunState'
        created_at:
          type: string
          format: date-time
          description: When the task was created (RFC3339)
        updated_at:
          type: string
          format: date-time
          description: When the task was last updated (RFC3339)
        started_at:
          type: string
          format: date-time
          nullable: true
          description: When the task started running (RFC3339), null if not yet started