Ciresk Docs
API reference

Schedules

Autostart a paused session, or a template's session, at a local time on chosen days.

GET/v1/dev/schedules

List autostart schedules

The caller's autostart schedules, each with its next start and what its last run did.

A person reads their own schedules; an agent or a key its owner's. With session_id or template, only the schedule of that session or template (an empty list when there is none).

Permission: dev:sessions.read

Parameters

NameTypeRequiredDescription
session_idquerystringOptionalthe schedule of this session
templatequerystringOptionalthe caller's schedule of this template name

Response200 OK

schedulesarray of objectsRequired
schedules[].atstringRequired
schedules[].created_atstring (date-time)Required
schedules[].daysarray of stringsRequired
schedules[].idstringRequired
schedules[].last_runobject or nullRequired
what the schedule's last start did; a session that was not paused is in neither list
schedules[].last_run.atstring (date-time)Required
schedules[].last_run.missedbooleanRequired
more than 15 minutes late: nothing was started
schedules[].last_run.refusedarray of objectsRequired
schedules[].last_run.refused[].codestringRequired
the code dev.sessions.start answers: budget_exceeded, org_session_limit, person_session_limit, cell_session_limit, a licence refusal, view_unknown (the directory cannot say the owner's groups and the policy has path rules)
schedules[].last_run.refused[].session_idstringRequired
schedules[].last_run.startedarray of stringsRequired
the sessions it started
schedules[].next_start_atstring (date-time)Required
the next start, 5 minutes before the next chosen day's at
schedules[].session_idstring or nullRequired
schedules[].templatestring or nullRequired
schedules[].time_zonestringRequired
schedules[].updated_atstring (date-time)Required

Errors

curl "$CIRESK_API/v1/dev/schedules" \
  -H "Authorization: Bearer $CIRESK_KEY"
PUT/v1/dev/schedules

Set an autostart schedule

Set the autostart schedule of one paused-capable session or of a template, so it is ready at a local time on chosen days.

One schedule per session (a cloud writer the caller owns) or per template name of the caller's. At each chosen day's at, in time_zone, minus 5 minutes, dev starts the session, or every paused session of the caller's of that template, from its checkpoint exactly as dev.sessions.start does: the licence, the live-session limits, the cell's envelope and the budget's first slice; a refusal is recorded in last_run and journaled session.autostart_refused, and the next day is tried again. A session that is not paused is left as it is. A start more than 15 minutes late (the api was down) is skipped as missed. Setting it again replaces it. Audited dev.schedule.set. No schedule exists until a person or their agent sets one.

Permission: dev:sessions.writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalmakes a retried call act once (every mutating MCP tool sends one)

Request body

atstringRequired
the local time the session is ready by (HH:MM); it starts 5 minutes before
daysarray of strings
the local days it starts on; weekdays by default
session_idstring or null
a cloud-writer session the caller owns
templatestring or null
every paused session of the caller's of this template name
time_zonestringRequired
an IANA time zone (Europe/Copenhagen)

Response200 OK

atstringRequired
created_atstring (date-time)Required
daysarray of stringsRequired
idstringRequired
last_runobject or nullRequired
what the schedule's last start did; a session that was not paused is in neither list
last_run.atstring (date-time)Required
last_run.missedbooleanRequired
more than 15 minutes late: nothing was started
last_run.refusedarray of objectsRequired
last_run.refused[].codestringRequired
the code dev.sessions.start answers: budget_exceeded, org_session_limit, person_session_limit, cell_session_limit, a licence refusal, view_unknown (the directory cannot say the owner's groups and the policy has path rules)
last_run.refused[].session_idstringRequired
last_run.startedarray of stringsRequired
the sessions it started
next_start_atstring (date-time)Required
the next start, 5 minutes before the next chosen day's at
session_idstring or nullRequired
templatestring or nullRequired
time_zonestringRequired
updated_atstring (date-time)Required

Errors

  • 401an error
  • 403not_allowed (another person's session)
  • 404an error
  • 409not_cloud_writer (a local writer is never paused: its files are on the device), session_ended
  • 422validation_failed: not exactly one of session_id and template, no day, at not HH:MM, an unknown time zone
curl -X PUT "$CIRESK_API/v1/dev/schedules" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Idempotency-Key: 1a41ffa7-8096-4010-ac3f-97beb88c7017" \
  -H "Content-Type: application/json" \
  -d '{
    "at": "2026-10-20T14:04:12Z",
    "days": [
      "mon"
    ],
    "session_id": "devs_0166ba8e973a3df1b173b30df1cb8f2f",
    "template": "platform",
    "time_zone": "2026-10-20T14:04:12Z"
  }'
DELETE/v1/dev/schedules

Delete an autostart schedule

Remove the autostart schedule of a session or a template; the sessions stay as they are.

Permission: dev:sessions.write

Parameters

NameTypeRequiredDescription
session_idquerystringOptionalthe schedule of this session
templatequerystringOptionalthe caller's schedule of this template name

Response204 No Content

removed

Errors

  • 401an error
  • 403an error
  • 422validation_failed: not exactly one of session_id and template
curl -X DELETE "$CIRESK_API/v1/dev/schedules" \
  -H "Authorization: Bearer $CIRESK_KEY"