Schedules API

{
  id: string                 // composite `${source}:${sourceScheduleId}` — opaque to the UI
  sourceScheduleId: string   // the raw id inside the owning system
  runtime: string            // runtime the schedule targets ('openclaw' | 'clawboo-native' | …)
  owner: string              // = scheduledBy: which engine FIRES it ('clawboo' | 'openclaw' | …)
  source: 'clawboo-routine' | 'openclaw-gateway-cron'
  agentId: string            // the agent a fire runs on; '' for a team routine
  target?: 'team' | 'agent'  // Routine rows: who a fire goes to
  teamId?: string | null     // Routine rows: the team whose chat or board receives a fire
  teamName?: string          // display names resolved at read time; for a team routine,
  agentName?: string         //   agentName (and runtime) are the team's current lead's
  teamTaskId?: string        // set only for Routine rows bound to an existing board task
  label?: string
  description?: string       // Routine rows: the instructions each fire carries
  cronSpec: string           // a cron expression, `once@<iso>`, `every:<ms>[@anchor:<ms>]`, or `at:<iso>`
  nextRunAt: number | null   // epoch ms; null when disarmed / will never fire again
  lastRunAt?: number
  lastError?: string
  status: 'queued' | 'claimed' | 'running' | 'idle' | 'paused' | 'error'
  manageability: 'managed' | 'external-write' | 'observe-only'
  domain: 'team-task' | 'runtime-own-life'
  tenantId: string | null    // dormant multi-tenant seam — always null today
}

{
  schedules: ScheduleRecord[]
  sources: Array<{
    sourceId: 'clawboo-routine' | 'openclaw-gateway-cron'
    ok: boolean
    degraded: boolean
    reason?: string   // e.g. 'gateway_disconnected' | 'stale_cache'
    at: number        // epoch ms of this read
  }>
}

curl http://localhost:18790/api/schedules

{
  source: 'clawboo-routine' | 'openclaw-gateway-cron'   // required
  domain: 'team-task' | 'runtime-own-life'              // required
  cronSpec: string                                      // required
  target?: 'team' | 'agent'    // Routine rows: who a fire goes to (default 'agent')
  agentId?: string             // required unless target is 'team'
  teamId?: string | null       // required for a team routine; must match the agent's team otherwise
  label?: string
  teamTaskId?: string | null   // agent routines: bind to an existing board task (the ownership-guard site)
  taskTemplate?: unknown       // Routine rows: the ledger task-template object (validated by the source)
  payload?: unknown            // Gateway rows: the cron payload (e.g. { kind: 'agentTurn', message })
  tenantId?: string | null     // dormant multi-tenant seam
}

{
  schedule: ScheduleRecord
}

{
  "error": "source, domain, cronSpec, and an agentId (or a teamId for a team routine) are required",
  "code": "invalid_body"
}

{ "error": "Invalid cron spec \"* * *\": ...", "code": "invalid_cron_spec" }

{
  "error": "A recurring schedule (\"0 9 * * *\") cannot bind to existing team task <id> — a bound task is claimable once, so use a one-shot (once@<iso>) spec",
  "code": "bound_recurring_schedule"
}

{ "error": "\"Ada\" is not on that team.", "code": "invalid_routine_target" }

{ "error": "invalid task template", "code": "invalid_body" }

{
  "error": "Schedule source \"<id>\" (observe-only) does not support \"create\"",
  "code": "unsupported_schedule_write"
}

{ "error": "Unknown schedule \"<create>\"", "code": "unknown_schedule" }

{
  "error": "Already scheduled by \"<owner>\" (team task <id>) — never retry this refusal",
  "code": "duplicate_firing_owner"
}

{
  "error": "A team-task schedule cannot be registered into \"openclaw-gateway-cron\" — team-task cadence belongs to the Routines ledger",
  "code": "team_task_domain_violation"
}

{ "error": "gateway_disconnected", "code": "schedule_source_unavailable" }

{ "error": "<message>" }

