DOCS · REFERENCE

API Reference

Every endpoint — REST, programmatic surface, MCP, A2A, UCP, and billing.

The endpoint catalog. Auth modes, delivery format, and code walkthroughs live in the earlier pages — start there if you’re new.

Base URLs

Service Base URL
REST API https://api.recurrence.cloud
MCP (JSON-RPC) https://api.recurrence.cloud/api/mcp
A2A (JSON-RPC) https://api.recurrence.cloud/api/a2a

Conventions

  • JSON bodies (Content-Type: application/json).
  • Errors return {"error": "<message>"} with the appropriate status.
  • Creates return 201 with the created record; timestamps are ISO-8601 UTC.
  • List endpoints accept page, pageSize, days filters where noted; environment scoping via X-Environment-Id header.

Environments

Method Endpoint Description
POST /api/environments Create — { "name": "prod", "type": "production" | "testing" }
GET /api/environments/org Environments of the active org (session)
GET /api/environments/org/:organizationId By org
GET /api/environments/:id Single
PATCH /api/environments/:id Update — { "name"?, "type"? }
DELETE /api/environments/:id Delete (admin)

Response — 201 POST /api/environments:

{
  "id": "env_…",
  "name": "production",
  "type": "production",
  "organizationId": "org_…",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "updatedAt": "2026-01-01T12:00:00.000Z"
}

Apps

An app owns webhooks, schedules, events, and API keys.

Method Endpoint Description
POST /api/apps Create — { "name", "organizationId", "environmentId"? }
GET /api/apps Apps of the active org
GET /api/apps/org/:organizationId By org
GET /api/apps/:id Single
PATCH /api/apps/:id Update — { "name"?, "environmentId"?, "active"? }
DELETE /api/apps/:id Delete (admin)

Response — 201 POST /api/apps (the apiToken is the delivery-signing secret for this app):

{
  "id": "app_…",
  "name": "my-first-app",
  "apiToken": "rc_app_…",
  "environmentId": "env_…",
  "organizationId": "org_…",
  "active": true,
  "createdAt": "2026-01-01T12:00:00.000Z"
}

API keys

Method Endpoint Description
POST /api/api-keys Create — { "name", "appId", "environmentId"?, "expiresAt"? }
POST /api/api-keys/validate Validate a key
POST /api/api-keys/sign { "key", "payload" } → HMAC-SHA256 signature (test deliveries)
POST /api/api-keys/verify { "key", "payload", "signature" } → { "valid" }
GET /api/api-keys/app/:appId Keys for an app
GET /api/api-keys/org Org-wide listing (session)
GET /api/api-keys/:id Single
PATCH /api/api-keys/:id { "name"? }
DELETE /api/api-keys/:id Delete

Response — 201 POST /api/api-keys (the raw key is returned once, never stored):

{
  "id": "key_…",
  "name": "prod-worker",
  "keyPrefix": "rc_1a2b",
  "rawKey": "rc_live_the-only-time-you-see-this",
  "expiresAt": null,
  "active": true
}

Webhooks

A webhook is a delivery target. Deliveries are signed with the webhook’s secret — HMAC-SHA256 over the raw body (verification).

Method Endpoint Description
POST /api/webhooks Create — { "url", "appId", "organizationId", "method"?, "headers"?, "payload"?, "secret"?, "timeoutMs"? }
GET /api/webhooks/org/:organizationId By org
GET /api/webhooks/by-app/:appId By app
GET /api/webhooks/:id Single
PATCH /api/webhooks/:id Update any writable field
DELETE /api/webhooks/:id Delete
GET /api/webhooks/:id/activity Delivery history for this webhook
POST /api/webhooks/:id/test Fire a test delivery now
POST /api/webhooks/:id/rotate-secret New secret; old one invalid immediately

Response — 201 POST /api/webhooks (timeoutMs default 30000):

{
  "id": "wh_…",
  "name": "report-receiver",
  "url": "https://api.yourcompany.dev/jobs",
  "method": "POST",
  "headers": {},
  "secret": "a-long-random-string",
  "timeoutMs": 30000,
  "active": true,
  "appId": "app_…",
  "organizationId": "org_…"
}

Schedules

Time comes from cronExpr or human-friendly recurrence (recurrenceText / frequency + interval, byDay, byMonthDay, startTime); always include a timezone. Delivery target: webhookId or an MCP tool (mcpServerId + mcpToolName).

