# Models

## The RunAgentRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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:<level>` 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"}}}}}}
```

## The RunAgentResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The ListRunsResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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:<level>` 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"}}}}}}
```

## The RunItem object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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:<level>` 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"}}}}}}
```

## The ConversationResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ConversationStep object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ConversationMessage object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ConversationMessageRole object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ConversationMessageRole":{"type":"string","description":"Role of the normalized message","enum":["user","assistant","tool","system"]}}}}
```

## The ConversationContentBlock object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The TextContentBlock object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ActionCategory object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ActionCategory":{"type":"string","description":"High-level category of an action performed during the conversation","enum":["command","files","search","integration","documents","computer","review","skill"]}}}}
```

## The ActionState object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ActionState":{"type":"string","description":"State of an action result","enum":["running","completed","failed","denied"]}}}}
```

## The ActionContentBlock object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"]}}}}
```

## The ActionResultContentBlock object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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."}}},"ActionCategory":{"type":"string","description":"High-level category of an action performed during the conversation","enum":["command","files","search","integration","documents","computer","review","skill"]},"ActionState":{"type":"string","description":"State of an action result","enum":["running","completed","failed","denied"]}}}}
```

## The EventContentBlock object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ArtifactItem object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The PlanArtifact object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The PullRequestArtifact object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ScreenshotArtifact object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The FileArtifact object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The PlanArtifactData object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The PullRequestArtifactData object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ScreenshotArtifactData object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The FileArtifactData object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ScheduleInfo object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The PageInfo object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The RunStatusMessage object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"]}}}}
```

## The RequestUsage object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The RunCreatorInfo object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The RunState object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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"}}}}
```

## The RunSourceType object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The RunExecutionLocation object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The AmbientAgentConfig object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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:<level>` 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"}}}}}}
```

## The Harness object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The MCPServerConfig object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The Error object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ArtifactResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ScreenshotArtifactResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ScreenshotArtifactResponseData object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The FileArtifactResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The FileArtifactResponseData object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The AttachmentInput object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ScheduledAgentItem object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ScheduledAgentItem":{"type":"object","required":["id","name","cron_schedule","enabled","prompt","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Unique identifier for the scheduled agent"},"name":{"type":"string","description":"Human-readable name for the schedule"},"cron_schedule":{"type":"string","description":"Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)"},"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"prompt":{"type":"string","description":"The prompt/instruction for the agent to execute"},"last_spawn_error":{"type":"string","nullable":true,"description":"Error message from the last failed spawn attempt, if any"},"agent_config":{"$ref":"#/components/schemas/AmbientAgentConfig"},"environment":{"allOf":[{"$ref":"#/components/schemas/CloudEnvironmentConfig"}],"description":"Resolved environment configuration (if agent_config references an environment_id)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the schedule was created (RFC3339)"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the schedule was last updated (RFC3339)"},"created_by":{"$ref":"#/components/schemas/RunCreatorInfo"},"updated_by":{"$ref":"#/components/schemas/RunCreatorInfo"},"history":{"$ref":"#/components/schemas/ScheduledAgentHistoryItem"},"scope":{"$ref":"#/components/schemas/Scope"}}},"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:<level>` 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"}}},"CloudEnvironmentConfig":{"type":"object","description":"Configuration for a cloud environment used by scheduled agents","properties":{"name":{"type":"string","description":"Human-readable name for the environment"},"description":{"type":"string","nullable":true,"description":"Optional description of the environment"},"docker_image":{"type":"string","description":"Docker image to use (e.g., \"ubuntu:latest\" or \"registry/repo:tag\")"},"github_repos":{"type":"array","items":{"$ref":"#/components/schemas/GitHubRepo"},"description":"List of GitHub repositories to clone into the environment"},"setup_commands":{"type":"array","items":{"type":"string"},"description":"Shell commands to run during environment setup"},"providers":{"$ref":"#/components/schemas/ProvidersConfig"}}},"GitHubRepo":{"type":"object","required":["owner","repo"],"properties":{"owner":{"type":"string","description":"GitHub repository owner (user or organization)"},"repo":{"type":"string","description":"GitHub repository name"}}},"ProvidersConfig":{"type":"object","description":"Optional cloud provider configurations for automatic auth","properties":{"gcp":{"$ref":"#/components/schemas/GcpProviderConfig"},"aws":{"$ref":"#/components/schemas/AwsProviderConfig"}}},"GcpProviderConfig":{"type":"object","description":"GCP Workload Identity Federation settings","required":["project_number","workload_identity_federation_pool_id","workload_identity_federation_provider_id"],"properties":{"project_number":{"type":"string","description":"GCP project number"},"workload_identity_federation_pool_id":{"type":"string","description":"Workload Identity Federation pool ID"},"workload_identity_federation_provider_id":{"type":"string","description":"Workload Identity Federation provider ID"}}},"AwsProviderConfig":{"type":"object","description":"AWS IAM role assumption settings","required":["role_arn"],"properties":{"role_arn":{"type":"string","description":"AWS IAM role ARN to assume"}}},"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"}}},"ScheduledAgentHistoryItem":{"type":"object","description":"Scheduler-derived history metadata for a scheduled agent","properties":{"last_ran":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the last successful run (RFC3339)"},"next_run":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the next scheduled run (RFC3339)"}}},"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"}}}}}}
```

## The ScheduledAgentHistoryItem object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ScheduledAgentHistoryItem":{"type":"object","description":"Scheduler-derived history metadata for a scheduled agent","properties":{"last_ran":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the last successful run (RFC3339)"},"next_run":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the next scheduled run (RFC3339)"}}}}}}
```

