# Agent
Operations for running and managing cloud agents
## List available agents
> Retrieve a list of available agents (skills) that can be used to run tasks.\
> Agents are discovered from environments or a specific repository.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"ListAgentsResponse":{"type":"object","required":["agents"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentListItem"},"description":"List of available agents"}}},"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.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\n"},"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.\nContains a description of the parse failure. Only present when\ninclude_malformed_skills=true is passed to the list agents endpoint.\n"}}},"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.\nPresent only for skills discovered from self-hosted workers\n(as opposed to skills from GitHub repos linked to environments).\n"}}},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent":{"get":{"summary":"List available agents","description":"Retrieve a list of available agents (skills) that can be used to run tasks.\nAgents are discovered from environments or a specific repository.\n","operationId":"listAgents","tags":["agent"],"parameters":[{"name":"repo","in":"query","description":"Optional repository specification to list agents from (format: \"owner/repo\").\nIf not provided, lists agents from all accessible environments.\n","required":false,"schema":{"type":"string"}},{"name":"refresh","in":"query","description":"When true, clears the agent list cache before fetching.\nUse this to force a refresh of the available agents.\n","required":false,"schema":{"type":"boolean","default":false}},{"name":"sort_by","in":"query","description":"Sort order for the returned agents.\n- \"name\": Sort alphabetically by name (default)\n- \"last_run\": Sort by most recently used\n","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\nmalformed. These variants will have a non-empty `error` field\ndescribing the parse failure. Defaults to false.\n","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"}}}}}}}}}
```
## Get run transcript
> Retrieve the raw conversation transcript for an agent run.\
> Returns a 302 redirect to a time-limited download URL for the transcript.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/runs/{runId}/transcript":{"get":{"summary":"Get run transcript","description":"Retrieve the raw conversation transcript for an agent run.\nReturns a 302 redirect to a time-limited download URL for the transcript.\n","operationId":"getRunTranscript","tags":["agent"],"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"}}}}}}}}}
```
## Run an agent task
> Spawn a cloud agent with a prompt and optional configuration.\
> The agent will be queued for execution and assigned a unique run ID.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"RunAgentRequest":{"type":"object","description":"Request body for creating a new agent run.\nEither prompt or skill (via skill field or config.skill_spec) is required.\n","properties":{"prompt":{"type":"string","description":"The prompt/instruction for the agent to execute.\nRequired unless a skill is specified via the skill field or config.skill_spec.\n"},"skill":{"type":"string","description":"Skill specification to use as the base prompt for the agent.\nSupported formats:\n - \"repo:skill_name\" - Simple name in specific repo\n - \"repo:skill_path\" - Full path in specific repo\n - \"org/repo:skill_name\" - Simple name with org and repo\n - \"org/repo:skill_path\" - Full path with org and repo\nWhen provided, this takes precedence over config.skill_spec.\n"},"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.\nDefaults to true for users on a single team.\n"},"agent_identity_uid":{"type":"string","description":"Optional agent identity UID to use as the execution principal for the run.\nThis is only valid for runs that are team owned. \n"},"conversation_id":{"type":"string","description":"Optional conversation ID to continue an existing conversation.\nIf provided, the agent will continue from where the previous run left off.\n"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentInput"},"description":"Optional file attachments to include with the prompt (max 5).\nAttachments are uploaded to cloud storage and made available to the agent.\n"},"parent_run_id":{"type":"string","description":"Optional run ID of the parent that spawned this run.\nUsed for orchestration hierarchies.\n"},"interactive":{"type":"boolean","description":"Whether the run should be interactive.\nIf not set, defaults to false.\n"}}},"AmbientAgentConfig":{"type":"object","description":"Configuration for a cloud agent run","properties":{"name":{"type":"string","description":"Human-readable label for grouping, filtering, and traceability.\nAutomatically set to the skill name when running a skill-based agent.\nSet this explicitly to categorize runs by intent (e.g., \"nightly-dependency-check\")\nso you can filter and track them via the name query parameter on GET /agent/runs.\n"},"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 which agent skill to use.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\nUse the list agents endpoint to discover available skills.\n"},"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.\nIf not set, defaults to false.\n"},"idle_timeout_minutes":{"type":"integer","format":"int32","minimum":1,"maximum":60,"description":"Number of minutes to keep the agent environment alive after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n"},"worker_host":{"type":"string","description":"Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n"},"harness":{"$ref":"#/components/schemas/Harness"},"harness_auth_secrets":{"$ref":"#/components/schemas/HarnessAuthSecrets"},"session_sharing":{"$ref":"#/components/schemas/SessionSharingConfig"}}},"MCPServerConfig":{"type":"object","description":"Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.\n","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"}}},"Harness":{"type":"object","description":"Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\n","properties":{"type":{"type":"string","enum":["oz","claude","gemini"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code harness\n- gemini: Gemini CLI harness\n"}}},"HarnessAuthSecrets":{"type":"object","description":"Authentication secrets for third-party harnesses.\nOnly the secret for the harness specified gets injected into the environment.\n","properties":{"claude_auth_secret_name":{"type":"string","description":"Name of a managed secret for Claude Code harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"claude\".\n"}}},"SessionSharingConfig":{"type":"object","description":"Configures sharing behavior for the run's shared session.\nWhen set, the worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it has\nbootstrapped. The same ACL is mirrored onto the backing conversation so\nlink viewers can read the conversation without being on the run's team.\nSubject to the workspace-level anyone-with-link sharing setting.\n","properties":{"public_access":{"type":"string","enum":["VIEWER","EDITOR"],"description":"Grants anyone-with-link access at the specified level to the run's\nshared session and backing conversation.\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\nAnonymous (unauthenticated) reads are not supported in this release;\nlink viewers must still be authenticated Warp users.\n"}}},"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.\nSupported image types: image/jpeg, image/png, image/gif, image/webp\n"},"data":{"type":"string","format":"byte","description":"Base64-encoded attachment data"}}},"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"}}},"RunState":{"type":"string","enum":["QUEUED","PENDING","CLAIMED","INPROGRESS","SUCCEEDED","FAILED","BLOCKED","ERROR","CANCELLED"],"description":"Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n"},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/run":{"post":{"summary":"Run an agent task","description":"Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n","operationId":"runAgent","tags":["agent"],"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"}}}}}}}}}
```
## List agent runs
> Retrieve a paginated list of agent runs with optional filtering.\
> Results default to \`sort\_by=updated\_at\` and \`sort\_order=desc\`.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"RunState":{"type":"string","enum":["QUEUED","PENDING","CLAIMED","INPROGRESS","SUCCEEDED","FAILED","BLOCKED","ERROR","CANCELLED"],"description":"Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n"},"RunSourceType":{"type":"string","enum":["LINEAR","API","SLACK","LOCAL","SCHEDULED_AGENT","WEB_APP","GITHUB_ACTION","CLOUD_MODE","CLI"],"description":"Source that created the run:\n- LINEAR: Created from Linear integration\n- API: Created via the Warp API\n- SLACK: Created from Slack integration\n- LOCAL: Created from local CLI/app\n- SCHEDULED_AGENT: Created by a scheduled agent\n- WEB_APP: Created from the Warp web app\n- GITHUB_ACTION: Created from a GitHub action\n- CLOUD_MODE: Created from a Cloud Mode\n- CLI: Created from the CLI\n"},"RunExecutionLocation":{"type":"string","enum":["LOCAL","REMOTE"],"description":"Where the run executed:\n- LOCAL: Executed in the user's local Oz environment\n- REMOTE: Executed by a remote/cloud worker\n"},"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)"},"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"},"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"}}},"RunStatusMessage":{"type":"object","description":"Status message for a run. For terminal error states, includes structured\nerror code and retryability info from the platform error catalog.\n","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\na new run. Only present on terminal error states. When false, retrying\nwithout addressing the underlying cause will not succeed.\n"}}},"PlatformErrorCode":{"type":"string","description":"Machine-readable error code identifying the problem type.\nUsed in the `type` URI of Error responses and in the `error_code`\nfield of RunStatusMessage.\n\nUser errors (run transitions to FAILED):\n- `insufficient_credits` — Team has no remaining add-on credits\n- `feature_not_available` — Required feature not enabled for user's plan\n- `external_authentication_required` — User hasn't authorized a required external service\n- `not_authorized` — Principal lacks permission for the requested operation\n- `invalid_request` — Request is malformed or contains invalid parameters\n- `resource_not_found` — Referenced resource does not exist\n- `budget_exceeded` — Spending budget limit has been reached\n- `integration_disabled` — Integration is disabled and must be enabled\n- `integration_not_configured` — Integration setup is incomplete\n- `operation_not_supported` — Requested operation not supported for this resource/state\n- `environment_setup_failed` — Client-side environment setup failed\n- `content_policy_violation` — Prompt or setup commands violated content policy\n- `conflict` — Request conflicts with the current state of the resource\n\nWarp errors (run transitions to ERROR):\n- `authentication_required` — Request lacks valid authentication credentials\n- `resource_unavailable` — Transient infrastructure issue (retryable)\n- `internal_error` — Unexpected server-side error (retryable)\n","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"]},"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"}}},"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"}}},"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"}}},"AmbientAgentConfig":{"type":"object","description":"Configuration for a cloud agent run","properties":{"name":{"type":"string","description":"Human-readable label for grouping, filtering, and traceability.\nAutomatically set to the skill name when running a skill-based agent.\nSet this explicitly to categorize runs by intent (e.g., \"nightly-dependency-check\")\nso you can filter and track them via the name query parameter on GET /agent/runs.\n"},"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 which agent skill to use.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\nUse the list agents endpoint to discover available skills.\n"},"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.\nIf not set, defaults to false.\n"},"idle_timeout_minutes":{"type":"integer","format":"int32","minimum":1,"maximum":60,"description":"Number of minutes to keep the agent environment alive after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n"},"worker_host":{"type":"string","description":"Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n"},"harness":{"$ref":"#/components/schemas/Harness"},"harness_auth_secrets":{"$ref":"#/components/schemas/HarnessAuthSecrets"},"session_sharing":{"$ref":"#/components/schemas/SessionSharingConfig"}}},"MCPServerConfig":{"type":"object","description":"Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.\n","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"}}},"Harness":{"type":"object","description":"Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\n","properties":{"type":{"type":"string","enum":["oz","claude","gemini"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code harness\n- gemini: Gemini CLI harness\n"}}},"HarnessAuthSecrets":{"type":"object","description":"Authentication secrets for third-party harnesses.\nOnly the secret for the harness specified gets injected into the environment.\n","properties":{"claude_auth_secret_name":{"type":"string","description":"Name of a managed secret for Claude Code harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"claude\".\n"}}},"SessionSharingConfig":{"type":"object","description":"Configures sharing behavior for the run's shared session.\nWhen set, the worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it has\nbootstrapped. The same ACL is mirrored onto the backing conversation so\nlink viewers can read the conversation without being on the run's team.\nSubject to the workspace-level anyone-with-link sharing setting.\n","properties":{"public_access":{"type":"string","enum":["VIEWER","EDITOR"],"description":"Grants anyone-with-link access at the specified level to the run's\nshared session and backing conversation.\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\nAnonymous (unauthenticated) reads are not supported in this release;\nlink viewers must still be authenticated Warp users.\n"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"AgentSkill":{"type":"object","description":"Information about the agent skill used for the run.\nEither full_path or bundled_skill_id will be set, but not both.\n","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"}}},"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"}}},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/runs":{"get":{"summary":"List agent runs","description":"Retrieve a paginated list of agent runs with optional filtering.\nResults default to `sort_by=updated_at` and `sort_order=desc`.\n","operationId":"listRuns","tags":["agent"],"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.\n- `updated_at`: Sort by last update timestamp (default)\n- `created_at`: Sort by creation timestamp\n- `title`: Sort alphabetically by run title\n- `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.\n","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.\n","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":"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\").\nAlias for skill_spec.\n","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"}}}}}}}}}
```
## Run an agent task (preferred)
> Alias for POST /agent/run. This is the preferred endpoint for creating\
> new agent runs. Behavior is identical to POST /agent/run.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"RunAgentRequest":{"type":"object","description":"Request body for creating a new agent run.\nEither prompt or skill (via skill field or config.skill_spec) is required.\n","properties":{"prompt":{"type":"string","description":"The prompt/instruction for the agent to execute.\nRequired unless a skill is specified via the skill field or config.skill_spec.\n"},"skill":{"type":"string","description":"Skill specification to use as the base prompt for the agent.\nSupported formats:\n - \"repo:skill_name\" - Simple name in specific repo\n - \"repo:skill_path\" - Full path in specific repo\n - \"org/repo:skill_name\" - Simple name with org and repo\n - \"org/repo:skill_path\" - Full path with org and repo\nWhen provided, this takes precedence over config.skill_spec.\n"},"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.\nDefaults to true for users on a single team.\n"},"agent_identity_uid":{"type":"string","description":"Optional agent identity UID to use as the execution principal for the run.\nThis is only valid for runs that are team owned. \n"},"conversation_id":{"type":"string","description":"Optional conversation ID to continue an existing conversation.\nIf provided, the agent will continue from where the previous run left off.\n"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentInput"},"description":"Optional file attachments to include with the prompt (max 5).\nAttachments are uploaded to cloud storage and made available to the agent.\n"},"parent_run_id":{"type":"string","description":"Optional run ID of the parent that spawned this run.\nUsed for orchestration hierarchies.\n"},"interactive":{"type":"boolean","description":"Whether the run should be interactive.\nIf not set, defaults to false.\n"}}},"AmbientAgentConfig":{"type":"object","description":"Configuration for a cloud agent run","properties":{"name":{"type":"string","description":"Human-readable label for grouping, filtering, and traceability.\nAutomatically set to the skill name when running a skill-based agent.\nSet this explicitly to categorize runs by intent (e.g., \"nightly-dependency-check\")\nso you can filter and track them via the name query parameter on GET /agent/runs.\n"},"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 which agent skill to use.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\nUse the list agents endpoint to discover available skills.\n"},"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.\nIf not set, defaults to false.\n"},"idle_timeout_minutes":{"type":"integer","format":"int32","minimum":1,"maximum":60,"description":"Number of minutes to keep the agent environment alive after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n"},"worker_host":{"type":"string","description":"Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n"},"harness":{"$ref":"#/components/schemas/Harness"},"harness_auth_secrets":{"$ref":"#/components/schemas/HarnessAuthSecrets"},"session_sharing":{"$ref":"#/components/schemas/SessionSharingConfig"}}},"MCPServerConfig":{"type":"object","description":"Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.\n","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"}}},"Harness":{"type":"object","description":"Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\n","properties":{"type":{"type":"string","enum":["oz","claude","gemini"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code harness\n- gemini: Gemini CLI harness\n"}}},"HarnessAuthSecrets":{"type":"object","description":"Authentication secrets for third-party harnesses.\nOnly the secret for the harness specified gets injected into the environment.\n","properties":{"claude_auth_secret_name":{"type":"string","description":"Name of a managed secret for Claude Code harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"claude\".\n"}}},"SessionSharingConfig":{"type":"object","description":"Configures sharing behavior for the run's shared session.\nWhen set, the worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it has\nbootstrapped. The same ACL is mirrored onto the backing conversation so\nlink viewers can read the conversation without being on the run's team.\nSubject to the workspace-level anyone-with-link sharing setting.\n","properties":{"public_access":{"type":"string","enum":["VIEWER","EDITOR"],"description":"Grants anyone-with-link access at the specified level to the run's\nshared session and backing conversation.\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\nAnonymous (unauthenticated) reads are not supported in this release;\nlink viewers must still be authenticated Warp users.\n"}}},"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.\nSupported image types: image/jpeg, image/png, image/gif, image/webp\n"},"data":{"type":"string","format":"byte","description":"Base64-encoded attachment data"}}},"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"}}},"RunState":{"type":"string","enum":["QUEUED","PENDING","CLAIMED","INPROGRESS","SUCCEEDED","FAILED","BLOCKED","ERROR","CANCELLED"],"description":"Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n"},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/runs":{"post":{"summary":"Run an agent task (preferred)","description":"Alias for POST /agent/run. This is the preferred endpoint for creating\nnew agent runs. Behavior is identical to POST /agent/run.\n","operationId":"createRun","tags":["agent"],"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 run details
> Retrieve detailed information about a specific agent run, \
> including the full prompt, session link, and resolved configuration.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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)"},"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"},"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"}}},"RunState":{"type":"string","enum":["QUEUED","PENDING","CLAIMED","INPROGRESS","SUCCEEDED","FAILED","BLOCKED","ERROR","CANCELLED"],"description":"Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n"},"RunExecutionLocation":{"type":"string","enum":["LOCAL","REMOTE"],"description":"Where the run executed:\n- LOCAL: Executed in the user's local Oz environment\n- REMOTE: Executed by a remote/cloud worker\n"},"RunStatusMessage":{"type":"object","description":"Status message for a run. For terminal error states, includes structured\nerror code and retryability info from the platform error catalog.\n","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\na new run. Only present on terminal error states. When false, retrying\nwithout addressing the underlying cause will not succeed.\n"}}},"PlatformErrorCode":{"type":"string","description":"Machine-readable error code identifying the problem type.\nUsed in the `type` URI of Error responses and in the `error_code`\nfield of RunStatusMessage.\n\nUser errors (run transitions to FAILED):\n- `insufficient_credits` — Team has no remaining add-on credits\n- `feature_not_available` — Required feature not enabled for user's plan\n- `external_authentication_required` — User hasn't authorized a required external service\n- `not_authorized` — Principal lacks permission for the requested operation\n- `invalid_request` — Request is malformed or contains invalid parameters\n- `resource_not_found` — Referenced resource does not exist\n- `budget_exceeded` — Spending budget limit has been reached\n- `integration_disabled` — Integration is disabled and must be enabled\n- `integration_not_configured` — Integration setup is incomplete\n- `operation_not_supported` — Requested operation not supported for this resource/state\n- `environment_setup_failed` — Client-side environment setup failed\n- `content_policy_violation` — Prompt or setup commands violated content policy\n- `conflict` — Request conflicts with the current state of the resource\n\nWarp errors (run transitions to ERROR):\n- `authentication_required` — Request lacks valid authentication credentials\n- `resource_unavailable` — Transient infrastructure issue (retryable)\n- `internal_error` — Unexpected server-side error (retryable)\n","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"]},"RunSourceType":{"type":"string","enum":["LINEAR","API","SLACK","LOCAL","SCHEDULED_AGENT","WEB_APP","GITHUB_ACTION","CLOUD_MODE","CLI"],"description":"Source that created the run:\n- LINEAR: Created from Linear integration\n- API: Created via the Warp API\n- SLACK: Created from Slack integration\n- LOCAL: Created from local CLI/app\n- SCHEDULED_AGENT: Created by a scheduled agent\n- WEB_APP: Created from the Warp web app\n- GITHUB_ACTION: Created from a GitHub action\n- CLOUD_MODE: Created from a Cloud Mode\n- CLI: Created from the CLI\n"},"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"}}},"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"}}},"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"}}},"AmbientAgentConfig":{"type":"object","description":"Configuration for a cloud agent run","properties":{"name":{"type":"string","description":"Human-readable label for grouping, filtering, and traceability.\nAutomatically set to the skill name when running a skill-based agent.\nSet this explicitly to categorize runs by intent (e.g., \"nightly-dependency-check\")\nso you can filter and track them via the name query parameter on GET /agent/runs.\n"},"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 which agent skill to use.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\nUse the list agents endpoint to discover available skills.\n"},"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.\nIf not set, defaults to false.\n"},"idle_timeout_minutes":{"type":"integer","format":"int32","minimum":1,"maximum":60,"description":"Number of minutes to keep the agent environment alive after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n"},"worker_host":{"type":"string","description":"Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n"},"harness":{"$ref":"#/components/schemas/Harness"},"harness_auth_secrets":{"$ref":"#/components/schemas/HarnessAuthSecrets"},"session_sharing":{"$ref":"#/components/schemas/SessionSharingConfig"}}},"MCPServerConfig":{"type":"object","description":"Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.\n","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"}}},"Harness":{"type":"object","description":"Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\n","properties":{"type":{"type":"string","enum":["oz","claude","gemini"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code harness\n- gemini: Gemini CLI harness\n"}}},"HarnessAuthSecrets":{"type":"object","description":"Authentication secrets for third-party harnesses.\nOnly the secret for the harness specified gets injected into the environment.\n","properties":{"claude_auth_secret_name":{"type":"string","description":"Name of a managed secret for Claude Code harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"claude\".\n"}}},"SessionSharingConfig":{"type":"object","description":"Configures sharing behavior for the run's shared session.\nWhen set, the worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it has\nbootstrapped. The same ACL is mirrored onto the backing conversation so\nlink viewers can read the conversation without being on the run's team.\nSubject to the workspace-level anyone-with-link sharing setting.\n","properties":{"public_access":{"type":"string","enum":["VIEWER","EDITOR"],"description":"Grants anyone-with-link access at the specified level to the run's\nshared session and backing conversation.\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\nAnonymous (unauthenticated) reads are not supported in this release;\nlink viewers must still be authenticated Warp users.\n"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}},"AgentSkill":{"type":"object","description":"Information about the agent skill used for the run.\nEither full_path or bundled_skill_id will be set, but not both.\n","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"}}},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/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"],"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"}}}}}}}}}
```
## Get normalized run conversation
> 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.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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"}}},"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."}}},"ActionCategory":{"type":"string","description":"High-level category of an action performed during the conversation","enum":["command","files","search","integration","documents","computer","review","skill"]},"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."}}},"ActionState":{"type":"string","description":"State of an action result","enum":["running","completed","failed","denied"]},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/runs/{runId}/conversation":{"get":{"summary":"Get normalized run conversation","description":"Retrieve a run's conversation as a normalized sequence of messages and\nnested steps.\nThe response groups text, tool activity, and event content into\nstructured blocks.\n","operationId":"getRunConversation","tags":["agent"],"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\n(error_code: operation_not_supported)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Cancel a run
> 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.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/runs/{runId}/cancel":{"post":{"summary":"Cancel a run","description":"Cancel an agent run that is currently queued or in progress.\nOnce cancelled, the run will transition to a cancelled state.\n\nNot all runs can be cancelled. Runs that are in a terminal state\n(SUCCEEDED, FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in\nPENDING state return 409 (retry after a moment). Self-hosted, local,\nand GitHub Action runs return 422.\n","operationId":"cancelRun","tags":["agent"],"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\n(error_code: invalid_request)\n","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.\nRetry after a moment (error_code: conflict, retryable: true).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Run cannot be cancelled because the operation is not supported\nfor this run type (e.g., self-hosted, local, or GitHub Action runs)\n(error_code: operation_not_supported)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get normalized conversation
> Retrieve a conversation directly by conversation ID in Warp's\
> normalized task/message format.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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"}}},"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."}}},"ActionCategory":{"type":"string","description":"High-level category of an action performed during the conversation","enum":["command","files","search","integration","documents","computer","review","skill"]},"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."}}},"ActionState":{"type":"string","description":"State of an action result","enum":["running","completed","failed","denied"]},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/conversations/{conversation_id}":{"get":{"summary":"Get normalized conversation","description":"Retrieve a conversation directly by conversation ID in Warp's\nnormalized task/message format.\n","operationId":"getConversation","tags":["agent"],"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\n(error_code: operation_not_supported)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## List available models
> 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).
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/models":{"get":{"summary":"List available models","description":"Retrieve the list of LLM models available to the authenticated user for\nagent runs. The response includes which model is the default, as well as\nper-model metadata such as provider, cost, and whether the model is\ncurrently disabled (and why).\n","operationId":"listModels","tags":["agent"],"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"}}}}}}}}}
```
## Get artifact details
> 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.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/artifacts/{artifactUid}":{"get":{"summary":"Get artifact details","description":"Retrieve an artifact by its UUID. For downloadable file-like artifacts,\nreturns a time-limited signed download URL. For plan artifacts, returns\nthe current plan content inline.\n","operationId":"getArtifact","tags":["agent"],"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"}}}}}}}}}
```
## Get session redirect
> Check whether a shared session should redirect to a conversation transcript.\
> Returns a conversation\_id if the agent sandbox has finished and conversation\
> data is available, or an empty object if no redirect is needed.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"agent","description":"Operations for running and managing cloud agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"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.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/sessions/{sessionUuid}/redirect":{"get":{"summary":"Get session redirect","description":"Check whether a shared session should redirect to a conversation transcript.\nReturns a conversation_id if the agent sandbox has finished and conversation\ndata is available, or an empty object if no redirect is needed.\n","operationId":"getSessionRedirect","tags":["agent"],"parameters":[{"name":"sessionUuid","in":"path","description":"The UUID of the shared session","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Redirect information. Contains conversation_id if redirect is needed,\notherwise an empty object.\n","content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"string","description":"The conversation ID to redirect to (only present when redirect is needed)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.warp.dev/reference/api-and-sdk/agent.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.