code.
Team work and the runtimes’ own jobs stay separate. A Routine schedules team work on any runtime: a message to a team’s lead (a team routine) or a board task for one agent (an agent routine). A Gateway cron job schedules an OpenClaw agent’s own work, and a Hermes job a Hermes agent’s own work. Clawboo never puts team work into the Gateway’s cron or Hermes’s scheduler, and never creates jobs there by itself; the Routines view shows them and lets you change them.
id of the form <source>:<rawId>: clawboo-routine:<routine-id>, openclaw-gateway-cron:<gateway-job-id> or hermes-gateway-jobs:<profile>.<job-id>. The :id path segment is URL-decoded and sent to the source it names; an id that matches no source answers 404. Request bodies are JSON (up to 2 MB). Every route here is on the general rate limit (3,000 requests a minute per client address). Add the access cookie to each curl example (see Authentication).
Routes
The ScheduleRecord shape
Every source describes its schedules in one shape. It is the element type of schedules[] on GET, and the schedule returned by a create, change, pause or resume.
domain says what a schedule is for: team-task is team work that Clawboo schedules (Routines), and runtime-own-life is an agent’s own job in its runtime’s scheduler (the OpenClaw Gateway’s cron, or Hermes’s). manageability says who owns it: managed means Clawboo owns and runs it, external-write means the runtime owns and runs it and Clawboo changes it through the runtime’s API, and observe-only (no source uses it today) would be read-only.
A team routine stores no agent (agentId is ''). Every answer that returns a schedule (the list, the occurrences route, and a create, change, pause or resume) fills in teamName and agentName, and for a team routine takes agentName and runtime from the team’s current lead. An agent routine whose agent is gone reads runtime: 'unknown'.
Claude Code, Codex and Clawboo Native have no scheduler of their own; scheduling any of them is a Routine. So is team work on OpenClaw and Hermes.
GET /api/schedules
Every schedule from every source, with each one’s teamName and agentName filled in. A team routine stores no agent, so it reports the team’s current lead (the agent its next run would reach) as agentName and runtime. A source that fails or is disconnected does not fail the request: it adds a degraded entry to sources[]. A Gateway cron list read earlier is served from its cache; with no cache, its jobs are absent until the Gateway reconnects. Hermes jobs work the same way while the Hermes gateway is not running, and a read never starts it. This route always answers 200.
- Path/query params: none.
- Request body: none.
Responses
200 OK: the schedules plus one status entry per source:
{ ok: true, degraded: false }. When its Gateway connection is down, the Gateway cron source reports { ok: false, degraded: true, reason: 'gateway_disconnected' } with no cache, or reason: 'stale_cache' when it serves cached jobs. With no Gateway set up at all it reports reason: 'not_configured' and no jobs. With a Gateway set up that nothing uses yet, so the server has not connected to it (see How Clawboo connects), it reports reason: 'not_in_use' and no jobs. When the Hermes gateway is not running, the Hermes jobs source reports reason: 'gateway_stopped' with no cache, or 'stale_cache'; a profile it could not read while the gateway runs makes it degraded with reason: 'profile_unreadable', and that profile’s jobs are left out. With no Hermes agents, or no Hermes that Clawboo installed, it reports { ok: false, degraded: false, reason: 'not_configured' } and no jobs.
Example
POST /api/schedules
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Creates a schedule in the source named by source. Before the source is touched, two checks run in order: a read-only (observe-only) source answers 403, and a domain: 'team-task' create aimed at the Gateway cron or Hermes’s jobs answers 422 (both sources refuse it too). The source then runs its own checks.
For a clawboo-routine create, the cron spec is checked (a spec that does not parse is a 400), and the Routine’s task template is built from label, taskTemplate and target. The template’s title defaults to label (or Scheduled team task), and its description is the instructions each run carries. The target is checked too:
- A team routine (
target: 'team') needs ateamIdnaming a live, unarchived team. Its runs are posted into that team’s chat for the team’s lead, so it stores no agent (agentIdis ignored and reads back as''), and it cannot bind ateamTaskId. - An agent routine (
target: 'agent', the default) needs anagentIdnaming a live, unarchived agent, and is filed on that agent’s team. AteamIdis optional; when sent, it must match the agent’s team (nullfor an agent on no team).
code: "invalid_routine_target". A recurring spec bound to an existing teamTaskId is refused too: a bound task can be claimed only once, so a recurring run would park the Routine in error. Bind only one-shot once@<iso> specs. Binding a task that another engine already schedules is the 409 duplicate_firing_owner refusal.
For an openclaw-gateway-cron create, Clawboo calls the Gateway’s cron.add with the job’s payload (default { kind: 'agentTurn', message: label }, with 'Scheduled wake' when there is no label) and the session target that payload needs: main for a systemEvent, isolated for anything else. The Gateway accepts a mismatched pair but then skips every run, so Clawboo always picks the pair itself.
For a hermes-gateway-jobs create, agentId must name a Clawboo Hermes agent. Clawboo creates the job in that agent’s Hermes profile with label as its name (Scheduled job without one), the schedule, and a prompt from payload.prompt, else payload.message, else label; a job with no prompt is refused. Hermes takes a cron expression without a time zone (it runs jobs in its own zone), an interval in whole minutes, or one time. The job saves its output in the profile (deliver: local), since Hermes’s chat channels are off. A write starts the Hermes gateway when it is not running.
- Path/query params: none.
- Request body: a
ScheduleCreateSpec.source,domainandcronSpecare required, plus ateamIdfor a team routine or anagentIdfor anything else:
Responses
201 Created: the schedule was created:
400 Bad Request: a required field is missing, source, domain or target is unknown, or a source check failed. code is invalid_body for the shape check or an invalid task template; invalid_cron_spec for a cron spec that does not parse; invalid_routine_target for a target that does not check out, or a Hermes job Hermes cannot take (no prompt, a time zone, an interval that is not whole minutes, an agent not on Hermes, or a job Hermes refused); and bound_recurring_schedule for a recurring spec bound to an existing task. Messages on this page that contain an em dash show it as the JSON escape \u2014:
403 Forbidden: the target source is observe-only (no source is today, but the check exists):
404 Not Found: the teamTaskId you bound names no board task:
409 Conflict: the bound teamTaskId is already scheduled by another engine. Treat it as data and do not retry:
422 Unprocessable Entity: a domain: 'team-task' create was aimed at the Gateway cron or Hermes’s jobs:
503 Service Unavailable: the target is the Gateway cron and Clawboo’s Gateway connection is down, or the target is Hermes’s jobs and the Hermes gateway does not answer:
500 Internal Server Error: any other error:
Example
PATCH /api/schedules/:id
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Pauses or resumes a schedule, or changes its cron spec, label, task template, payload or target. The body takes one of two shapes; a body with neither is a 400, and a body with both runs action and ignores patch. The change goes to the source named in :id.
For a Routine:
- Pause and resume follow the table below. A paused Routine does not run until you resume it.
- A cron spec change recomputes
nextRunAtfor anidleRoutine and sets it tonullfor any other. A paused or errored Routine gets a newnextRunAtwhen you resume it. - A change to
target,agentIdorteamIdpoints the Routine somewhere else, and the new target is checked exactly as on create. AtargetinsidetaskTemplatecounts as one too. - A
teamTaskIdinside a template change is ignored: a Routine binds to a board task only when it is created, where the check for another engine runs.
Pausing a paused Routine changes nothing, and resuming an idle one only recomputes its
nextRunAt; both answer 200. Resuming a queued Routine is a 409.
For a Gateway cron job:
- Pause and resume become the Gateway’s
cron.update { id, patch: { enabled } }(the Gateway has no separate enable method). - A change becomes
cron.update { id, patch }with the changedlabel(as the job’s name),cronSpecandpayload; the Routine-only fields are ignored. A changedpayloadcarries the session target it needs, as on create. - The job id is not checked by Clawboo. It goes to the Gateway as is. When the Gateway has no job with that id, the answer is 404
unknown_schedule; any other Gateway error answers 500 with the Gateway’s message. The same holds for delete and run.
-
Pause and resume become Hermes’s
POST .../jobs/<job-id>/pauseand/resumeon the agent’s profile. -
A change sends the changed
label(as the job’s name),cronSpecand prompt (payload.prompt, elsepayload.message) to Hermes as aPATCHon the job, with the same schedule rules as on create. A change that setstarget,teamIdortaskTemplate, or names anotheragentId, is refused with 400invalid_routine_target: a Hermes job stays with its agent and runs a prompt. A job’s model, provider or folder cannot be changed through the API. -
The id is checked first. It must be
<profile>.<job-id>with a 12-character hex job id, for a profile that belongs to a Clawboo Hermes agent; otherwise the answer is 404unknown_schedule, as it is when Hermes has no such job. A change Hermes refuses answers 400invalid_routine_target. The same holds for delete and run. -
Path params:
id(composite schedule id). - Request body: one of:
Responses
200 OK: the schedule was changed; the updated record is returned. A Gateway or Hermes job can come back as schedule: null when it cannot be read back right after the change:
400 Bad Request: the body is neither a valid action nor a patch object, a changed cronSpec does not parse (invalid_cron_spec), the template is invalid, or a changed target does not check out (invalid_routine_target):
403 Forbidden: the target source is observe-only:
404 Not Found: :id matches no source, or names a Routine, Gateway job or Hermes job that does not exist:
409 Conflict: the pause or resume is not allowed from the Routine’s current status:
503 Service Unavailable: the target is a Gateway job and Clawboo’s Gateway connection is down, or a Hermes job and the Hermes gateway does not answer:
500 Internal Server Error: any other error:
Example
DELETE /api/schedules/:id
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Removes a schedule: a Routine is deleted from Clawboo’s database, a Gateway job is removed with the Gateway’s cron.remove, and a Hermes job with a DELETE on the job in Hermes.
- Path params:
id(composite schedule id). - Request body: none.
Responses
200 OK: the schedule was removed:
403 Forbidden: the target source is observe-only:
404 Not Found: :id matches no source, or names a Routine, Gateway job or Hermes job that does not exist:
503 Service Unavailable: the target is a Gateway job and Clawboo’s Gateway connection is down, or a Hermes job and the Hermes gateway does not answer:
500 Internal Server Error: any other error:
Example
POST /api/schedules/:id/run
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Runs a schedule now. The answer only says the run was queued; it does not wait for the run. A Routine moves to queued and Clawboo’s scheduler picks it up at once; a Gateway job gets the Gateway’s cron.run { id, mode: 'force' }; a Hermes job gets Hermes’s /run, and Hermes runs it at its next scheduler tick, within a minute (a paused job is resumed by it). Only an idle Routine can be queued: a paused, errored, queued, claimed or running one answers 409. So does one a pause holds back, in words that say what is paused. Follow the result in the Routine’s run history (GET /api/schedules/:id/runs), the event log, or OpenClaw’s own cron history.
- Path params:
id(composite schedule id). - Request body: none.
Responses
202 Accepted: the run was queued:
403 Forbidden: the target source is observe-only:
404 Not Found: :id matches no source, or names a Routine, Gateway job or Hermes job that does not exist:
409 Conflict: the Routine is not idle:
503 Service Unavailable: the target is a Gateway job and Clawboo’s Gateway connection is down, or a Hermes job and the Hermes gateway does not answer:
500 Internal Server Error: any other error:
Example
GET /api/schedules/:id/runs
A Routine’s recent runs, newest first, built from the Routine’s events in the event log. An agent routine’s run carries the board task it created, with that task’s current title and status. The Gateway and Hermes keep their own run history, so a Gateway or Hermes job id returns an empty list.
- Path params:
id(composite schedule id). - Query params:
limit(optional, default10, kept between 1 and 50). - Request body: none.
Responses
200 OK:
interrupted when it never recorded an outcome: the next run began without one, or the Routine is no longer queued, claimed or running. Either way the server stopped during that run. A team routine’s run succeeded once the lead’s turn started; the team’s work then continues in the chat. A run reads paused when a pause stopped it: it counts as neither a run nor a failure, error says why, and the routine runs again on resume.
404 Not Found: :id is not a composite schedule id, or names no Routine:
500 Internal Server Error: any other error:
Example
GET /api/schedules/occurrences
The upcoming runs of Clawboo’s own Routines, counted per time window you name. The board’s calendar sends the viewer’s local midnights, so each window is one day; that keeps a 23- or 25-hour day around a clock change correct. The count is worked out on the server because the scheduler reads cron in the scheduler time zone (GET /api/schedules/time-zone, below), so these are the times it will actually run.
Only runs after now are counted, and only for Routines that will run. These are left out:
- a paused Routine, one stopped in
errorafter a failed run, and a spent one-shot (idlewith no next run); - a Routine whose cron spec cannot be read;
- a team routine whose team is gone, archived, opted out of server orchestration, or has no active member;
- an agent routine whose agent is gone, archived, or a person;
- a Routine a pause or an archived team holds back, since it does not fire until that ends;
- every OpenClaw Gateway cron job and Hermes job (those are an agent’s own work, not team work).
idle Routine, the first run is its stored nextRunAt, the time the scheduler will actually use, and the cron spec gives the runs after it. A result is reused for up to a minute, and never past its first run, so boards that poll this cost little.
- Query params:
bounds(required): 2 to 64 comma-separated epoch-millisecond integers in strictly ascending order, spanning at most 62 days. Windowiis[bounds[i], bounds[i + 1]).teamId(optional): only Routines whoseteamIdmatches. A Routine for an agent on no team appears only without this filter.
- Request body: none.
Responses
200 OK: only Routines with at least one run in some window are listed, each with one entry per window, in window order:
more says the window holds more than that. timeZone is the scheduler time zone, so a caller in another zone can tell which zone a Routine’s cron spec is read in.
400 Bad Request: bounds is missing, has fewer than 2 or more than 64 values, is not strictly ascending integers, or spans more than 62 days:
500 Internal Server Error: the Routines could not be read:
Example
GET /api/schedules/time-zone
The time zone Routines are worked out in. A cron spec is wall-clock time, so 0 9 * * * runs at 9:00 in this zone. Until one is set it is the server’s own zone, the zone of the process that runs Clawboo. In a container that is UTC unless TZ is set. One-shot once@ specs are fixed instants and do not use it. OpenClaw Gateway cron jobs keep their own zone.
- Request body: none.
Responses
200 OK:
500 Internal Server Error: the setting could not be read:
PUT /api/schedules/time-zone
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Set the time zone Routines are worked out in, for every Routine on the install. It is stored in Clawboo’s database, independent of the server process, so it survives a restart. Each armed Routine’s next run moves to the new zone’s clock in the same write as the setting, so a failed request changes neither. A Routine already due keeps its run; a paused Routine, or one stopped after a failure, takes the new zone when it is resumed, and one that is running takes it when the run ends.
- Request body:
{ "timeZone": string | null }. An IANA zone name such asAmerica/New_Yorksets that zone. The name is kept as given, apart from letter case (utcis stored asUTC).nullgoes back to the server’s own zone.
Responses
200 OK: the zone now in force, in the same shape as GET /api/schedules/time-zone.
400 Bad Request: the name is not a time zone (code: "invalid_time_zone"), or timeZone is missing or neither a string nor null (code: "invalid_body"):
Example
Error envelope
Every error here is{ "error": string, "code"?: string }. Branch on code, never on the message:
A cron spec that does not parse answers
code: "invalid_cron_spec" with a message that starts Invalid cron spec. A rate-limited request answers 429 { "error": "Too many requests. Wait a moment and retry." } with a Retry-After header.
Source of truth: apps/web/server/api/schedules.ts; the three sources in apps/web/server/lib/scheduleSource/; the scheduler time zone in apps/web/server/lib/routines/timeZone.ts; error classes in packages/scheduler/src/errors.ts; Routine states in packages/db/src/routines/state-machine.ts.
Related
- Routines: create and manage Routines in the dashboard.
- Scheduling: how Routines differ from OpenClaw’s and Hermes’s own jobs, and how a run reaches a team.
- The board: bound tasks and the one-claim rule.
- System API: the OpenClaw Gateway the cron source talks to.
- @clawboo/scheduler: the shared record type, sources and errors.
- REST API overview: authentication, rate limits and conventions.