# Schedules
Operations for creating and managing scheduled agents
## List scheduled agents
> Retrieve all scheduled agents accessible to the authenticated user.\
> Results are sorted alphabetically by name.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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:` 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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules":{"get":{"summary":"List scheduled agents","description":"Retrieve all scheduled agents accessible to the authenticated user.\nResults are sorted alphabetically by name.\n","operationId":"listScheduledAgents","tags":["schedules"],"responses":{"200":{"description":"List of scheduled agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListScheduledAgentsResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Create a scheduled agent
> Create a new scheduled agent that runs on a cron schedule.\
> The agent will be triggered automatically based on the cron expression.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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:` 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"}}},"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"}}},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules":{"post":{"summary":"Create a scheduled agent","description":"Create a new scheduled agent that runs on a cron schedule.\nThe agent will be triggered automatically based on the cron expression.\n","operationId":"createScheduledAgent","tags":["schedules"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScheduledAgentRequest"}}}},"responses":{"201":{"description":"Scheduled agent created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledAgentItem"}}}},"400":{"description":"Invalid request (missing required fields, invalid cron expression)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission or feature not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get scheduled agent details
> Retrieve detailed information about a specific scheduled agent,\
> including its configuration, history, and next scheduled run time.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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:` 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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules/{scheduleId}":{"get":{"summary":"Get scheduled agent details","description":"Retrieve detailed information about a specific scheduled agent,\nincluding its configuration, history, and next scheduled run time.\n","operationId":"getScheduledAgent","tags":["schedules"],"parameters":[{"name":"scheduleId","in":"path","description":"The unique identifier of the scheduled agent","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scheduled agent details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledAgentItem"}}}},"400":{"description":"Missing schedule ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to access schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Update a scheduled agent
> Update an existing scheduled agent's configuration.\
> All fields except agent\_config are required.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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:` 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"}}},"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"}}},"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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules/{scheduleId}":{"put":{"summary":"Update a scheduled agent","description":"Update an existing scheduled agent's configuration.\nAll fields except agent_config are required.\n","operationId":"updateScheduledAgent","tags":["schedules"],"parameters":[{"name":"scheduleId","in":"path","description":"The unique identifier of the scheduled agent","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateScheduledAgentRequest"}}}},"responses":{"200":{"description":"Scheduled agent updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledAgentItem"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to update schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Delete a scheduled agent
> Delete a scheduled agent. This will stop all future scheduled runs.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"DeleteScheduledAgentResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Whether the deletion was successful"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules/{scheduleId}":{"delete":{"summary":"Delete a scheduled agent","description":"Delete a scheduled agent. This will stop all future scheduled runs.\n","operationId":"deleteScheduledAgent","tags":["schedules"],"parameters":[{"name":"scheduleId","in":"path","description":"The unique identifier of the scheduled agent","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scheduled agent deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteScheduledAgentResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to delete schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Pause a scheduled agent
> Pause a scheduled agent. The agent will not run until resumed.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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:` 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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules/{scheduleId}/pause":{"post":{"summary":"Pause a scheduled agent","description":"Pause a scheduled agent. The agent will not run until resumed.\n","operationId":"pauseScheduledAgent","tags":["schedules"],"parameters":[{"name":"scheduleId","in":"path","description":"The unique identifier of the scheduled agent","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scheduled agent paused successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledAgentItem"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to pause schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Resume a scheduled agent
> Resume a paused scheduled agent. The agent will start running\
> according to its cron schedule.
```json
{"openapi":"3.0.0","info":{"title":"Oz Agent API","version":"1.0.0"},"tags":[{"name":"schedules","description":"Operations for creating and managing scheduled agents"}],"servers":[{"url":"https://app.warp.dev/api/v1","description":"Warp Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authentication via a Warp API key.\n"}},"schemas":{"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:` 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"}}},"Error":{"type":"object","description":"Error response following RFC 7807 (Problem Details for HTTP APIs).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n","required":["type","title","status","error"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n"},"title":{"type":"string","description":"A short, human-readable summary of the problem type (RFC 7807)"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem (RFC 7807)"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem (RFC 7807)"},"instance":{"type":"string","description":"The request path that generated this error (RFC 7807)"},"error":{"type":"string","description":"Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n"},"retryable":{"type":"boolean","description":"Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n"},"trace_id":{"type":"string","description":"OpenTelemetry trace ID for debugging and support requests"}}}}},"paths":{"/agent/schedules/{scheduleId}/resume":{"post":{"summary":"Resume a scheduled agent","description":"Resume a paused scheduled agent. The agent will start running\naccording to its cron schedule.\n","operationId":"resumeScheduledAgent","tags":["schedules"],"parameters":[{"name":"scheduleId","in":"path","description":"The unique identifier of the scheduled agent","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scheduled agent resumed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledAgentItem"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No permission to resume schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent 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/schedules.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.