DOCS · CORE WORKFLOWS
Creating Schedules
Cron expressions, human-friendly recurrence, timezones, retry policies, and the one-call with-webhook composite.
A schedule = time + timezone + retry policy. Everything else (where the delivery goes, what it carries) is attached to it.
Two ways to say “when”
Cron expression — standard 5-field syntax, validated server-side:
curl -X POST https://api.recurrence.cloud/api/v1/schedules \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{
"name": "nightly-sync",
"cronExpr": "0 3 * * *",
"timezone": "Europe/Berlin",
"appId": "<app id>"
}'
Human-friendly recurrence — for agents and integrations that think in words, not crontab:
curl -X POST https://api.recurrence.cloud/api/v1/schedules \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{
"name": "tuesday-standup-prep",
"recurrenceText": "every 2 weeks on monday at 09:00",
"timezone": "America/New_York",
"appId": "<app id>"
}'
Equivalent structured fields also work: frequency (second…year) + interval, byDay ("monday,wednesday"), byMonthDay ("1,15"), and startTime ("09:00").
The one-call composite
Schedule + delivery target + first event, atomically (POST /api/v1/schedules/with-webhook):
{
"schedule": { "name": "daily-report", "cronExpr": "0 9 * * 1-5", "timezone": "UTC" },
"webhook": { "url": "https://api.example.com/report", "secret": "<long random string>" },
"event": { "subject": "daily-report", "payload": { "type": "report.csv" } },
"appId": "<app id>"
}
Swap webhook for mcp to fire an MCP tool call instead of an HTTP webhook:
{
"schedule": { "name": "weekly-brief", "cronExpr": "0 8 * * 1-5", "timezone": "America/New_York" },
"mcp": { "url": "https://mcp.yourcompany.dev", "toolName": "briefing.generate" },
"event": { "subject": "briefing", "payload": { "scope": "ops" } },
"appId": "<app id>"
}
Retry policy
Failed deliveries retry with exponential backoff — backoffSeconds × 2^(attempt-1):
{
"maxRetries": 5,
"backoffSeconds": 60
}
Attempt 1 fires immediately; a failure waits 60s, then 120s, 240s… up to maxRetries (0–10, default 3 with 60s base). Every attempt is recorded as its own run; the final failure is marked exhausted and can trigger failure alerts.
Lifecycle
PATCH /api/v1/schedules/:id— change time, target, policy, oractive: falseto pause. Schedules live outside your deploys.POST /api/schedules/:id/run-now(session) — trigger immediately for testing.POST /api/schedules/test-due— dry-run: which schedules fire next and why (debugging timezone logic).GET /api/schedules/:id/runs— per-attempt history.
Timezones are part of the schedule
"0 9 * * 1-5" + timezone: "America/New_York" fires at 9am New York, DST-corrected — the schedule carries the clock so your receivers never do timezone math.
Next: Webhooks & deliveries — how the signed POST actually arrives.