# 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"}}},"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"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code 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"}}},"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"}}},"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"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code 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"}}},"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"}}},"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"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code 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"}}},"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"}}},"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"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code 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"}}},"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"}}},"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"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code 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"}}},"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"}}},"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"],"description":"The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code 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"}}},"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"}}}}}}}}}
```