Schedules
Make an agent run a task on a cron schedule: create, list and delete schedules.
A schedule makes an agent run a prompt at fixed times: every morning at 7:00, every Monday, the first day of the month. The agent runs the task on its own, with its skills, MCP servers, connected apps and memory. No end user and no conversation is involved.
The platform does not deliver the result of a scheduled run to you. A run sends no webhook and writes to no conversation. Write the prompt so that the task itself delivers its result through a tool: an MCP server of yours, or a connected app (send the email, post the message, write the row).
All paths on this page start with:
https://sokko.ai/api/v1/workspaces/{workspaceId}/agents/{agentId}The examples use $BASE for that prefix. The agent must be ready for every
call on this page: schedules live in the running agent.
Create a schedule
POST /schedules| Field | Type | Rules |
|---|---|---|
name | string | Required. 1 to 80 characters, not starting with [. Unique among the agent's schedules. |
cron | string | Required. A five-field cron expression. See below. |
prompt | string | Required. 1 to 4,000 characters. What the agent does at each run. |
timezone | string | Optional. An IANA time zone name such as Europe/Brussels. |
curl $BASE/schedules \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Morning order summary",
"cron": "0 7 * * 2-7",
"prompt": "Read the orders for today with the orders tool. Send the summary to the shop owner with the send_summary tool.",
"timezone": "Europe/Brussels"
}'The answer is 201:
{
"id": "4f8a2c1e9b7d",
"name": "Morning order summary",
"cron": "0 7 * * 2-7",
"prompt": "Read the orders for today with the orders tool. Send the summary to the shop owner with the send_summary tool.",
"timezone": "Europe/Brussels",
"enabled": true,
"managedBy": null,
"nextRunAt": "2026-11-21T06:00:00.000Z",
"lastRunAt": null,
"lastStatus": null
}The name is the key of a schedule. A second schedule with the name of an
existing one answers 409 schedule_exists, whatever its other fields are, so a
create you send again after a lost answer cannot make the task run twice. The
name is compared as written, after the spaces at its ends are removed.
A schedule cannot be changed. Delete it and create it again.
The id of a schedule is a short string, not a UUID. Treat it as opaque.
Five-field cron
cron has exactly five fields, separated by spaces:
┌───────── minute 0 to 59
│ ┌─────── hour 0 to 23
│ │ ┌───── day of month 1 to 31
│ │ │ ┌─── month 1 to 12
│ │ │ │ ┌─ day of week 0 to 7 (0 and 7 are Sunday)
│ │ │ │ │
0 7 * * 2-7Each field takes numbers, *, lists with ,, ranges with - and steps with
/. Names such as MON or JAN, a seconds field, and shortcuts such as
@daily are refused.
| Expression | Runs |
|---|---|
0 7 * * * | Every day at 7:00. |
*/15 * * * * | Every 15 minutes. |
30 8 * * 1-5 | Monday to Friday at 8:30. |
0 9 1 * * | The first day of each month at 9:00. |
0 8,18 * * * | Every day at 8:00 and at 18:00. |
Send timezone when the hour matters. Without it the agent's own time zone
applies, and the schedule object shows "timezone": null. If the create
answers 400 with a message about timezone, that agent runs every schedule in
its own time zone: send the schedule without the field.
Each run calls a model, which costs credits of the workspace. A schedule that runs every few minutes adds up.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A bad name, a cron expression that is not five fields or has a value out of range, an unknown time zone. |
| 404 | not_found | No such agent in this workspace. |
| 409 | agent_not_ready | The agent is not ready. |
| 409 | agent_busy | The agent is being upgraded to a newer recipe version. Try again when the upgrade has ended. |
| 409 | schedule_exists | The agent has a schedule with this name. |
| 503 | agent_unavailable | The agent's scheduler did not answer. List the schedules before you try again: the schedule can exist. |
List schedules
GET /schedulescurl $BASE/schedules \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{
"data": [
{
"id": "4f8a2c1e9b7d",
"name": "Morning order summary",
"cron": "0 7 * * 2-7",
"prompt": "Read the orders for today with the orders tool. Send the summary to the shop owner with the send_summary tool.",
"timezone": "Europe/Brussels",
"enabled": true,
"managedBy": null,
"nextRunAt": "2026-11-22T06:00:00.000Z",
"lastRunAt": "2026-11-21T06:00:03.812Z",
"lastStatus": "ok"
}
],
"nextCursor": null
}The answer holds every schedule of the agent in one page. nextCursor is
always null.
| Field | Meaning |
|---|---|
cron | The expression. null for a task the agent set for itself with a schedule that is not a cron expression. |
enabled | false for a paused schedule. |
managedBy | recipe for a schedule that the agent's recipe created, else null. An upgrade replaces the recipe's schedules and leaves yours. |
nextRunAt | When the next run is due, or null. |
lastRunAt | The time of the last run, or null before the first run. |
lastStatus | ok or error for the last run, null before the first run. |
The list also shows schedules the agent created itself, for example when an operator asked it in a conversation to "remind me every Friday".
The time and the status of the last run are all the API reports about a run. The output of the run is not available.
Errors: 404 not_found, 409 agent_not_ready, 503 agent_unavailable.
Delete a schedule
DELETE /schedules/{scheduleId}curl -X DELETE $BASE/schedules/4f8a2c1e9b7d \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{ "id": "4f8a2c1e9b7d", "deleted": true }A delete is permanent. If you delete a schedule that a recipe created, the next upgrade of the agent creates it again.
Errors: 404 not_found (no such agent or schedule), 409 agent_not_ready,
409 agent_busy (the agent is being upgraded), 503 agent_unavailable.
Webhooks
Register an endpoint, receive signed events for agents, turns, connections and credits, verify the signature, and handle retries.
Recipes
Describe your standard agent once, publish it as a numbered version, apply it for each customer with that customer's values, and upgrade agents to a newer version.