## The CreateScheduledAgentRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"CreateScheduledAgentRequest":{"type":"object","description":"Request body for creating a new scheduled agent.\nEither prompt or agent_config.skill_spec is required.\n","required":["name","cron_schedule"],"properties":{"name":{"type":"string","description":"Human-readable name for the schedule"},"cron_schedule":{"type":"string","description":"Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)"},"prompt":{"type":"string","description":"The prompt/instruction for the agent to execute.\nRequired unless agent_config.skill_spec is provided.\n"},"enabled":{"type":"boolean","description":"Whether the schedule should be active immediately","default":true},"agent_config":{"$ref":"#/components/schemas/AmbientAgentConfig"},"team":{"type":"boolean","description":"Whether to create a team-owned schedule.\nDefaults to true for users on a single team.\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:<level>` 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"}}}}}}
```

## The UpdateScheduledAgentRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"UpdateScheduledAgentRequest":{"type":"object","description":"Request body for updating a scheduled agent.\nEither prompt or agent_config.skill_spec is required.\n","required":["name","cron_schedule","enabled"],"properties":{"name":{"type":"string","description":"Human-readable name for the schedule"},"cron_schedule":{"type":"string","description":"Cron expression defining when the agent runs"},"prompt":{"type":"string","description":"The prompt/instruction for the agent to execute.\nRequired unless agent_config.skill_spec is provided.\n"},"enabled":{"type":"boolean","description":"Whether the schedule should be active"},"agent_config":{"$ref":"#/components/schemas/AmbientAgentConfig"}}},"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:<level>` 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"}}}}}}
```

## The ListScheduledAgentsResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ListScheduledAgentsResponse":{"type":"object","required":["schedules"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/ScheduledAgentItem"},"description":"List of scheduled agents"}}},"ScheduledAgentItem":{"type":"object","required":["id","name","cron_schedule","enabled","prompt","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Unique identifier for the scheduled agent"},"name":{"type":"string","description":"Human-readable name for the schedule"},"cron_schedule":{"type":"string","description":"Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)"},"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"prompt":{"type":"string","description":"The prompt/instruction for the agent to execute"},"last_spawn_error":{"type":"string","nullable":true,"description":"Error message from the last failed spawn attempt, if any"},"agent_config":{"$ref":"#/components/schemas/AmbientAgentConfig"},"environment":{"allOf":[{"$ref":"#/components/schemas/CloudEnvironmentConfig"}],"description":"Resolved environment configuration (if agent_config references an environment_id)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the schedule was created (RFC3339)"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the schedule was last updated (RFC3339)"},"created_by":{"$ref":"#/components/schemas/RunCreatorInfo"},"updated_by":{"$ref":"#/components/schemas/RunCreatorInfo"},"history":{"$ref":"#/components/schemas/ScheduledAgentHistoryItem"},"scope":{"$ref":"#/components/schemas/Scope"}}},"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:<level>` 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"}}},"CloudEnvironmentConfig":{"type":"object","description":"Configuration for a cloud environment used by scheduled agents","properties":{"name":{"type":"string","description":"Human-readable name for the environment"},"description":{"type":"string","nullable":true,"description":"Optional description of the environment"},"docker_image":{"type":"string","description":"Docker image to use (e.g., \"ubuntu:latest\" or \"registry/repo:tag\")"},"github_repos":{"type":"array","items":{"$ref":"#/components/schemas/GitHubRepo"},"description":"List of GitHub repositories to clone into the environment"},"setup_commands":{"type":"array","items":{"type":"string"},"description":"Shell commands to run during environment setup"},"providers":{"$ref":"#/components/schemas/ProvidersConfig"}}},"GitHubRepo":{"type":"object","required":["owner","repo"],"properties":{"owner":{"type":"string","description":"GitHub repository owner (user or organization)"},"repo":{"type":"string","description":"GitHub repository name"}}},"ProvidersConfig":{"type":"object","description":"Optional cloud provider configurations for automatic auth","properties":{"gcp":{"$ref":"#/components/schemas/GcpProviderConfig"},"aws":{"$ref":"#/components/schemas/AwsProviderConfig"}}},"GcpProviderConfig":{"type":"object","description":"GCP Workload Identity Federation settings","required":["project_number","workload_identity_federation_pool_id","workload_identity_federation_provider_id"],"properties":{"project_number":{"type":"string","description":"GCP project number"},"workload_identity_federation_pool_id":{"type":"string","description":"Workload Identity Federation pool ID"},"workload_identity_federation_provider_id":{"type":"string","description":"Workload Identity Federation provider ID"}}},"AwsProviderConfig":{"type":"object","description":"AWS IAM role assumption settings","required":["role_arn"],"properties":{"role_arn":{"type":"string","description":"AWS IAM role ARN to assume"}}},"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"}}},"ScheduledAgentHistoryItem":{"type":"object","description":"Scheduler-derived history metadata for a scheduled agent","properties":{"last_ran":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the last successful run (RFC3339)"},"next_run":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the next scheduled run (RFC3339)"}}},"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"}}}}}}
```

## The DeleteScheduledAgentResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"DeleteScheduledAgentResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Whether the deletion was successful"}}}}}}
```

