{ "openapi": "3.1.0", "info": { "title": "LeadRails Public API", "version": "1.0.0", "description": "LeadRails public REST API. Authenticate with an API key issued from the admin UI; send it as `Authorization: Bearer lr_live_`.", "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.leadrails.dev", "description": "Production" }, { "url": "https://api-staging.leadrails.dev", "description": "Staging" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "LeadRails API key. Send as `Authorization: Bearer lr_live_`. Create and manage keys in the LeadRails admin UI." } }, "responses": { "Problem": { "description": "RFC 9457 problem document. Returned for every non-2xx response from a /v1/* endpoint.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://docs.leadrails.dev/errors/invalid-api-key", "description": "Absolute URL identifying the problem type. Slugs under https://docs.leadrails.dev/errors/ are stable." }, "title": { "type": "string", "example": "Invalid API key", "description": "Short, human-readable summary." }, "status": { "type": "integer", "example": 401, "description": "HTTP status code mirrored into the body." }, "detail": { "type": "string", "example": "The Authorization header is missing or does not carry a valid LeadRails API key.", "description": "Per-instance explanation." }, "instance": { "type": "string", "example": "/v1/me", "description": "URI reference identifying the occurrence." }, "request_id": { "type": "string", "example": "8f3c1234-abcd-cf-ray", "description": "Correlation id (CF-Ray when present). Mirrors the X-Request-Id response header." } } } } } } }, "schemas": {}, "parameters": {} }, "paths": { "/v1/healthz": { "get": { "tags": [ "meta" ], "summary": "Liveness probe.", "description": "Unauthenticated liveness probe. Returns a fixed shape so synthetic monitors can branch on response body in addition to status code.", "responses": { "200": { "description": "Health check OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "worker": { "type": "string", "enum": [ "admin-api" ] } }, "required": [ "ok", "worker" ] } } } } } } }, "/v1/me": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "meta" ], "summary": "Whoami + capabilities for the current API key.", "description": "Returns the workspace id, plan, scopes, current rate-limit snapshot, and a `capabilities` map advertising which conditionally-exposed features this key has access to. Clients should branch on the `capabilities` map rather than probing the surface for 403s.", "responses": { "200": { "description": "Discovery + capabilities for the current API key. Clients SHOULD call this on cold start and cache `plan` + `capabilities`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "name": { "type": "string", "description": "Human-readable workspace name. Mirrors `clients.name` for the resolved `client_id`." }, "plan": { "type": "string", "enum": [ "free", "starter", "pro", "agency", "scale" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 0 }, "period": { "type": "number", "enum": [ 60 ] }, "remaining": { "type": [ "integer", "null" ], "minimum": 0 }, "reset": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "limit", "period", "remaining", "reset" ] }, "capabilities": { "type": "object", "properties": { "events_read": { "type": "boolean" }, "webhooks_outbound": { "type": "boolean" }, "agency_endpoints": { "type": "boolean" }, "fine_grained_scopes": { "type": "boolean" } }, "required": [ "events_read", "webhooks_outbound", "agency_endpoints", "fine_grained_scopes" ] }, "request_id": { "type": "string" } }, "required": [ "client_id", "name", "plan", "scopes", "rate_limit", "capabilities", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/sources": { "get": { "security": [ { "ApiKeyAuth": [ "sources:read" ] } ], "tags": [ "sources" ], "summary": "List sources.", "description": "Returns the workspace's sources in `created_at DESC` order. Echo `next_cursor` from this response into the `cursor` query param to fetch the next page. The cursor is opaque — do not parse it.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paged list of sources in the calling key's workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" } } }, "post": { "security": [ { "ApiKeyAuth": [ "sources:write" ] } ], "tags": [ "sources" ], "summary": "Create a source.", "description": "Idempotent. Requires an `Idempotency-Key` request header (any client-chosen string up to 255 characters). A successful response is cached for 24 hours; replaying the same key returns the cached body verbatim with `Idempotent-Replayed: true`. Replaying with a different request body returns 422 `idempotency-conflict`.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "source_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "allowed_site_url": { "type": "string", "format": "uri" } }, "required": [ "name", "source_type" ] } } } }, "responses": { "200": { "description": "Idempotent replay. Body is bit-identical to the original 201 response. `Idempotent-Replayed: true` header is set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } } } }, "201": { "description": "Source created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v1/sources/{id}": { "get": { "security": [ { "ApiKeyAuth": [ "sources:read" ] } ], "tags": [ "sources" ], "summary": "Get a source by id.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } }, "patch": { "security": [ { "ApiKeyAuth": [ "sources:write" ] } ], "tags": [ "sources" ], "summary": "Update a source (partial).", "description": "Partial update. Requires `Idempotency-Key`. To flip status to `revoked`, use `POST /v1/sources/{id}/revoke` — the dedicated endpoint ensures the irreversible action gets its own audit row.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "allowed_site_url": { "type": [ "string", "null" ], "format": "uri" } } } } } }, "responses": { "200": { "description": "Source updated (or idempotent replay).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v1/sources/{id}/pause": { "post": { "security": [ { "ApiKeyAuth": [ "sources:write" ] } ], "tags": [ "sources" ], "summary": "Pause a source.", "description": "Idempotent. A paused source still ingests events (they persist with `source_paused: true` activity) but no delivery jobs fan out. Already-paused sources return 200 unchanged.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source paused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/v1/sources/{id}/revoke": { "post": { "security": [ { "ApiKeyAuth": [ "sources:write" ] } ], "tags": [ "sources" ], "summary": "Revoke a source.", "description": "Irreversible. Sets status to `revoked` and (transitively) hard-fails intake from any keys still associated with the source. Idempotent — already-revoked sources return 200 unchanged.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source revoked (terminal). Future intake from this source's keys hard-fails at auth.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "allowed_site_url": { "type": [ "string", "null" ] }, "auth_mode": { "type": "string", "enum": [ "hmac_v1" ] }, "schema_version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "source_type", "status", "allowed_site_url", "auth_mode", "schema_version", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/v1/sources/{id}/rotate-secret": { "post": { "security": [ { "ApiKeyAuth": [ "sources:write" ] } ], "tags": [ "sources" ], "summary": "Rotate a source's HMAC signing secret.", "description": "Revokes any active signing key on the source and mints a fresh 32-byte secret. The plaintext is returned ONCE in the response — there is no endpoint to recover it later. Requires `Idempotency-Key`.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Idempotent replay. Body is bit-identical to the original 201 response (the same plaintext is returned). `Idempotent-Replayed: true` header is set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key_id": { "type": "string" }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "key_id", "signing_secret", "created_at" ] } } } }, "201": { "description": "New signing secret minted. The plaintext is returned exactly once — persist it before this response leaves memory.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key_id": { "type": "string" }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "key_id", "signing_secret", "created_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/v1/destinations": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "List destinations.", "description": "Returns the workspace's destinations, newest first. Forward-only cursor pagination via the opaque `cursor` query parameter. Requires the `destinations:read` scope.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Page of destinations for the authenticated workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "adapter_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "adapter_type", "status", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "Create a destination.", "description": "Creates a destination of any supported adapter type. The `config` payload is validated against the adapter's Zod schema; outbound URL fields are re-checked against the SSRF guard. The `Idempotency-Key` header is REQUIRED (1-255 chars); retries with the same token replay the cached response. Requires the `destinations:write` scope.", "responses": { "201": { "description": "Destination created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "adapter_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "config": { "type": "object", "additionalProperties": {} }, "sensitive_keys": { "type": "array", "items": { "type": "string" } }, "provider_metadata": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "adapter_type", "status", "config", "sensitive_keys", "created_at", "updated_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/v1/destinations/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "Get a destination by id.", "description": "Returns the decrypted config map plus `sensitive_keys` listing which fields SDK clients should mask in their UIs. Requires the `destinations:read` scope.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Destination detail with decrypted config.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "adapter_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "config": { "type": "object", "additionalProperties": {} }, "sensitive_keys": { "type": "array", "items": { "type": "string" } }, "provider_metadata": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "adapter_type", "status", "config", "sensitive_keys", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "Update a destination.", "description": "Partial update; `adapter_type` is NOT patchable (create a new destination instead). Outbound URL fields are re-validated against the SSRF guard at write time. The `Idempotency-Key` header is REQUIRED (1-255 chars); retries with the same token replay the cached response. Requires the `destinations:write` scope.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Destination updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "adapter_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "config": { "type": "object", "additionalProperties": {} }, "sensitive_keys": { "type": "array", "items": { "type": "string" } }, "provider_metadata": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "adapter_type", "status", "config", "sensitive_keys", "created_at", "updated_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/v1/destinations/{id}/pause": { "post": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "Pause a destination.", "description": "Flips the destination to `paused`. Pre-existing delivery jobs already on the queue still execute; new fanout skips this destination. Idempotent: pausing an already-paused destination is a no-op success. Requires the `destinations:write` scope.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Destination paused. Future deliveries skip this destination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "adapter_type": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "config": { "type": "object", "additionalProperties": {} }, "sensitive_keys": { "type": "array", "items": { "type": "string" } }, "provider_metadata": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "name", "adapter_type", "status", "config", "sensitive_keys", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/v1/destinations/{id}/refresh-template": { "post": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "Refresh this destination's cached provider template manifest.", "description": "Re-fetches the upstream template manifest (today: Resend for `email_resend_v2`) and updates the destination's `provider_metadata`. Returns a diff vs the prior manifest. Rate-limited to ~1 request per 10s per destination; excess returns 429 with `Retry-After`. Requires the `destinations:write` scope.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Manifest refreshed. `changed` reports whether the new manifest differs from the prior cached one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "changed": { "type": "boolean" }, "manifest": {}, "diff": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "changed": { "type": "array", "items": { "type": "string" } }, "from_changed": { "type": "boolean" } }, "required": [ "added", "removed", "changed", "from_changed" ] }, "provider_scope": { "type": "string", "enum": [ "full", "send-only" ] } }, "required": [ "changed" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/v1/destinations/{id}/test": { "post": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "destinations" ], "summary": "Send a synthetic test event through this destination.", "description": "Dispatches a synthetic LeadEvent through the destination's adapter and reports the outcome. NO delivery_job is persisted; this is a non-destructive check that the destination's credentials work and the adapter can reach its target. For `email_*` adapters: optionally supply `variables` to override template fallback values. Missing required variables or type mismatches return 422 BEFORE any provider call. Requires the `destinations:write` scope.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Synthetic test event dispatched. Body reports the adapter's classification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "classification": { "type": "string", "enum": [ "success", "transient_failure", "permanent_failure", "rate_limited" ] }, "error_code": { "type": "string" }, "error_message": { "type": "string" }, "response_summary": {} }, "required": [ "ok", "classification" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/v1/routes": { "get": { "security": [ { "ApiKeyAuth": [ "routes:read" ] } ], "tags": [ "routes" ], "summary": "List routes.", "description": "Returns the workspace's routes in `created_at DESC` order. Echo `next_cursor` from this response into the `cursor` query param to fetch the next page. The cursor is opaque — do not parse it.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paged list of routes in the calling key's workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "destination_id": { "type": "string" }, "workflow_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "priority": { "type": "integer" }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string" }, "mapping_json": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "destination_id", "workflow_id", "name", "status", "priority", "filter_rules_json", "mapping_version", "mapping_json", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" } } }, "post": { "security": [ { "ApiKeyAuth": [ "routes:write" ] } ], "tags": [ "routes" ], "summary": "Create a route.", "description": "Wires a source to a destination. `source_id` and `destination_id` MUST both belong to the calling key's workspace; a cross-workspace reference returns 400 `invalid-reference`. `workflow_id` is optional — when omitted, the handler resolves the source's default workflow. Requires an `Idempotency-Key` request header (1-255 chars).", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "minLength": 1 }, "destination_id": { "type": "string", "minLength": 1 }, "workflow_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000 }, "filter_rules_json": { "type": "string" }, "mapping_version": { "type": "string", "minLength": 1, "maxLength": 50 }, "mapping_json": { "type": "string" } }, "required": [ "source_id", "destination_id", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Idempotent replay. Body is bit-identical to the original 201 response. `Idempotent-Replayed: true` header is set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "destination_id": { "type": "string" }, "workflow_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "priority": { "type": "integer" }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string" }, "mapping_json": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "destination_id", "workflow_id", "name", "status", "priority", "filter_rules_json", "mapping_version", "mapping_json", "created_at", "updated_at" ] } } } }, "201": { "description": "Route created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "destination_id": { "type": "string" }, "workflow_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "priority": { "type": "integer" }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string" }, "mapping_json": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "destination_id", "workflow_id", "name", "status", "priority", "filter_rules_json", "mapping_version", "mapping_json", "created_at", "updated_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v1/routes/{id}": { "get": { "security": [ { "ApiKeyAuth": [ "routes:read" ] } ], "tags": [ "routes" ], "summary": "Get a route by id.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Route detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "destination_id": { "type": "string" }, "workflow_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "priority": { "type": "integer" }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string" }, "mapping_json": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "destination_id", "workflow_id", "name", "status", "priority", "filter_rules_json", "mapping_version", "mapping_json", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } }, "patch": { "security": [ { "ApiKeyAuth": [ "routes:write" ] } ], "tags": [ "routes" ], "summary": "Update a route (partial).", "description": "Partial update. `destination_id`, when supplied, is re-validated against the route's workspace. `source_id` is NOT patchable. To soft-delete a route use `DELETE /v1/routes/{id}` — that endpoint stamps a dedicated audit row.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000 }, "destination_id": { "type": "string", "minLength": 1 }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string", "minLength": 1, "maxLength": 50 }, "mapping_json": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Route updated (or idempotent replay).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "destination_id": { "type": "string" }, "workflow_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "priority": { "type": "integer" }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string" }, "mapping_json": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "destination_id", "workflow_id", "name", "status", "priority", "filter_rules_json", "mapping_version", "mapping_json", "created_at", "updated_at" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "delete": { "security": [ { "ApiKeyAuth": [ "routes:write" ] } ], "tags": [ "routes" ], "summary": "Soft-delete a route.", "description": "Flips status to `revoked`. Future fanout skips revoked routes; in-flight delivery_jobs already on the queue still execute. Idempotent — deleting a revoked route is a no-op success.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Route soft-deleted (status → revoked). Idempotent: deleting an already-revoked route returns the cached row.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "destination_id": { "type": "string" }, "workflow_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "priority": { "type": "integer" }, "filter_rules_json": { "type": [ "string", "null" ] }, "mapping_version": { "type": "string" }, "mapping_json": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "destination_id", "workflow_id", "name", "status", "priority", "filter_rules_json", "mapping_version", "mapping_json", "created_at", "updated_at" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/v1/events": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "events" ], "summary": "List events.", "description": "Returns a cursor-paginated page of `lead_events` for the caller's workspace, newest first. Filters: `source_id`, `destination_id`, `status` (`delivered|failed|pending`), `from`, `to` (ISO timestamps). Default limit 50, max 200.\n\nRequires a Pro, Agency, or Scale plan. Free/Starter callers receive a 403 RFC-9457 problem document with type `https://docs.leadrails.dev/errors/plan-required`.\n\nInformational scope: `events:read`. v1 ships wildcard scopes (`['*']`); fine-grained scope enforcement lands in v1.1.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "source_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "destination_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "Paginated event list scoped to the caller's workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": "string" }, "schema_version": { "type": "string" }, "idempotency_key": { "type": "string" }, "normalized_status": { "type": "string", "enum": [ "pending", "normalized", "failed" ] }, "received_at": { "type": "string" }, "remote_ip": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "referer": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "site_url": { "type": [ "string", "null" ] }, "workflow_name": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "schema_version", "idempotency_key", "normalized_status", "received_at", "remote_ip", "user_agent", "referer", "origin", "site_url", "workflow_name" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" } } } }, "/v1/events/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "events" ], "summary": "Get a single event by id.", "description": "Returns one event in the caller's workspace. Events belonging to another workspace return 404 (existence is hidden).\n\nRequires a Pro, Agency, or Scale plan. Free/Starter callers receive a 403 RFC-9457 problem document with type `https://docs.leadrails.dev/errors/plan-required`.\n\nInformational scope: `events:read`. v1 ships wildcard scopes (`['*']`); fine-grained scope enforcement lands in v1.1.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Single-event projection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "source_id": { "type": "string" }, "schema_version": { "type": "string" }, "idempotency_key": { "type": "string" }, "normalized_status": { "type": "string", "enum": [ "pending", "normalized", "failed" ] }, "received_at": { "type": "string" }, "remote_ip": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "referer": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "site_url": { "type": [ "string", "null" ] }, "workflow_name": { "type": "string" } }, "required": [ "id", "client_id", "source_id", "schema_version", "idempotency_key", "normalized_status", "received_at", "remote_ip", "user_agent", "referer", "origin", "site_url", "workflow_name" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/v1/events/{id}/delivery-jobs": { "get": { "security": [ { "ApiKeyAuth": [] } ], "tags": [ "events" ], "summary": "List delivery jobs for a single event.", "description": "Returns every delivery job fanned out from the given event at intake time (one per matching route), each with its full attempt history ordered by `attempt_number`. Events in another workspace return 404.\n\nRequires a Pro, Agency, or Scale plan. Free/Starter callers receive a 403 RFC-9457 problem document with type `https://docs.leadrails.dev/errors/plan-required`.\n\nInformational scope: `events:read`. v1 ships wildcard scopes (`['*']`); fine-grained scope enforcement lands in v1.1.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "All delivery jobs fanned out from the given event, with attempt history embedded on each job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "client_id": { "type": "string" }, "route_id": { "type": "string" }, "destination_id": { "type": "string" }, "adapter_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "enqueued", "processing", "retrying", "delivered", "failed", "skipped" ] }, "attempt_count": { "type": "integer" }, "max_attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ] }, "last_error_code": { "type": [ "string", "null" ] }, "last_error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "delivered_at": { "type": [ "string", "null" ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string" }, "event_id": { "type": "string" }, "destination_id": { "type": "string" }, "adapter_type": { "type": "string" }, "attempt_number": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "transient_failure", "permanent_failure", "rate_limited" ] }, "request_summary_json": { "type": [ "string", "null" ] }, "response_summary_json": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "job_id", "event_id", "destination_id", "adapter_type", "attempt_number", "status", "request_summary_json", "response_summary_json", "error_code", "error_message", "started_at", "finished_at" ] } } }, "required": [ "id", "event_id", "client_id", "route_id", "destination_id", "adapter_type", "status", "attempt_count", "max_attempts", "next_attempt_at", "last_error_code", "last_error_message", "created_at", "updated_at", "delivered_at", "attempts" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } } }, "webhooks": {} }