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.

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.

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

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)