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
201with the created record; timestamps are ISO-8601 UTC. - List endpoints accept
page,pageSize,daysfilters where noted; environment scoping viaX-Environment-Idheader.
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.