## The CloudEnvironmentConfig object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"CloudEnvironmentConfig":{"type":"object","description":"Configuration for a cloud environment used by scheduled agents","properties":{"name":{"type":"string","description":"Human-readable name for the environment"},"description":{"type":"string","nullable":true,"description":"Optional description of the environment"},"docker_image":{"type":"string","description":"Docker image to use (e.g., \"ubuntu:latest\" or \"registry/repo:tag\")"},"github_repos":{"type":"array","items":{"$ref":"#/components/schemas/GitHubRepo"},"description":"List of GitHub repositories to clone into the environment"},"setup_commands":{"type":"array","items":{"type":"string"},"description":"Shell commands to run during environment setup"},"providers":{"$ref":"#/components/schemas/ProvidersConfig"}}},"GitHubRepo":{"type":"object","required":["owner","repo"],"properties":{"owner":{"type":"string","description":"GitHub repository owner (user or organization)"},"repo":{"type":"string","description":"GitHub repository name"}}},"ProvidersConfig":{"type":"object","description":"Optional cloud provider configurations for automatic auth","properties":{"gcp":{"$ref":"#/components/schemas/GcpProviderConfig"},"aws":{"$ref":"#/components/schemas/AwsProviderConfig"}}},"GcpProviderConfig":{"type":"object","description":"GCP Workload Identity Federation settings","required":["project_number","workload_identity_federation_pool_id","workload_identity_federation_provider_id"],"properties":{"project_number":{"type":"string","description":"GCP project number"},"workload_identity_federation_pool_id":{"type":"string","description":"Workload Identity Federation pool ID"},"workload_identity_federation_provider_id":{"type":"string","description":"Workload Identity Federation provider ID"}}},"AwsProviderConfig":{"type":"object","description":"AWS IAM role assumption settings","required":["role_arn"],"properties":{"role_arn":{"type":"string","description":"AWS IAM role ARN to assume"}}}}}}
```

## The ProvidersConfig object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ProvidersConfig":{"type":"object","description":"Optional cloud provider configurations for automatic auth","properties":{"gcp":{"$ref":"#/components/schemas/GcpProviderConfig"},"aws":{"$ref":"#/components/schemas/AwsProviderConfig"}}},"GcpProviderConfig":{"type":"object","description":"GCP Workload Identity Federation settings","required":["project_number","workload_identity_federation_pool_id","workload_identity_federation_provider_id"],"properties":{"project_number":{"type":"string","description":"GCP project number"},"workload_identity_federation_pool_id":{"type":"string","description":"Workload Identity Federation pool ID"},"workload_identity_federation_provider_id":{"type":"string","description":"Workload Identity Federation provider ID"}}},"AwsProviderConfig":{"type":"object","description":"AWS IAM role assumption settings","required":["role_arn"],"properties":{"role_arn":{"type":"string","description":"AWS IAM role ARN to assume"}}}}}}
```

