WAwarp
AgentsScheduled Agents

Create a scheduled agent

Changed on

Create a new scheduled agent that runs on a cron schedule. The agent will be triggered automatically based on the cron expression.

post/agent/schedules

Request

  • Base URL
    https://app.warp.dev/api/v1
  • Auth
    HTTP bearer

Headers

X-Warp-Team-Uidstring

UID of the team to use as the request's active team. Ignored for service-account callers, which always act as their bound team.

Request body

namestring required

Human-readable name for the schedule

cron_schedulestring required

Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)

promptstring

The prompt/instruction for the agent to execute. Required unless agent_config.skill_spec or agent_config.skills is provided.

mode'normal' | 'plan' | 'orchestrate'

Query mode for an agent run.

  • normal: Standard user query (default).
  • plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.
  • orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
enabledboolean

Whether the schedule should be active immediately

agent_uidstring uuid

Agent UID to use as the execution principal for this schedule. Only valid for team-owned schedules.

teamboolean

Whether to create a team-owned schedule. Defaults to true for users on a single team.

metadataRunMetadata

Custom key/value metadata attached to a run at creation time and immutable afterward; at most 20 keys, with keys 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with no NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).

Response

Scheduled agent created successfully

idstring required

Unique identifier for the scheduled agent

namestring required

Human-readable name for the schedule

cron_schedulestring required

Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)

enabledboolean required

Whether the schedule is currently active

promptstring required

The prompt/instruction for the agent to execute

last_spawn_errorstring nullable

Error message from the last failed spawn attempt, if any

agent_uidstring uuid

UID of the agent that this schedule runs as

metadataRunMetadata

Custom key/value metadata attached to a run at creation time and immutable afterward; at most 20 keys, with keys 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with no NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).

created_atstring date-time required

Timestamp when the schedule was created (RFC3339)

updated_atstring date-time required

Timestamp when the schedule was last updated (RFC3339)

Changes

  • 2c45dcc0a13eRevision changes
    • breaking

      the request property / became not nullable

    • breaking

      removed the enum value CREATOR of the request property /

    • breaking

      removed the enum value EXECUTOR of the request property /

    • breaking

      removed the enum value claude of the request property //

    • breaking

      removed the enum value codex of the request property //

    • breaking

      removed the enum value gemini of the request property //

    • breaking

      removed the enum value oz of the request property //

    • breaking

      the // request property type changed from string to no type

    • breaking

      response property agent_config/credential_strategy list-of-types was widened by adding types null to media type application/json of response 201

    • breaking

      added subschema #1 to the // response property oneOf list for the response status

    • breaking

      the // response's property type changed from string to no type for status

    • info

      added the new optional request property //

    • info

      request property / list-of-types was widened by adding types null to media type application/json

    • info

      added subschema #1 to the // request property oneOf list

    • info

      added the optional property // to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      removed the CREATOR enum value from the / response property for the response status

    • info

      removed the EXECUTOR enum value from the / response property for the response status

    • info

      removed the claude enum value from the // response property for the response status

    • info

      removed the codex enum value from the // response property for the response status

    • info

      removed the gemini enum value from the // response property for the response status

    • info

      removed the oz enum value from the // response property for the response status

  • 96d1e59a65c5Revision changes
    • info

      added the new optional request property /

    • info

      added the optional property / to the response with the status

    • info

      added the optional property ///// to the response with the status