Method Endpoint Description
POST /api/schedules Create (session) — body below
GET /api/schedules/next-runs Upcoming fires
GET /api/schedules/org/:organizationId By org
GET /api/schedules/by-app/:appId By app
GET /api/schedules/:id Schedule + attached events
PATCH /api/schedules/:id Update any writable field ("active": false pauses)
DELETE /api/schedules/:id Delete
POST /api/schedules/test-due Dry-run: which schedules fire when, and why
GET /api/schedules/:id/runs Run history — one receipt per attempt
POST /api/schedules/:id/run-now Trigger immediately

Request — POST /api/schedules:

{
  "name": "nightly-sync",
  "cronExpr": "0 3 * * *",
  "timezone": "Europe/Berlin",
  "appId": "app_…",
  "organizationId": "org_…",
  "webhookId": "wh_…",
  "maxRetries": 3,
  "backoffSeconds": 60,
  "active": true
}

Response — 201:

{
  "id": "sch_…",
  "name": "nightly-sync",
  "cronExpr": "0 3 * * *",
  "timezone": "Europe/Berlin",
  "appId": "app_…",
  "organizationId": "org_…",
  "webhookId": "wh_…",
  "maxRetries": 3,
  "backoffSeconds": 60,
  "active": true,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "updatedAt": "2026-01-01T12:00:00.000Z"
}

Run receipt — GET /api/schedules/:id/runs (one per attempt):

{
  "id": "run_…",
  "scheduleId": "sch_…",
  "status": "success",
  "responseCode": 200,
  "attempt": 1,
  "trigger": "scheduled",
  "createdAt": "2026-01-01T03:00:01.250Z"
}

Events

Events define what a fire delivers. Same-subject events on one fire are batched into a single delivery.

Method Endpoint Description
POST /api/events Create — { "scheduleId", "organizationId", "subject", "payload", "environmentId"? }
GET /api/events/org/:organizationId By org
GET /api/events/by-schedule/:scheduleId By schedule
GET /api/events/:id Single
DELETE /api/events/:id Delete

Response — 201 POST /api/events:

{
  "id": "evt_…",
  "scheduleId": "sch_…",
  "organizationId": "org_…",
  "subject": "morning-report",
  "payload": { "type": "report.daily" },
  "createdAt": "2026-01-01T12:00:00.000Z"
}

Delivery format

Every fire is one signed HTTP request to the webhook URL:

Header Meaning
X-Webhook-Signature Hex HMAC-SHA256 of the raw body (when the webhook has a secret)
X-Signature-Algorithm Always sha256
X-Organization-Id Owning organization
X-App-Id Owning app
X-Webhook-Id Registered target that fired
X-Recurrence-Attempt 1 = first fire, 2+ = retry
X-Recurrence-Batch-Id Stable id for the delivery chain — key idempotency here
{
  "events": [
    {
      "id": "evt_…",
      "subject": "morning-report",
      "scheduleId": "sch_…",
      "scheduleName": "morning-report",
      "data": { "type": "report.daily" }
    }
  ],
  "organizationId": "org_…",
  "appId": "app_…",
  "webhookId": "wh_…",
  "batchId": "bat_…",
  "attempt": 1,
  "firedAt": "2026-01-01T06:00:01.000Z"
}

Same-subject events arrive grouped: "events": [{ "subject", "count", "events": […] }]. Full verification code: Webhooks & deliveries.

Activity

Method Endpoint Description
GET /api/activity Org-wide delivery stream — filters: status (success·failed·retrying·exhausted·skipped), scheduleId, webhookId, subject, days (1–90), page, pageSize
GET /api/activity/agent-activity Audit trail of agent operations (MCP/A2A/UCP)

Activity item shape: { id, webhookId, method, url, statusCode, requestBody, responseBody, duration, success, scheduleId, subject, batchId, createdAt } — bodies are truncated excerpts.

MCP servers (management)

Method Endpoint Description
GET / POST /api/v1/mcp-servers Register — { "url", "name"?, "headers"?, "timeoutMs"? } (also session-authed at /api/mcp-servers)
GET /api/v1/mcp-servers/:id Single
PATCH / DELETE /api/v1/mcp-servers/:id Manage
GET /api/v1/mcp-servers/:id/tools Discover this server’s tools
POST /api/v1/mcp-servers/discover Probe an ad-hoc URL
POST /api/v1/mcp-servers/:id/verify Deep-verify a tool exists