## The GcpProviderConfig object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"GcpProviderConfig":{"type":"object","description":"GCP Workload Identity Federation settings","required":["project_number","workload_identity_federation_pool_id","workload_identity_federation_provider_id"],"properties":{"project_number":{"type":"string","description":"GCP project number"},"workload_identity_federation_pool_id":{"type":"string","description":"Workload Identity Federation pool ID"},"workload_identity_federation_provider_id":{"type":"string","description":"Workload Identity Federation provider ID"}}}}}}
```

## The AwsProviderConfig object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"AwsProviderConfig":{"type":"object","description":"AWS IAM role assumption settings","required":["role_arn"],"properties":{"role_arn":{"type":"string","description":"AWS IAM role ARN to assume"}}}}}}
```

## The GitHubRepo object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"GitHubRepo":{"type":"object","required":["owner","repo"],"properties":{"owner":{"type":"string","description":"GitHub repository owner (user or organization)"},"repo":{"type":"string","description":"GitHub repository name"}}}}}}
```

## The ListAgentsResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The AgentListItem object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The AgentListVariant object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The AgentListSource object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The AgentListEnvironment object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The Scope object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The PlatformErrorCode object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"]}}}}
```

## The CreateExternalConversationRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"CreateExternalConversationRequest":{"type":"object","description":"Request body for creating a new external conversation for a third-party harness.","required":["format"],"properties":{"format":{"type":"string","description":"The conversation format identifying the harness type.\n"}}}}}}
```

## The CreateExternalConversationResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"CreateExternalConversationResponse":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"The unique identifier of the newly created conversation."}}}}}}
```

## The ResolvePromptRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ResolvePromptRequest":{"type":"object","description":"Request body for resolving the effective prompt for a task.","properties":{"skill":{"type":"object","description":"Optional skill metadata to prepend to the prompt.","required":["name","content"],"properties":{"name":{"type":"string","description":"Human-readable name of the skill"},"content":{"type":"string","description":"The resolved skill content"},"path":{"type":"string","description":"Full path to SKILL.md (optional)"}}},"attachments_dir":{"type":"string","description":"Directory where attachments were downloaded locally"}}}}}}
```

## The ResolvePromptResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ResolvePromptResponse":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"The resolved prompt"},"system_prompt":{"type":"string","description":"Optional system prompt addition for the harness"}}}}}}
```

## The GetUploadTargetRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"GetUploadTargetRequest":{"type":"object","description":"Request body for obtaining a conversation-scoped upload target.","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","description":"The conversation ID to associate the uploaded data with."}}}}}}
```

## The UploadTarget object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"UploadTarget":{"type":"object","description":"A description of where and how to upload a blob.\nUse the `method` and `url` to upload, including all `headers` in the request.\nPass the blob to upload as the request body.\n","required":["url","method","headers"],"properties":{"url":{"type":"string","format":"uri","description":"The presigned URL to upload the blob to."},"method":{"type":"string","enum":["PUT","POST"],"description":"The HTTP method to use for the upload."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers that must be included in the upload request."}}}}}}
```

## The ListModelsResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ModelInfo object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ReportArtifactRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ReportArtifactRequest":{"oneOf":[{"$ref":"#/components/schemas/ReportPullRequestArtifactRequest"}],"discriminator":{"propertyName":"artifact_type","mapping":{"PULL_REQUEST":"#/components/schemas/ReportPullRequestArtifactRequest"}}},"ReportPullRequestArtifactRequest":{"type":"object","description":"Request body for reporting a pull request artifact.","required":["artifact_type","data"],"properties":{"artifact_type":{"type":"string","enum":["PULL_REQUEST"],"description":"Type of artifact being reported."},"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"}}}}}}
```

## The ReportPullRequestArtifactRequest object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ReportPullRequestArtifactRequest":{"type":"object","description":"Request body for reporting a pull request artifact.","required":["artifact_type","data"],"properties":{"artifact_type":{"type":"string","enum":["PULL_REQUEST"],"description":"Type of artifact being reported."},"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"}}}}}}
```

## The ReportArtifactResponse object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"ReportArtifactResponse":{"type":"object","required":["artifact_uid"],"properties":{"artifact_uid":{"type":"string","description":"Unique identifier for the created artifact"}}}}}}
```

## The AgentSkill object

```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```


---

# 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/models.md?ask=<question>
```

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.