# A team routine: post to the team chat every weekday at 9am
curl -X POST http://localhost:18790/api/schedules \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "clawboo-routine",
    "domain": "team-task",
    "target": "team",
    "teamId": "<team-id>",
    "cronSpec": "0 9 * * 1-5",
    "label": "Daily standup digest",
    "taskTemplate": { "description": "Summarize what the team finished yesterday." }
  }'

# An agent routine: a daily task for one agent
curl -X POST http://localhost:18790/api/schedules \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "clawboo-routine",
    "domain": "team-task",
    "target": "agent",
    "agentId": "<agent-id>",
    "cronSpec": "0 9 * * *",
    "label": "Inbox sweep",
    "taskTemplate": { "description": "Check the support inbox and draft replies to anything urgent." }
  }'

{
  action: 'pause' | 'resume'
}

{
  patch: {
    cronSpec?: string
    label?: string
    taskTemplate?: unknown        // Routine rows (e.g. { description } for new instructions)
    target?: 'team' | 'agent'     // Routine rows: re-point the routine
    agentId?: string | null       // Routine rows
    teamId?: string | null        // Routine rows
    payload?: unknown             // Gateway rows
  }
}

{
  schedule: ScheduleRecord | null
}

{ "error": "body needs { action: 'pause' | 'resume' } or { patch }", "code": "invalid_body" }

{ "error": "Invalid cron spec \"...\": ...", "code": "invalid_cron_spec" }

{
  "error": "Schedule source \"<id>\" (observe-only) does not support \"pause\"",
  "code": "unsupported_schedule_write"
}

{ "error": "Unknown schedule \"<id>\"", "code": "unknown_schedule" }

{ "error": "Illegal schedule transition error → idle", "code": "illegal_schedule_transition" }

{ "error": "gateway_disconnected", "code": "schedule_source_unavailable" }

{ "error": "<message>" }

# Pause a Routine
curl -X PATCH http://localhost:18790/api/schedules/clawboo-routine:<row-id> \
  -H 'Content-Type: application/json' \
  -d '{"action":"pause"}'

# Change its cron spec
curl -X PATCH http://localhost:18790/api/schedules/clawboo-routine:<row-id> \
  -H 'Content-Type: application/json' \
  -d '{"patch":{"cronSpec":"0 8 * * 1-5"}}'

# Turn it into a team routine for another team
curl -X PATCH http://localhost:18790/api/schedules/clawboo-routine:<row-id> \
  -H 'Content-Type: application/json' \
  -d '{"patch":{"target":"team","teamId":"<team-id>","agentId":null}}'

{ "ok": true }

{
  "error": "Schedule source \"<id>\" (observe-only) does not support \"remove\"",
  "code": "unsupported_schedule_write"
}

{ "error": "Unknown schedule \"<id>\"", "code": "unknown_schedule" }

{ "error": "gateway_disconnected", "code": "schedule_source_unavailable" }

{ "error": "<message>" }

curl -X DELETE http://localhost:18790/api/schedules/openclaw-gateway-cron:<job-id>

{ "ok": true }

{
  "error": "Schedule source \"<id>\" (observe-only) does not support \"run\"",
  "code": "unsupported_schedule_write"
}

{ "error": "Unknown schedule \"<id>\"", "code": "unknown_schedule" }

{ "error": "Illegal schedule transition <status> → queued", "code": "illegal_schedule_transition" }

{ "error": "gateway_disconnected", "code": "schedule_source_unavailable" }

{ "error": "<message>" }

curl -X POST http://localhost:18790/api/schedules/clawboo-routine:<row-id>/run

{
  runs: Array<{
    firedAt: number // epoch ms of the claim
    finishedAt: number | null // when the outcome was recorded
    status: 'running' | 'succeeded' | 'failed' | 'interrupted'
    error: string | null // the failure, for a failed fire
    taskId: string | null // the board task an agent fire created; null for a team fire
    dispatchPath: string | null // 'team-chat' | 'one-shot' | 'connected'
    targetAgentId: string | null // a team fire's recipient: the lead the message went to
    task: { id: string; title: string; status: string } | null
  }>
}

{ "error": "Unknown schedule \"<id>\"", "code": "unknown_schedule" }

{ "error": "<message>" }

curl 'http://localhost:18790/api/schedules/clawboo-routine:<row-id>/runs?limit=5'