DOCS · AGENTS
For AI agents
A terse, machine-first operating guide: everything an agent needs to create and manage scheduled deliveries — auth, endpoints, tools, and the delivery contract.
This page is written for AI agents and their operators: terse, complete, no narrative. Prefer the MCP interface (walkthrough) — fall back to REST where noted.
Identity & auth
- Base URL:
https://api.recurrence.cloud - MCP:
POST /api/mcp— JSON-RPC 2.0, Streamable HTTP, stateless. Auth:Authorization: Bearer <agent API key>orX-API-Keyheader. - REST fallback:
/api/v1/*—X-API-Keyheader. - Keys are app-scoped and tenant-scoped; every operation is audited (
GET /api/activity/agent-activity).
Decision procedure (MCP)
initialize— echo anyprotocolVersionyou support (server base:2025-06-18).tools/list— 17 tools. Recommended order of operations:- Orient:
whoami,list_environments,list_apps - Draft:
test_schedule_duebefore creating — confirm the recurrence fires when you think it will - Create:
create_scheduled_task(one call: schedule + target + first event) for the common case;create_webhook+create_schedule+add_eventfor staged control - Manage later:
list_schedules,get_schedule,update_schedule,test_schedule_due
- Orient:
tools/call— usage errors returnisErrorresults; fix arguments and retry. Do not retry protocol errors (-32601, validation400s) unchanged.
Creating a schedule (tool call template)
{
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "create_scheduled_task", "arguments": {
"name": "<kebab-case name>",
"appId": "<required app id from whoami/list_apps>",
"recurrenceText": "every 15 minutes",
"timezone": "UTC",
"target": { "url": "https://receiver.example/ingest", "webhook": { "secret": "<long random string>" } },
"firstEvent": { "subject": "<grouping-key>", "payload": { "type": "<namespaced.event>" } }
} }
}
Recurrence: prefer recurrenceText (“every 2 weeks on monday at 09:00”); use cronExpr (“0 9 * * 1-5”) only when recurrence text is insufficient. Always set timezone explicitly.
Delivery contract (what the schedule does)
- One signed
POSTper fire: body{ events, organizationId, appId, webhookId, batchId, attempt, firedAt }. events[]entries:{ id, subject, scheduleId, scheduleName, data }; same-subject events arrive grouped{ subject, count, events }.- Signature:
X-Webhook-Signature= hex HMAC-SHA256 of the raw body with the webhooksecret; plusX-Organization-Id,X-App-Id,X-Webhook-Id,X-Recurrence-Attempt,X-Recurrence-Batch-Id. - Failure → retry with exponential backoff (
backoffSeconds × 2^(attempt-1)), samebatchId. Receivers must be idempotent keyed onbatchIdand return 2xx fast; fan long work into queues. - Agent-created schedules must target receivers the operator owns or is authorized to fire into.
REST fallback (programmatic, X-API-Key)
| Action | Call |
|---|---|
| Create everything once | POST /api/v1/schedules/with-webhook { schedule{ name, cronExpr, timezone }, webhook{ url, secret }, event{ subject, payload }, appId } |
| Attach more events | POST /api/v1/events { "scheduleId", "subject", "payload" } |
| Update time | PATCH /api/v1/schedules/:id { "cronExpr": "…" } |
| Pause | PATCH /api/v1/schedules/:id { "active": false } |
| Inspect | GET /api/v1/schedules/:id · GET /api/schedules/:id/runs · GET /api/activity?scheduleId=… |
| Verify signature locally | POST /api/api-keys/verify { key, payload, signature } |
Machine-readable index of all docs: /llms.txt. Full endpoint catalog: API reference.
Constraints & etiquette
- Rate limits apply per key — batch creation bursts politely; prefer
create_scheduled_taskover four sequential calls. - Never place secrets in
event.payload; the payload is delivered to the receiver as configured. - Environments (
testing/production) scope apps, keys, and schedules — verify vialist_environmentsbefore creating anything the operator might mistake for production. - A2A alternative:
POST /api/a2a(SendMessage/GetTask/CancelTask/ListTasks, card at/.well-known/agent-card.json); UCP:POST /api/ucp(context/list,context/read).