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