DOCS · REFERENCE
Examples
Copy-paste recipes for scheduling and receiving — curl, Node, Python, Cloudflare Workers, Next.js, MCP clients.
Runnable recipes covering the common setups. All use the real API surface — walkthrough explains each piece if something is unfamiliar.
1. Zero to signed delivery (curl)
export API_KEY="rc_live_…" APP_ID="app_…"
curl -X POST https://api.recurrence.cloud/api/v1/schedules/with-webhook \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{
"schedule": { "name": "daily-digest", "cronExpr": "0 6 * * *", "timezone": "America/New_York" },
"webhook": { "url": "https://webhook.site/your-uuid", "secret": "a-long-random-string" },
"event": { "subject": "digest-prod", "payload": { "type": "digest.daily" } },
"appId": "$APP_ID"
}'
Test without waiting: POST /api/webhooks/:id/test fires a probe delivery now.
2. Node / TypeScript (axios)
import axios from "axios";
const rc = axios.create({
baseURL: "https://api.recurrence.cloud/api/v1",
headers: { "X-API-Key": process.env.API_KEY! },
});
export async function scheduleTenantDigest(tenant: string, webhookUrl: string) {
const { data: schedule } = await rc.post("/schedules/with-webhook", {
schedule: { name: `digest-${tenant}`, recurrenceText: "every day at 06:00", timezone: tenantTz(tenant) },
webhook: { url: webhookUrl, secret: process.env.WEBHOOK_SECRET },
event: { subject: tenant, payload: { type: "digest.daily", tenant } },
appId: process.env.APP_ID!,
});
return schedule;
}
// Attach another event to an existing schedule (batched by subject)
await rc.post("https://api.recurrence.cloud/api/events", {
scheduleId: schedule.id, subject: tenant,
payload: { type: "digest.topics", tenant, channels: ["email", "slack"] },
}).catch(() => {}); // best-effort attach — see Events & Batching for grouping semantics
3. Python (requests)
import os, requests
RC = "https://api.recurrence.cloud"
H = {"X-API-Key": os.environ["API_KEY"], "Content-Type": "application/json"}
r = requests.post(f"{RC}/api/v1/schedules/with-webhook", headers=H, json={
"schedule": {"name": "weekly-rollup", "cronExpr": "0 8 * * 1", "timezone": "UTC"},
"webhook": {"url": "https://receivers.example/rollup", "secret": os.environ["WEBHOOK_SECRET"]},
"event": {"subject": "weekly-rollup", "payload": {"type": "metrics.rollup"}},
"appId": os.environ["APP_ID"],
})
r.raise_for_status()
print(r.json()["schedule"]["id"])
4. Receiver — Cloudflare Worker (signature-verified)
export default {
async fetch(request, env): Promise<Response> {
const raw = await request.text();
const ok = await verify(raw, request.headers.get("X-Webhook-Signature"), env.WEBHOOK_SECRET);
if (!ok) return new Response("invalid signature", { status: 401 });
const batch = JSON.parse(raw);
// Dedupe retries on batchId; expand grouped events
for (const g of batch.events) {
const list = Array.isArray(g.events) ? g.events : [g];
for (const e of list) await handle(e.data, batch.batchId);
}
return new Response("ok");
},
};
async function verify(raw: string, sigHex: string | null, secret: string) {
if (!sigHex) return false;
const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret),
{ name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
const digest = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(raw));
return [...new Uint8Array(digest)].map(b => b.toString(16).padStart(2, "0")).join("") === sigHex;
}
5. Receiver — Next.js App Router (idempotent + fast fan-out)
// app/api/ingest/route.ts
export const maxDuration = 60;
export async function POST(request: Request) {
const raw = await request.text();
const sig = request.headers.get("X-Webhook-Signature");
if (!(await verify(raw, sig, process.env.WEBHOOK_SECRET!)))
return Response.json({ error: "invalid signature" }, { status: 401 });
const batch = JSON.parse(raw);
if (await seen(batch.batchId)) return Response.json({ ok: true }); // replay → no-op
for (const e of flatten(batch.events)) await queue.send(e.data); // work continues async
await mark(batch.batchId);
return Response.json({ ok: true }); // 2xx fast, scheduler records receipt
}
6. MCP client config (agents)
{ "mcpServers": { "recurrence-cloud": {
"url": "https://api.recurrence.cloud/api/mcp",
"headers": { "X-API-Key": "<agent api key>" } } } }
Then the agent’s JSON-RPC session — initialize → tools/list → tools/call (create_scheduled_task) — per the MCP walkthrough.
7. Agent delegating via A2A (curl)
curl -X POST https://api.recurrence.cloud/api/a2a \
-H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 7, "method": "SendMessage",
"params": { "parts": [ { "type": "text", "text": "Schedule a weekly rollup every Monday 08:00 UTC to https://receivers.example/rollup" } ] } }'
Task state: GetTask / ListTasks with the returned task id. Card: GET /.well-known/agent-card.json.
8. Monitoring an org’s failures (Python)
r = requests.get(f"{RC}/api/activity",
params={"status": "failed", "days": 7, "pageSize": 50},
headers={"Authorization": f"Bearer {SESSION}"})
for a in r.json():
print(a["scheduleName"], a["statusCode"], a["attempt"], a["batchId"])
More depth: delivery contract · retry semantics · endpoint catalog