openapi: 3.0.0 info: title: Oz Agent API version: 1.0.0 description: | API for creating, managing, and querying Oz cloud agent runs. These endpoints allow users to programmatically spawn agents, list runs, and retrieve detailed run information. contact: name: Warp Support url: 'https://docs.warp.dev' email: 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: - name: repo in: query description: | Optional repository specification to list agents from (format: "owner/repo"). If not provided, lists agents from all accessible environments. required: false schema: type: string - name: refresh in: query description: | When true, clears the agent list cache before fetching. Use this to force a refresh of the available agents. required: false schema: type: boolean default: false - name: sort_by in: query description: | Sort order for the returned agents. - "name": Sort alphabetically by name (default) - "last_run": Sort by most recently used required: false schema: type: string enum: - name - last_run - name: include_malformed_skills in: query description: | When true, includes skills whose SKILL.md file exists but is malformed. These variants will have a non-empty `error` field describing the parse failure. Defaults to false. required: false schema: type: boolean default: false responses: '200': description: List of available agents content: application/json: schema: $ref: '#/components/schemas/ListAgentsResponse' '400': description: Invalid repository specification content: application/json: schema: $ref: '#/components/schemas/Error' /agent/connected-self-hosted-workers: get: summary: List connected self-hosted workers description: | Retrieve currently connected self-hosted workers for the authenticated principal's team. Worker presence is derived from worker websocket heartbeats and may be briefly stale. operationId: listConnectedSelfHostedWorkers tags: - agent security: - bearerAuth: [] responses: '200': description: List of currently connected self-hosted workers content: application/json: schema: $ref: '#/components/schemas/ListConnectedSelfHostedWorkersResponse' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Not authorized to list connected workers content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/runs/{runId}/transcript': get: summary: Get run transcript description: | Retrieve the raw conversation transcript for an agent run. Returns a 302 redirect to a time-limited download URL for the transcript. operationId: getRunTranscript tags: - agent security: - bearerAuth: [] parameters: - name: runId in: path description: The unique identifier of the run required: true schema: type: string responses: '302': description: Redirect to a download URL for the transcript headers: Location: description: URL to download the transcript schema: type: string format: uri '400': description: Missing run ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access run transcript content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Run not found or has no transcript content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /agent/run: post: summary: Run an agent task description: | Spawn a cloud agent with a prompt and optional configuration. The agent will be queued for execution and assigned a unique run ID. operationId: runAgent deprecated: true tags: - agent security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunAgentRequest' examples: simple: summary: Simple prompt value: prompt: Fix the bug in auth.go withConfig: summary: With agent config value: prompt: Refactor the database layer config: name: my-agent model_id: gpt-5-4-high base_prompt: Focus on Go backend code title: DB Refactoring Run responses: '200': description: Run created successfully content: application/json: schema: $ref: '#/components/schemas/RunAgentResponse' '400': description: 'Invalid request (missing prompt, invalid config)' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 'No permission to access referenced resources (environment, MCP servers)' content: application/json: schema: $ref: '#/components/schemas/Error' /agent/runs: post: summary: Run a cloud agent description: | Spawn a cloud agent with a prompt and optional configuration. The agent will be queued for execution and assigned a unique run ID. operationId: createRun tags: - agent security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunAgentRequest' responses: '200': description: Run created successfully content: application/json: schema: $ref: '#/components/schemas/RunAgentResponse' '400': description: 'Invalid request (missing prompt, invalid config)' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 'No permission to access referenced resources (environment, MCP servers)' content: application/json: schema: $ref: '#/components/schemas/Error' get: summary: List agent runs description: | Retrieve a paginated list of agent runs with optional filtering. Results default to `sort_by=updated_at` and `sort_order=desc`. operationId: listRuns tags: - agent security: - bearerAuth: [] parameters: - name: limit in: query description: Maximum number of runs to return required: false schema: type: integer minimum: 1 maximum: 500 default: 20 - name: cursor in: query description: Pagination cursor from previous response required: false schema: type: string - name: sort_by in: query description: | Sort field for results. - `updated_at`: Sort by last update timestamp (default) - `created_at`: Sort by creation timestamp - `title`: Sort alphabetically by run title - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. required: false schema: type: string enum: - updated_at - created_at - title - agent default: updated_at - name: sort_order in: query description: Sort direction required: false schema: type: string enum: - asc - desc default: desc - name: state in: query description: | Filter by run state. Can be specified multiple times to match any of the given states. required: false schema: type: array items: $ref: '#/components/schemas/RunState' style: form explode: true - name: name in: query description: Filter by agent config name required: false schema: type: string - name: model_id in: query description: Filter by model ID required: false schema: type: string - name: creator in: query description: Filter by creator UID (user or service account) required: false schema: type: string - name: executor in: query description: | Filter by the user or agent that executed the run. This will often be the same as the creator, but not always: users may delegate tasks to agents. required: false schema: type: string - name: source in: query description: Filter by run source type required: false schema: $ref: '#/components/schemas/RunSourceType' - name: execution_location in: query description: Filter by where the run executed required: false schema: $ref: '#/components/schemas/RunExecutionLocation' - name: created_after in: query description: Filter runs created after this timestamp (RFC3339 format) required: false schema: type: string format: date-time - name: created_before in: query description: Filter runs created before this timestamp (RFC3339 format) required: false schema: type: string format: date-time - name: updated_after in: query description: Filter runs updated after this timestamp (RFC3339 format) required: false schema: type: string format: date-time - name: environment_id in: query description: Filter runs by environment ID required: false schema: type: string - name: skill in: query description: | Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec. required: false schema: type: string - name: skill_spec in: query description: 'Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")' required: false schema: type: string - name: schedule_id in: query description: Filter runs by the scheduled agent ID that created them required: false schema: type: string - name: ancestor_run_id in: query description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. required: false schema: type: string - name: artifact_type in: query description: Filter runs by artifact type required: false schema: type: string enum: - PLAN - PULL_REQUEST - SCREENSHOT - FILE - name: q in: query description: 'Fuzzy search query across run title, prompt, and skill_spec' required: false schema: type: string responses: '200': description: List of runs content: application/json: schema: $ref: '#/components/schemas/ListRunsResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/runs/{runId}': get: summary: Get run details description: | Retrieve detailed information about a specific agent run, including the full prompt, session link, and resolved configuration. operationId: getRun tags: - agent security: - bearerAuth: [] parameters: - name: runId in: path description: The unique identifier of the run required: true schema: type: string responses: '200': description: Run details content: application/json: schema: $ref: '#/components/schemas/RunItem' '400': description: Missing run ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access run content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Run not found content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/runs/{runId}/timeline': get: summary: Get run timeline description: | Retrieve chronological setup and lifecycle timeline events for an agent run. operationId: getRunTimeline tags: - agent security: - bearerAuth: [] parameters: - name: runId in: path description: The unique identifier of the run required: true schema: type: string responses: '200': description: Run timeline events content: application/json: schema: $ref: '#/components/schemas/GetRunTimelineResponse' '400': description: Missing run ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access run content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/runs/{runId}/conversation': get: summary: Get normalized run conversation description: | Retrieve a run's conversation as a normalized sequence of messages and nested steps. The response groups text, tool activity, and event content into structured blocks. operationId: getRunConversation tags: - agent security: - bearerAuth: [] parameters: - name: runId in: path description: The unique identifier of the run required: true schema: type: string responses: '200': description: Normalized conversation content: application/json: schema: $ref: '#/components/schemas/ConversationResponse' '400': description: Missing run ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access run content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: 'Run not found, or the run has no conversation' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: | Conversation format is not yet supported by the normalized endpoint (error_code: operation_not_supported) content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/runs/{runId}/cancel': post: summary: Cancel a run description: | Cancel an agent run that is currently queued or in progress. Once cancelled, the run will transition to a cancelled state. Not all runs can be cancelled. Runs that are in a terminal state (SUCCEEDED, FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in PENDING state return 409 (retry after a moment). Self-hosted, local, and GitHub Action runs return 422. operationId: cancelRun tags: - agent security: - bearerAuth: [] parameters: - name: runId in: path description: The unique identifier of the run to cancel required: true schema: type: string responses: '200': description: Run cancelled successfully content: application/json: schema: type: string description: The ID of the cancelled run '400': description: | Missing run ID, or the run is already in a terminal state (error_code: invalid_request) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to cancel run content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Run not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: | Run is in PENDING state and cannot be cancelled yet. Retry after a moment (error_code: conflict, retryable: true). content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: | Run cannot be cancelled because the operation is not supported for this run type (e.g., self-hosted, local, or GitHub Action runs) (error_code: operation_not_supported) content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/runs/{runId}/followups': post: summary: Submit a follow-up message for a run description: | Send a follow-up message to an existing run. The server transparently routes the message based on the current state of the run (still queued, actively running, or ended). A 200 response means the follow-up was accepted; updated run state can be observed via `GET /agent/runs/{runId}`. operationId: submitRunFollowup tags: - agent security: - bearerAuth: [] parameters: - name: runId in: path description: The unique identifier of the run required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunFollowupRequest' responses: '200': description: Follow-up accepted content: application/json: schema: type: object '400': description: | Invalid request (e.g. no active sandbox without conversation ID, malformed payload). Empty messages are accepted when continuing a run from saved conversation context; otherwise they are rejected. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to submit follow-ups for this run content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Run not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/conversations/{conversation_id}': get: summary: Get normalized conversation description: | Retrieve a conversation directly by conversation ID in Warp's normalized task/message format. operationId: getConversation tags: - agent security: - bearerAuth: [] parameters: - name: conversation_id in: path description: The unique identifier of the conversation required: true schema: type: string responses: '200': description: Normalized conversation content: application/json: schema: $ref: '#/components/schemas/ConversationResponse' '400': description: Missing conversation ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access conversation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: | Conversation format is not yet supported by the normalized endpoint (error_code: operation_not_supported) content: application/json: schema: $ref: '#/components/schemas/Error' /agent/schedules: post: summary: Create a scheduled agent description: | Create a new scheduled agent that runs on a cron schedule. The agent will be triggered automatically based on the cron expression. operationId: createScheduledAgent tags: - schedules security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateScheduledAgentRequest' examples: simple: summary: Simple daily schedule value: name: Daily Code Review cron_schedule: 0 9 * * * prompt: Review open pull requests and provide feedback enabled: true withConfig: summary: With agent config value: name: Weekly Report cron_schedule: 0 10 * * 1 prompt: Generate weekly status report enabled: true agent_config: model_id: claude-4-6-opus-high responses: '201': description: Scheduled agent created successfully content: application/json: schema: $ref: '#/components/schemas/ScheduledAgentItem' '400': description: 'Invalid request (missing required fields, invalid cron expression)' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission or feature not available content: application/json: schema: $ref: '#/components/schemas/Error' get: summary: List scheduled agents description: | Retrieve all scheduled agents accessible to the authenticated user. Results are sorted alphabetically by name. operationId: listScheduledAgents tags: - schedules security: - bearerAuth: [] responses: '200': description: List of scheduled agents content: application/json: schema: $ref: '#/components/schemas/ListScheduledAgentsResponse' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/schedules/{scheduleId}': get: summary: Get scheduled agent details description: | Retrieve detailed information about a specific scheduled agent, including its configuration, history, and next scheduled run time. operationId: getScheduledAgent tags: - schedules security: - bearerAuth: [] parameters: - name: scheduleId in: path description: The unique identifier of the scheduled agent required: true schema: type: string responses: '200': description: Scheduled agent details content: application/json: schema: $ref: '#/components/schemas/ScheduledAgentItem' '400': description: Missing schedule ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access schedule content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Schedule not found content: application/json: schema: $ref: '#/components/schemas/Error' put: summary: Update a scheduled agent description: | Update an existing scheduled agent's configuration. All fields except agent_config are required. operationId: updateScheduledAgent tags: - schedules security: - bearerAuth: [] parameters: - name: scheduleId in: path description: The unique identifier of the scheduled agent required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateScheduledAgentRequest' responses: '200': description: Scheduled agent updated successfully content: application/json: schema: $ref: '#/components/schemas/ScheduledAgentItem' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to update schedule content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Schedule not found content: application/json: schema: $ref: '#/components/schemas/Error' delete: summary: Delete a scheduled agent description: | Delete a scheduled agent. This will stop all future scheduled runs. operationId: deleteScheduledAgent tags: - schedules security: - bearerAuth: [] parameters: - name: scheduleId in: path description: The unique identifier of the scheduled agent required: true schema: type: string responses: '200': description: Scheduled agent deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteScheduledAgentResponse' '401': description: Authentication 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: - name: sort_by in: query required: false description: | Sort order for the returned environments. - `name`: alphabetical by environment name - `last_updated`: most recently updated first (default) schema: type: string enum: - name - last_updated default: last_updated responses: '200': description: List of accessible environments content: application/json: schema: $ref: '#/components/schemas/ListEnvironmentsResponse' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /agent/models: get: summary: List available models description: | Retrieve the list of LLM models available to the authenticated user for agent runs. The response includes which model is the default, as well as per-model metadata such as provider, cost, and whether the model is currently disabled (and why). operationId: listModels tags: - agent security: - bearerAuth: [] responses: '200': description: List of available models content: application/json: schema: $ref: '#/components/schemas/ListModelsResponse' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/artifacts/{artifactUid}': get: summary: Get artifact details description: | Retrieve an artifact by its UUID. For downloadable file-like artifacts, returns a time-limited signed download URL. For plan artifacts, returns the current plan content inline. operationId: getArtifact tags: - agent security: - bearerAuth: [] parameters: - name: artifactUid in: path description: The unique identifier (UUID) of the artifact required: true schema: type: string responses: '200': description: Artifact details with download information content: application/json: schema: $ref: '#/components/schemas/ArtifactResponse' '400': description: Missing artifact UID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No permission to access artifact content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Artifact not found or unsupported artifact type content: application/json: schema: $ref: '#/components/schemas/Error' /harness-support/transcript: get: summary: Download the raw third-party harness transcript description: | Redirects to a signed download URL for the raw third-party harness transcript (e.g. `claude_code.json`) of the current task's conversation. Only supported for conversations produced by non-Oz harnesses; Oz conversations 400. This may only be called from within a cloud agent execution environment whose task already has an associated conversation (e.g. on a resumed run). operationId: getTranscriptDownload tags: - harness-support security: - bearerAuth: [] responses: '307': description: Redirect to a signed download URL for the transcript '400': description: 'Task has no conversation, or conversation format does not support transcript downloads' 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 the conversation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Conversation or transcript not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /agent/identities: post: summary: Create an agent description: | Create a new agent for the caller's team. Agents can be used as the execution principal for team-owned runs. operationId: createAgent tags: - agent security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' responses: '201': description: Agent created successfully content: application/json: schema: $ref: '#/components/schemas/AgentResponse' '400': description: 'Invalid request (empty name, user on multiple teams, or on no team)' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 'Only human users can manage agents, or plan limit exceeded' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' get: summary: List agents description: | List all agents for the caller's team. Each agent includes an `available` flag indicating whether it is within the team's plan limit and may be used for runs. operationId: listAgents tags: - agent security: - bearerAuth: [] responses: '200': description: List of agents content: application/json: schema: $ref: '#/components/schemas/ListAgentIdentitiesResponse' '400': description: 'User on multiple teams, or on no team' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Only human users can list agents content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '/agent/identities/{uid}': get: summary: Retrieve an agent description: | Retrieve a single agent by its unique identifier. The response includes an `available` flag indicating whether the agent is within the team's plan limit and may be used for runs. operationId: getAgent tags: - agent security: - bearerAuth: [] parameters: - name: uid in: path description: The unique identifier of the agent required: true schema: type: string responses: '200': 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. 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. 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. interactive: type: boolean description: | Whether the run should be interactive. If not set, defaults to false. 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 is_sandbox_running: type: boolean description: Whether the sandbox environment is currently running 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. 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_finished - oz_run_failure 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' discriminator: propertyName: artifact_type mapping: PLAN: '#/components/schemas/PlanArtifact' PULL_REQUEST: '#/components/schemas/PullRequestArtifact' SCREENSHOT: '#/components/schemas/ScreenshotArtifact' FILE: '#/components/schemas/FileArtifact' 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 filename: type: string description: Last path component of filepath 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. RequestUsage: type: object description: Resource usage information for the run properties: inference_cost: type: number format: double description: Cost of LLM inference for the run compute_cost: type: number format: double description: Cost of compute resources for the run platform_cost: type: number format: double description: Cost of platform usage for the run 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 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 RunExecutionLocation: type: string enum: - LOCAL - REMOTE description: | Where the run executed: - LOCAL: Executed in the user's local Oz 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 skill_spec: type: string description: | Skill specification identifying the primary agent skill to use. Format: "{owner}/{repo}:{skill_path}" Example: "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 false. 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. SessionSharingConfig: type: object description: | Configures sharing behavior for the run's shared session. When set, the worker emits `--share public:` and the bundled Warp client applies an anyone-with-link ACL to the shared session once it has bootstrapped. The same ACL is mirrored onto the backing conversation so link viewers can read the conversation 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. - VIEWER: link viewers can read the session and conversation. - EDITOR: link viewers can also interact with the session. Anonymous (unauthenticated) reads are not supported in this release; link viewers must still be authenticated Warp users. Harness: type: object description: | Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness. 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 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 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). Includes backward-compatible extension members. The response uses the `application/problem+json` content type. Additional extension members (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 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 - filepath - 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 filename: type: string description: Last path component of filepath 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 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. 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' 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' 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' 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. 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. 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_stores: type: array items: $ref: '#/components/schemas/MemoryStoreRef' description: | Optional list of memory stores to attach to the agent. Each store must be team-owned by the same team as the agent. Duplicate UIDs within a single request are rejected. base_harness: type: string nullable: true description: | Optional default harness for runs executed by this agent. 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. 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. 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_stores: type: array nullable: true items: $ref: '#/components/schemas/MemoryStoreRef' description: | Replacement list of memory stores. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. inference_providers: type: object allOf: - $ref: '#/components/schemas/InferenceProvidersConfig' nullable: true description: | Replacement inference provider settings for this agent. Agent-level config takes precedence over the workspace's admin-configured defaults. Omit or pass `null` to leave unchanged. Pass an empty object `{}` to clear. base_harness: type: string nullable: true description: | Replacement default harness. Omit or pass `null` to leave unchanged, or pass an empty string to clear. 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. AgentResponse: type: object required: - uid - name - available - created_at - updated_at - secrets - skills - memory_stores 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 available: type: boolean description: Whether this agent is within the team's plan limit and can be used for runs 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_stores: type: array items: $ref: '#/components/schemas/MemoryStoreRef' description: | Memory stores attached to this agent. Always present; empty when no stores are attached. base_harness: type: string 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. Oz 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. 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'