MCP endpoint — POST /api/mcp

Streamable-HTTP JSON-RPC 2.0; agent API key auth; stateless (GET/DELETE → 405). Methods: initialize (echoes your protocolVersion, base 2025-06-18), notifications/initialized, ping, tools/list, tools/call.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_scheduled_task",
    "arguments": {
      "name": "status-check",
      "appId": "app_…",
      "recurrenceText": "every 15 minutes",
      "timezone": "UTC",
      "target": { "url": "https://api.yourcompany.dev/check" },
      "firstEvent": { "subject": "status-check", "payload": { "type": "ops.status" } }
    }
  }
}

Tool catalog (17): whoami — list_environments — list_apps — list_schedules — get_schedule — create_schedule — update_schedule — delete_schedule — test_schedule_due — list_webhooks — create_webhook — list_events — add_event — register_mcp_server — list_mcp_servers — discover_mcp_tools — create_scheduled_task

A2A & UCP

Surface Details
A2A agent card GET /.well-known/agent-card.json (public; also /api/a2a/agent-card.json)
A2A JSON-RPC POST /api/a2a — SendMessage · GetTask · CancelTask · ListTasks
UCP manifest GET /.well-known/ucp.json (public)
UCP JSON-RPC POST /api/ucp — context/list · context/read

Billing

Method Endpoint Description
POST /api/billing/webhook Stripe events (stripe-signature, no auth)
GET /api/billing/event-count { eventCount, eventLimit, totalEventLimit, eventLimitReached }
GET /api/billing/usage · /status Monthly usage; plan & limits
GET /api/billing/plans (+/:id) Plan catalog (admin CRUD on :id)
POST /api/billing/create-checkout-session Stripe Checkout — subscription
POST /api/billing/create-addon-checkout-session Stripe Checkout — add-on
GET /api/billing/addon-packages(…) Available add-on packages
POST /api/billing/create-portal-session Stripe customer portal
POST /api/billing/refresh-plan Re-sync plan state from Stripe
POST /api/billing/cancel-subscription Cancel
CRUD /api/billing/orgs/:orgId/accounts… · /orgs/:orgId/add-ons… Billing accounts & add-ons

Programmatic — /api/v1/* (X-API-Key)

Method Endpoint Description
POST /api/v1/schedules Same body/response as POST /api/schedules
POST /api/v1/schedules/with-webhook One call: schedule + webhook (or MCP target) + first event
POST /api/v1/schedules/test-due Dry-run upcoming fires
POST /api/v1/webhooks Create a webhook
POST /api/v1/events { "scheduleId", "subject", "payload" }
GET / POST /api/v1/mcp-servers Register & list MCP servers
GET /api/v1/mcp-servers/:id · /:id/tools Inspect a server; discover its tools
POST /api/v1/mcp-servers/discover · /:id/verify Probe ad-hoc; deep-verify a tool

The one-call composite — request:

{
  "schedule": { "name": "daily-report", "cronExpr": "0 9 * * 1-5", "timezone": "UTC" },
  "webhook": { "url": "https://api.example.com/report", "secret": "<webhook secret>" },
  "event": { "subject": "daily-report", "payload": { "type": "report.csv" } },
  "appId": "app_…"
}

Response — 201 (schedule, delivery-target link, and event created together):

{
  "schedule": {
    "id": "sch_…",
    "name": "daily-report",
    "cronExpr": "0 9 * * 1-5",
    "timezone": "UTC",
    "webhookId": "wh_…",
    "active": true
  },
  "webhookId": "wh_…",
  "mcpServerId": null,
  "createdMcpServer": null,
  "event": {
    "id": "evt_…",
    "subject": "daily-report",
    "payload": { "type": "report.csv" }
  }
}

To fire an MCP tool instead, replace webhook with "mcp": { "url": "https://…", "toolName": "reports.generate", "arguments": {} }.

Errors

Status Meaning
400 Validation failure / referenced record missing — { "error": "<message>", "code": "NOT_FOUND"? }
401 Missing or invalid credentials
403 Role insufficient
404 Not found
500 Internal error

JSON-RPC surfaces (MCP/A2A/UCP) return JSON-RPC errors (-32601 unsupported method, -32700 parse) and MCP isError results for predictable tool-usage failures.