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, or active: false to 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.