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> or X-API-Key header.
  • REST fallback: /api/v1/* — X-API-Key header.
  • Keys are app-scoped and tenant-scoped; every operation is audited (GET /api/activity/agent-activity).

Decision procedure (MCP)

  1. initialize — echo any protocolVersion you support (server base: 2025-06-18).
  2. tools/list — 17 tools. Recommended order of operations:
    • Orient: whoami, list_environments, list_apps
    • Draft: test_schedule_due before 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_event for staged control
    • Manage later: list_schedules, get_schedule, update_schedule, test_schedule_due
  3. tools/call — usage errors return isError results; fix arguments and retry. Do not retry protocol errors (-32601, validation 400s) 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 POST per 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 webhook secret; plus X-Organization-Id, X-App-Id, X-Webhook-Id, X-Recurrence-Attempt, X-Recurrence-Batch-Id.
  • Failure → retry with exponential backoff (backoffSeconds × 2^(attempt-1)), same batchId. Receivers must be idempotent keyed on batchId and 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_task over 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 via list_environments before 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).