{ "openapi": "3.1.0", "info": { "title": "maxclicks Public API", "version": "1.1.0", "summary": "The official REST API for the maxclicks email, CRM, and automation platform.", "description": "The maxclicks Public API connects customer data to prepared audiences, emails, and journeys. Version 1.1.0 is served under /v1. Schemas, attributes, template content, broadcast content, domains, senders, topics, and keys are authored in the app. This specification documents 58 functional operations; PATCH/DELETE /events/{id} are immutable guards that always return 405.\n\nAuthenticated operations use a Bearer API key and the owner's space permissions. Results use data, optionally warnings and pagination. Standard failures use error.type/code/message and optional issues. Event batch abort is a 422 data result, and an unresolved idempotency persistence failure may omit error.type.\n\nSeventeen operations support Idempotency-Key, as declared by their header parameter. Keep the same calling key, method, path, and body on retries. Recorded results include errors and webhook secrets; completed records are retained for 24 hours, while unresolved operations need reconciliation. Event acceptance instead uses eventId, and event identity changes use operationId plus a per-alias revision.\n\nHTTP acceptance does not imply finished downstream work. Events return a durable receipt and have a separate readiness endpoint; record deletion returns a pollable operation status; workflow triggers create a run; broadcast sends schedule work. Existing SDK/CLI/MCP sources wrap an earlier contract, so use this specification or direct HTTP for newer capabilities.\n\nAPI request limits are read=100/second, write=25/second, ai=10/minute per key. Event admission also has shared occurrence/backlog/receipt caps. Retry-After can be a delay in seconds or an HTTP date. Body size is limited to 10 MB; normalized event input is limited to 256 KiB. Offset traversal is capped at 10,000; ready events use cursors over a maximum 90-day query window.", "contact": { "name": "maxclicks", "url": "https://maxclicks.ai", "email": "info@maxclicks.ai" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "externalDocs": { "description": "Developer documentation", "url": "https://docs.maxclicks.ai" }, "servers": [ { "url": "https://api.maxclicks.ai/v1", "description": "Production" }, { "url": "https://api-stage.maxclicks.ai/v1", "description": "Staging" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Meta", "description": "Identify the calling API key." }, { "name": "Schemas", "description": "Manage the space's schemas (contact, object, event)." }, { "name": "Attributes", "description": "Read a schema's attributes. Attributes are authored in the app." }, { "name": "Records", "description": "Keep stored contact and object data current, inspect consent history, and track deletion to completion." }, { "name": "Suppressions", "description": "Manage the email do-not-contact list. Requires an admin key." }, { "name": "Events", "description": "Accept durable business events, inspect readiness, and bind anonymous source identities to contacts." }, { "name": "Domains", "description": "Read sending domains and their DNS verification status. Domains are added and verified in the app." }, { "name": "Senders", "description": "Read saved sender profiles configured in the app." }, { "name": "Topics", "description": "Read communication topics configured in the app." }, { "name": "Segments", "description": "Generate and manage AI-defined contact filters." }, { "name": "Broadcasts", "description": "Schedule, send, and measure mass emails. Broadcasts are authored in the app." }, { "name": "Templates", "description": "Send stored message templates. Templates are authored in the app." }, { "name": "Webhooks", "description": "Manage outgoing webhooks." }, { "name": "Workflows", "description": "Trigger published journeys, pause execution, and inspect runs and paged step history." }, { "name": "Forms", "description": "Public form submission and double opt-in confirmation." }, { "name": "Emails", "description": "Public email recipient actions." } ], "paths": { "/me": { "get": { "tags": [ "Meta" ], "summary": "Identify the calling API key", "description": "Returns the key metadata, its owning user, the bound space (if any), and the caller's role. Works for space-unbound keys, in which case `space` and `role` are null.\n", "operationId": "meta.me", "responses": { "200": { "description": "The identity of the calling key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/schemas": { "get": { "tags": [ "Schemas" ], "summary": "List schemas", "description": "Lists the space's schemas, optionally filtered by type.", "operationId": "schemas.list", "parameters": [ { "name": "type", "in": "query", "description": "Filter by one or more schema types. Repeat the parameter to pass several.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaType" } } }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of schemas.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Schema" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/schemas/{schema}": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" } ], "get": { "tags": [ "Schemas" ], "summary": "Get a schema", "description": "Fetches a single schema by id or slug.", "operationId": "schemas.get", "responses": { "200": { "description": "The schema.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Schema" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/schemas/{schema}/attributes": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" } ], "get": { "tags": [ "Attributes" ], "summary": "List attributes", "description": "Lists base attributes first, then custom attributes. Base ids use base: and have null sequence and timestamps. definition.type uses the documented stored/evaluated types; aggregate is definition.valueSource.type, not a top-level type. Only definitions with type other than evaluated and no valueSource are writable. Definition metadata can include auto-fill settings, aggregate source configuration, or evaluated target/reference descriptions; generated expressions are excluded. Record GET/list does not expand evaluated or aggregate values. Attribute authoring is available in the app, not through public v1.", "operationId": "attributes.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of attributes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/schemas/{schema}/records": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" } ], "get": { "tags": [ "Records" ], "summary": "List records", "description": "Lists stored contact or object records, ordered by createdAt ascending then id ascending. Custom values are flattened at the top level alongside platform fields. Evaluated and aggregate attributes are not expanded. This endpoint accepts limit/offset only; it has no ad-hoc search, time filter, include, or trait-expansion query. Traversal is capped; pagination.hasMore can be false when totalCount exceeds the reachable window.", "operationId": "records.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of records.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Records" ], "summary": "Create a record", "description": "Strictly creates one contact or object record (never updates an existing one). Any `id` in the body is ignored. `source` is forced to `api`. If the schema has an AI auto-fill attribute, credits are checked first. Supports `Idempotency-Key`. Errors: `schema_not_found`, `identifier_conflict` (409), `insufficient_credits` (402).\n", "operationId": "records.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordInput" }, "example": { "email": "sarah@example.com", "firstName": "Sarah" } } } }, "responses": { "201": { "description": "The created record.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/schemas/{schema}/records/upsert": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" } ], "post": { "tags": [ "Records" ], "summary": "Upsert a record", "description": "Creates or updates a contact or object. An explicit id selects that exact record or returns record_not_found. Otherwise contact matching uses userId first; email can match only a contact without userId; phone can match only a contact without userId or email. Objects match by externalId. Per-field identifier collisions may be skipped and reported in warnings; inspect the returned record. Returns 201 for creation or 200 for update. Any writable AI auto-fill attribute on the schema triggers the up-front credit check. Supports Idempotency-Key. Required writable fields without a value/default can fail with required_attribute_missing (400, issues names the key).", "operationId": "records.upsert", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordInput" }, "example": { "userId": "customer_1042", "email": "sarah@example.com", "firstName": "Sarah" } } } }, "responses": { "200": { "description": "The updated record.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEnvelope" } } } }, "201": { "description": "The created record.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/schemas/{schema}/records/{id}": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" }, { "$ref": "#/components/parameters/RecordIdParam" } ], "get": { "tags": [ "Records" ], "summary": "Get a record", "operationId": "records.get", "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Reads one contact or object in this schema. Stored custom values and platform fields are flattened; evaluated and aggregate attributes are not expanded. There is no include/expand query. Missing schema or record returns 404." }, "patch": { "tags": [ "Records" ], "summary": "Update a record", "description": "Partially updates a record. The path id overrides any body id. Explicit null clears a nullable field; omit a field to preserve it. Non-writable evaluated/aggregate keys are not accepted as stored inputs. Normalization and skipped per-field identity updates can produce warnings. The endpoint does not use Idempotency-Key. Errors: schema_not_found, record_not_found, identifier_conflict, or required_attribute_missing (400, issues names the missing key).", "operationId": "records.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordInput" }, "example": { "firstName": "Sarah" } } } }, "responses": { "200": { "description": "The updated record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Records" ], "summary": "Delete a record", "operationId": "records.delete", "responses": { "200": { "description": "Deletion operation status; pending is not completed erasure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordDeletionStatus" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Requests durable deletion of a contact or object. The response is an operationId/status/message object, not {id,deleted}. The workspace is closed for conflicting work while data and external resources are removed. Poll GET /record-deletions/{operationId} until status=completed; blocked requires reconciliation of unresolved work. The current handler returns HTTP 200 even when status=pending, so do not use HTTP status alone as proof of erasure. An unknown record returns 404 record_not_found. This endpoint does not use Idempotency-Key." } }, "/schemas/{schema}/records/{id}/audit-trail": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" }, { "$ref": "#/components/parameters/RecordIdParam" } ], "get": { "tags": [ "Records" ], "summary": "List a contact's audit trail", "description": "Lists the consent and communication audit trail for a contact, newest first. Contact schemas only. Errors: `schema_not_found`, `record_not_found`.\n", "operationId": "records.auditTrail", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Filter by communication channel.", "schema": { "$ref": "#/components/schemas/CommunicationChannel" } }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of audit-trail entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditTrailEntry" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/suppressions": { "get": { "tags": [ "Suppressions" ], "summary": "List suppressions", "description": "Lists suppressions for the caller's space, newest first. Includes global suppressions (not space-scoped) alongside space-scoped ones, since both block sends to the caller's contacts. Requires an admin key.\n", "operationId": "suppressions.list", "parameters": [ { "name": "identifier", "in": "query", "required": false, "description": "Filter to the suppression(s) for one email address.", "schema": { "type": "string", "format": "email" } }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of suppressions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Suppressions" ], "summary": "Create a suppression", "description": "Suppresses an email identifier for the space. Requires an admin key. Not Idempotency-Key aware. Error: `suppression_already_exists` (409; `manual` and `legal` are distinct reasons).\n", "operationId": "suppressions.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionInput" } } } }, "responses": { "201": { "description": "The created suppression.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Suppression" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/suppressions/batch": { "post": { "tags": [ "Suppressions" ], "summary": "Batch-create suppressions", "description": "Bulk-creates 1 to 100 suppressions in one call. Each item is validated and processed independently: an existing suppression for the same identifier and reason returns `exists` rather than failing the item. Requires an admin key. Supports `Idempotency-Key`. Always responds `200`.\n", "operationId": "suppressions.batchCreate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionBatchCreateRequest" } } } }, "responses": { "200": { "description": "Per-item results and a summary.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SuppressionBatchCreateResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/contacts/suppressions/batch-remove": { "post": { "tags": [ "Suppressions" ], "summary": "Batch-delete suppressions", "description": "Bulk-removes 1 to 100 suppressions by id in one call. Each id is gated exactly like the single delete (must belong to the caller's space; reason must be `manual` or `legal`). Requires an admin key. Supports `Idempotency-Key`. Always responds `200`.\n", "operationId": "suppressions.batchDelete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionBatchDeleteRequest" } } } }, "responses": { "200": { "description": "Per-item results and a summary.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SuppressionBatchDeleteResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/contacts/suppressions/{id}": { "parameters": [ { "$ref": "#/components/parameters/SuppressionIdParam" } ], "delete": { "tags": [ "Suppressions" ], "summary": "Delete a suppression", "description": "Deletes a manual or legal suppression. Requires admin permission and supports Idempotency-Key. Missing suppression returns suppression_not_found; automatic provider bounce/complaint suppressions cannot be removed through this endpoint. Removing a suppression is separate from granting contact marketing consent.", "operationId": "suppressions.delete", "responses": { "200": { "description": "The suppression was removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedEnvelope" } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/events": { "get": { "tags": [ "Events" ], "summary": "List events", "description": "Lists only ready business events for one event schema. Results are ordered by occurredAt descending, then id descending. The time filter is inclusive from and exclusive to; defaults are the seven days before now. A range wider than 90 days is clamped with a warning. Uses cursor pagination: no offset and no totalCount. Pending, failed, and outcome_unknown acceptances are absent; use events.status to inspect them. Invalid times return 400 invalid_time_range; malformed cursors return 400 invalid_cursor. Events are read from the operational event store, not the analytics archive.", "operationId": "events.list", "parameters": [ { "name": "schema", "in": "query", "required": true, "description": "The event schema id or slug.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the time range (ISO 8601). Defaults to 7 days before `to`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "End of the time range (ISO 8601). Defaults to now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous page's `pagination.nextCursor`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, capped at 200.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A cursor page of events.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "pagination": { "$ref": "#/components/schemas/CursorPagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/events/{schema}": { "x-note": "PATCH and DELETE /events/{id} are immutable guards that always return 405 events_immutable. They are not mutation operations. There is no GET /events/{id}; use GET /events/{schema}/{id}/status for an acceptance receipt.", "post": { "tags": [ "Events" ], "summary": "Fire an event", "description": "Durably accepts one business event and returns 202 with its immutable acceptance receipt. Missing AI auto-fill fields are prepared asynchronously; readinessAtAcceptance is pending or ready. An accepted event is visible to event lists and consumers only once ready. Supply a stable eventId and retry the same normalized payload and occurredAt to recover the original receipt with isDuplicate=true. Changed input under the same eventId returns 409 event_id_conflict; erased occurrences return 409 event_erased. Idempotency-Key is not used. The normalized event input is limited to 256 KiB. occurredAt must be within the previous 366 days or five minutes into the future. contactId and objectId are optional, mutually exclusive explicit subjects in this space. Event admission has separate rate, backlog, and receipt-storage limits in addition to the API write bucket.", "operationId": "events.fire", "parameters": [ { "name": "schema", "in": "path", "required": true, "description": "The event schema id or slug.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventInput" }, "example": { "eventId": "order_1042_paid", "amount": 42 } } } }, "responses": { "202": { "description": "Durable event acceptance receipt; inspect readiness separately.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FireResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/events/{schema}/batch": { "parameters": [ { "$ref": "#/components/parameters/SchemaParam" } ], "post": { "tags": [ "Events" ], "summary": "Fire a batch of events", "description": "Accepts 1–500 events of one schema. With onError=continue (default), each event commits independently; inspect every result, including failures, even on HTTP 200. Accepted items include their immutable receipt. Admission failures include retryAfterMilliseconds. With onError=abort, a validation or admission failure rolls back new acceptances in that transaction, marks earlier accepted results rolled_back, and returns HTTP 422 with data.results, data.summary, and data.failedIndex. Later items are not attempted. Existing receipts encountered as duplicates remain existing occurrences. A 422 abort response is a business-result data envelope, not the standard error envelope. Each item uses eventId deduplication; Idempotency-Key is not used. Individual events retain the 256 KiB and occurredAt limits, and the whole HTTP body remains limited to 10 MB.", "operationId": "events.fireBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBatchRequest" }, "example": { "events": [ { "eventId": "order_1042_paid", "amount": 42 } ], "onError": "continue" } } } }, "responses": { "200": { "description": "Per-item results and a summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BatchFireResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Batch aborted; earlier new acceptances were rolled back. Inspect data.results and data.failedIndex.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BatchFireResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/domains": { "get": { "tags": [ "Domains" ], "summary": "List domains", "description": "Items omit `records` (unlike `domains.get`); call `domains.get` for DNS records.", "operationId": "domains.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of domains.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/domains/{id}": { "parameters": [ { "$ref": "#/components/parameters/DomainIdParam" } ], "get": { "tags": [ "Domains" ], "summary": "Get a domain", "description": "Includes live-checked `records`. Error: `domain_not_found`.", "operationId": "domains.get", "responses": { "200": { "description": "The domain.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/senders": { "get": { "tags": [ "Senders" ], "summary": "List senders", "operationId": "senders.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of senders.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sender" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/topics": { "get": { "tags": [ "Topics" ], "summary": "List topics", "operationId": "topics.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of topics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Topic" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/topics/{id}": { "parameters": [ { "$ref": "#/components/parameters/TopicIdParam" } ], "get": { "tags": [ "Topics" ], "summary": "Get a topic", "description": "Error: `topic_not_found`.", "operationId": "topics.get", "responses": { "200": { "description": "The topic.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Topic" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/segments": { "get": { "tags": [ "Segments" ], "summary": "List segments", "operationId": "segments.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of segments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Segments" ], "summary": "Create a segment", "description": "Generates a contact filter from a natural-language `requirements` prompt (every create is an AI call, in the `ai` rate bucket; credits are checked first) and persists it in one call. The response includes a live `matchingCount`. The generated expression is never returned. Errors: `schema_not_found`, `invalid_segment`, `segment_generation_failed` (422), `segment_name_conflict` (409), `insufficient_credits` (402).\n", "operationId": "segments.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentCreate" }, "example": { "name": "Engaged customers", "contactSchema": "customers", "requirements": "Contacts who have opened an email in the last 30 days." } } } }, "responses": { "201": { "description": "The created segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/segments/{id}": { "parameters": [ { "$ref": "#/components/parameters/SegmentIdParam" } ], "get": { "tags": [ "Segments" ], "summary": "Get a segment", "description": "Error: `segment_not_found`.", "operationId": "segments.get", "responses": { "200": { "description": "The segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Segments" ], "summary": "Delete a segment", "description": "Errors: `segment_not_found`, `segment_integration_owned` (403), `segment_in_use` (409, used as a broadcast audience, workflow trigger, or webhook condition, or referenced by other entities).\n", "operationId": "segments.delete", "responses": { "200": { "description": "The segment was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedEnvelope" } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/segments/{id}/count": { "parameters": [ { "$ref": "#/components/parameters/SegmentIdParam" } ], "get": { "tags": [ "Segments" ], "summary": "Count a segment's matching contacts", "description": "Error: `segment_not_found`.", "operationId": "segments.count", "responses": { "200": { "description": "The live matching count and the schema's total contact count.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "count", "total" ], "properties": { "count": { "type": "integer", "description": "Contacts currently matching the segment." }, "total": { "type": "integer", "description": "All contacts of the segment's schema." } } }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/segments/{id}/contacts": { "parameters": [ { "$ref": "#/components/parameters/SegmentIdParam" } ], "get": { "tags": [ "Segments" ], "summary": "List a segment's matching contacts", "description": "Paginated contact records currently matching the segment. `limit` is additionally hard-capped at `config.segment.maximumContactsPageSize` (100) regardless of the requested value. Error: `segment_not_found`.\n", "operationId": "segments.listContacts", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of matching contacts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/broadcasts": { "get": { "tags": [ "Broadcasts" ], "summary": "List broadcasts", "operationId": "broadcasts.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of broadcasts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/broadcasts/{id}": { "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "get": { "tags": [ "Broadcasts" ], "summary": "Get a broadcast", "description": "Error: `broadcast_not_found`.", "operationId": "broadcasts.get", "responses": { "200": { "description": "The broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Broadcasts" ], "summary": "Update a broadcast", "description": "Updates name, description, scheduledFor, and/or audience before sending starts. At least one field is required. Audience accepts all or an existing segment for the broadcast contact schema; custom filter generation and content authoring are not available here. Concurrent changes or a planning claim can return 409 broadcast_changed; a started send cannot be edited. Supports Idempotency-Key. Cancel/stop/resume/redrive controls are available through app workflows, not this public endpoint.", "operationId": "broadcasts.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastUpdate" }, "example": { "name": "September customer update" } } } }, "responses": { "200": { "description": "The updated broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/broadcasts/{id}/send": { "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "post": { "tags": [ "Broadcasts" ], "summary": "Send a broadcast", "description": "Schedules a prepared broadcast immediately or for scheduledFor and returns 202. It does not wait for planning or delivery. Content is authored in the app. A pre-existing send schedule, started send, or active planning claim returns 409 broadcast_already_sending. Readiness issues return 422 broadcast_invalid with issues. Supports Idempotency-Key. Read runs to inspect recipients; HTTP acceptance is not proof every recipient received email.", "operationId": "broadcasts.send", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastSendRequest" }, "example": {} } } }, "responses": { "202": { "description": "The broadcast was accepted for sending.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/broadcasts/{id}/runs": { "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "get": { "tags": [ "Broadcasts" ], "summary": "List a broadcast's runs", "description": "One reduced run record per recipient contact. Error: `broadcast_not_found`.", "operationId": "broadcasts.listRuns", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of broadcast runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastRun" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/broadcasts/{id}/metrics": { "parameters": [ { "$ref": "#/components/parameters/BroadcastIdParam" } ], "get": { "tags": [ "Broadcasts" ], "summary": "Get a broadcast's aggregated email metrics", "description": "`email` is omitted entirely when the broadcast has no email content yet. Error: `broadcast_not_found`.\n", "operationId": "broadcasts.getMetrics", "responses": { "200": { "description": "Aggregated send/open/click/bounce metrics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BroadcastMetricsResponse" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "operationId": "templates.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates/{id}": { "parameters": [ { "$ref": "#/components/parameters/TemplateIdParam" } ], "get": { "tags": [ "Templates" ], "summary": "Get a template", "description": "Error: `template_not_found`.", "operationId": "templates.get", "responses": { "200": { "description": "The template.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Template" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates/{templateId}/send": { "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "The template id.", "schema": { "type": "string" } } ], "post": { "tags": [ "Templates" ], "summary": "Send a template", "description": "Renders stored template content and sends to the recipient resolved from data. Read expectedDataRepresentation and send every required key; referenced records are upserted before rendering and configured attribute expansions are applied. Available credits and email allowance are required. There is no subject/body replacement or preview execution parameter. Supports Idempotency-Key. Pre-send validation/eligibility failures use request errors (email_limit_reached, sending_disabled, template_not_sendable, domain_not_verified, invalid_data, marketing_requires_contact, recipient_not_subscribed, recipient_suppressed). The result exposes emailId, status, and error. status=sent means the provider accepted the durable send attempt, not inbox delivery. HTTP 200 status=failed collapses retryable refusals, terminal refusals, cancellation, and unknown provider outcomes into one public state with a generic error. It does not prove non-delivery or establish whether another send is safe. Preserve emailId and the original operation key and reconcile in the app; do not create a new key to force a second send. A stored template without an email channel can return null status/emailId/error.", "operationId": "templates.send", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateSendRequest" }, "example": { "data": { "contact": { "email": "sarah@example.com" } } } } } }, "responses": { "200": { "description": "The send was processed.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TemplateSendResponse" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "operationId": "webhooks.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of webhooks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Creates an outgoing webhook and returns signatureVerificationSecret. Store the secret securely; normal GET/list responses omit it. Supports Idempotency-Key, including replay of the original secret-bearing response. A custom filter generates through AI from requirements, uses the ai rate bucket and credits, and exposes only its description. Schema accepts an id or slug and must match the trigger. Deliveries retry network failures, HTTP 408, 429, and 5xx with bounded backoff; deduplicate their stable X-Webhook-ID. Delivery URL and secret are captured when enqueued, so queued deliveries can use earlier settings. Errors include invalid_webhook, schema_not_found, segment_not_found, and insufficient_credits.", "operationId": "webhooks.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "example": { "url": "https://example.com/webhooks/maxclicks", "trigger": "contact upserted", "schemaId": "customers", "condition": { "type": "none" } } } } }, "responses": { "201": { "description": "The created webhook, including its signing secret.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/webhooks/{id}": { "parameters": [ { "$ref": "#/components/parameters/WebhookIdParam" } ], "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook", "operationId": "webhooks.get", "responses": { "200": { "description": "The webhook.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Updates url, emailEventTypes, condition, and/or status (live or paused); at least one is required. Trigger and schema cannot change. A custom filter uses AI and credits. Supports Idempotency-Key. Setting live clears the circuit-breaker count. Already enqueued deliveries keep their captured URL and signing secret. Queued deliveries observed while paused are suppressed rather than held for later replay. Integration-owned webhooks cannot be changed.", "operationId": "webhooks.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" }, "example": { "status": "live" } } } }, "responses": { "200": { "description": "The updated webhook.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Deletes a webhook. Supports Idempotency-Key. Missing webhooks return webhook_not_found; integration-owned webhooks cannot be deleted.", "operationId": "webhooks.delete", "responses": { "200": { "description": "The webhook was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedEnvelope" } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/webhooks/{id}/rotate-secret": { "parameters": [ { "$ref": "#/components/parameters/WebhookIdParam" } ], "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook secret", "description": "Creates a new signing secret and returns it with the webhook id and updatedAt. Store it securely. Supports Idempotency-Key: retry the same key to recover the original secret-bearing response instead of rotating again. Normal reads never reveal the secret. Already enqueued deliveries retain their captured secret and URL, including retries; keep the previous verification secret until those deliveries drain. Integration-owned webhooks cannot be rotated.", "operationId": "webhooks.rotateSecret", "responses": { "200": { "description": "The new signing secret.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RotatedWebhookSecret" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/workflows": { "get": { "tags": [ "Workflows" ], "summary": "List workflows", "operationId": "workflows.list", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of workflows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workflows/{id}": { "x-note": "This path also serves `POST /workflows/{workflowStepReference}` (workflows.trigger), registered on the router as a catch-all single-segment POST beneath the more specific routes (list/get/pause/unpause/delete/runs). OpenAPI models both under one templated path item, matching the `/events/{schema}` merge above.\n", "get": { "tags": [ "Workflows" ], "summary": "Get a workflow", "description": "Error: `workflow_not_found`.", "operationId": "workflows.get", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The workflow id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workflow.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workflow" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Workflows" ], "summary": "Trigger a workflow", "description": "Starts a run at a published, unpaused incoming-webhook step. The path id is that step’s reference id, not the workflow id. Send the workflow’s configured JSON input as the body. HTTP 200 with data={} confirms run creation, not workflow completion. Errors use the standard JSON error envelope: workflow_step_not_found (404), invalid_request_body (400), or a server error for an invalid configured schema. Supports Idempotency-Key. Workflow authoring, run cancellation, and retry/redrive are not exposed by this public endpoint.", "operationId": "workflows.trigger", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The incoming-webhook step's reference id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Per-workflow-step payload, validated against the step's JSON schema.", "additionalProperties": true } } } }, "responses": { "200": { "description": "The workflow run was started.", "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "description": "`data` is an empty object.", "properties": { "data": { "type": "object" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } } } }, "/workflows/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/WorkflowIdParam" } ], "post": { "tags": [ "Workflows" ], "summary": "Pause a workflow", "description": "Pauses the workflow: new triggers and further execution of existing runs are blocked. An external effect already in flight may complete. Supports Idempotency-Key. Error: workflow_not_found.", "operationId": "workflows.pause", "responses": { "200": { "description": "The paused workflow.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workflow" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/workflows/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/WorkflowIdParam" } ], "post": { "tags": [ "Workflows" ], "summary": "Unpause a workflow", "description": "Unpauses the workflow so eligible paused work can continue. This does not publish unpublished edits or redrive terminal failed runs. Supports Idempotency-Key. Error: workflow_not_found.", "operationId": "workflows.unpause", "responses": { "200": { "description": "The unpaused workflow.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workflow" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } }, "headers": { "Idempotent-Replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Operation-Id": { "schema": { "type": "string" }, "description": "Operation identifier for reconciliation." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyUnknownError" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyParam" } ] } }, "/workflows/{id}/runs": { "parameters": [ { "$ref": "#/components/parameters/WorkflowIdParam" } ], "get": { "tags": [ "Workflows" ], "summary": "List a workflow's runs", "description": "Lists runs newest first. Each run embeds at most its latest 100 history entries, ascending within that window. Use workflows.getRun with nextHistoryBeforeIndex to read earlier history. Error: workflow_not_found.", "operationId": "workflows.listRuns", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" } ], "responses": { "200": { "description": "A page of workflow runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workflows/{id}/runs/{runId}": { "parameters": [ { "$ref": "#/components/parameters/WorkflowIdParam" }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run id.", "schema": { "type": "string" } } ], "get": { "tags": [ "Workflows" ], "summary": "Get a workflow run", "description": "Returns public run status and a window of at most 100 step-history records, ordered by index ascending within the returned window. The initial window contains the latest records. To read older history, pass nextHistoryBeforeIndex as history_before until it is null. status is running while a current step exists; otherwise failed if the run has a failed step, or completed. failureReason comes from the returned window and can be null even for a failed run whose failure is older. No internal step graph, handling state, or input/output data is returned. Errors: workflow_not_found, workflow_run_not_found.", "operationId": "workflows.getRun", "responses": { "200": { "description": "The workflow run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkflowRun" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "history_before", "in": "query", "required": false, "description": "Return step-history indices strictly below this non-negative safe integer. Use the previous nextHistoryBeforeIndex; omit for the latest 100 entries.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ] } }, "/forms/{formId}/submit": { "parameters": [ { "$ref": "#/components/parameters/FormIdParam" } ], "post": { "tags": [ "Forms" ], "summary": "Submit a form", "description": "Public, unauthenticated form submission (the tenant is derived from the form, not an API key). Validates required fields, CAPTCHA, and consent, then upserts the contact or (for double opt-in, when the visitor opted in to email) stores a pending record and emails a confirmation link. A declined-consent submission always goes through the direct path even on a double opt-in form. Rate limits: per IP 10/60s and per form 120/60s (both fail open if Redis is down), plus a separate per-recipient/per-form cap on confirmation emails. Error: `rate_limit_exceeded`.\n", "operationId": "forms.submit", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormSubmission" }, "example": { "contact": { "email": "sarah@example.com", "firstName": "Sarah" }, "emailMarketingConsent": false } } } }, "responses": { "200": { "description": "The submission was accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FormSubmissionResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/forms/{formId}/confirm/{token}": { "parameters": [ { "$ref": "#/components/parameters/FormIdParam" }, { "name": "token", "in": "path", "required": true, "description": "The single-use double opt-in token from the confirmation email.", "schema": { "type": "string" } } ], "get": { "tags": [ "Forms" ], "summary": "Confirm a double opt-in", "description": "Public browser navigation target for the double opt-in email link. Redeems the token, upserts the confirmed contact, and always redirects (302) to the hosted result page. Every failure path (missing/expired token, unpublished form) also redirects to a \"failed\" landing page rather than returning a JSON error. Same rate limits as `forms.submit`.\n", "operationId": "forms.confirmDoubleOptIn", "security": [], "responses": { "302": { "description": "Redirect to the hosted confirmation result page.", "headers": { "Location": { "description": "The result page URL.", "schema": { "type": "string", "format": "uri" } } } } } } }, "/emails/{emailId}/unsubscribe": { "parameters": [ { "name": "emailId", "in": "path", "required": true, "description": "The id of the sent email.", "schema": { "type": "string" } } ], "post": { "tags": [ "Emails" ], "summary": "One-click unsubscribe", "description": "Public RFC 8058 one-click unsubscribe target. Unsubscribes the linked contact from a topic or the whole email channel, then redirects (302) to the hosted result page. No rate limit at all on this endpoint.\n", "operationId": "emails.unsubscribeOneClick", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "List-Unsubscribe" ], "properties": { "List-Unsubscribe": { "type": "string", "const": "One-Click" } } } } } }, "responses": { "302": { "description": "Redirect to the hosted unsubscribe result page.", "headers": { "Location": { "description": "The result page URL.", "schema": { "type": "string", "format": "uri" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/events/{schema}/{id}/status": { "get": { "tags": [ "Events" ], "summary": "Get event readiness", "operationId": "events.status", "description": "Read the current readiness of an accepted event by its maxclicks event id, including pending, ready, failed, and outcome_unknown states. This is distinct from the immutable readinessAtAcceptance returned when firing or retrying the event. data contains raw acceptance values until preparation is ready. A missing event or event schema returns 404. Acceptance and readiness do not prove that a downstream workflow, webhook, or email completed.", "parameters": [ { "name": "schema", "in": "path", "required": true, "description": "Event schema id or slug.", "schema": { "type": "string", "example": "purchase-completed" } }, { "name": "id", "in": "path", "required": true, "description": "The maxclicks event id from the acceptance receipt, not your eventId.", "schema": { "type": "string", "example": "ev_BcwDvBUeSaSDILA5tHgpmU7I" } } ], "responses": { "200": { "description": "Current event readiness and accepted/prepared data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventStatus" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/event-identities": { "post": { "tags": [ "Events" ], "summary": "Bind an anonymous event identity", "operationId": "eventIdentities.identify", "description": "Binds or unbinds an anonymous browser identity to a contact using a server-held API key with write permission. An enabled contact track definition must match sourceId and subjectSchemaId in the space. Send contactId=null to remove the binding. All six body fields are required and unknown fields are rejected. Use a UUID operationId for replay of the same input; a changed body under that operationId returns 409. expectedAliasRevision is the last revision of this specific alias as a decimal string, or \"0\" for a new alias. Keep the returned identityRevision for the next change to that alias. Revision conflicts and erased aliases return 409; an unavailable source returns 403. Capacity is bounded at 100,000 aliases and 1,000,000 changes per space; exhausted capacity returns 429 without promising automatic recovery. Idempotency-Key is not used.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventIdentityInput" } } } }, "responses": { "200": { "description": "The committed identity revision.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventIdentityResult" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/record-deletions/{operationId}": { "get": { "tags": [ "Records" ], "summary": "Get record deletion status", "operationId": "records.getDeletion", "description": "Poll a record-deletion operation in the caller’s space. pending means cleanup is still in progress; blocked means unresolved work needs reconciliation and the workspace remains closed; completed confirms the deletion operation finished. A missing or out-of-scope operation returns 404. Preserve the operationId from records.delete.", "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "The full operationId returned by records.delete.", "schema": { "type": "string", "example": "delete:records:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" } } ], "responses": { "200": { "description": "Current deletion status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordDeletionStatus" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key sent as a bearer token in the `Authorization` header: `Authorization: Bearer `. The server also accepts the raw key without the `Bearer ` prefix, but clients should always send `Bearer`.\n" } }, "headers": { "IdempotentReplay": { "description": "Present and `true` when this response was replayed verbatim from a prior request that used the same `Idempotency-Key`.\n", "schema": { "type": "boolean" } } }, "parameters": { "LimitParam": { "name": "limit", "in": "query", "required": false, "description": "Page size. Clamped to 1..200 with a warning if out of range.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, "OffsetParam": { "name": "offset", "in": "query", "required": false, "description": "Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 10000 } }, "IdempotencyKeyParam": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.", "schema": { "type": "string", "maxLength": 256 } }, "SchemaParam": { "name": "schema", "in": "path", "required": true, "description": "A schema id or slug.", "schema": { "type": "string" } }, "RecordIdParam": { "name": "id", "in": "path", "required": true, "description": "The record's platform id.", "schema": { "type": "string" } }, "SuppressionIdParam": { "name": "id", "in": "path", "required": true, "description": "The suppression id.", "schema": { "type": "string" } }, "DomainIdParam": { "name": "id", "in": "path", "required": true, "description": "The domain id.", "schema": { "type": "string" } }, "TopicIdParam": { "name": "id", "in": "path", "required": true, "description": "The topic id.", "schema": { "type": "string" } }, "SegmentIdParam": { "name": "id", "in": "path", "required": true, "description": "The segment id.", "schema": { "type": "string" } }, "BroadcastIdParam": { "name": "id", "in": "path", "required": true, "description": "The broadcast id.", "schema": { "type": "string" } }, "TemplateIdParam": { "name": "id", "in": "path", "required": true, "description": "The template id.", "schema": { "type": "string" } }, "WebhookIdParam": { "name": "id", "in": "path", "required": true, "description": "The webhook id.", "schema": { "type": "string" } }, "WorkflowIdParam": { "name": "id", "in": "path", "required": true, "description": "The workflow id.", "schema": { "type": "string" } }, "FormIdParam": { "name": "formId", "in": "path", "required": true, "description": "The form id.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "The request was malformed or failed validation. Also covers `malformed_json` (body is not valid JSON) and, on list endpoints, `offset_too_large`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "The API key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks permission, or the space is out of scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The referenced resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The write conflicts with an existing resource or the resource's current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Insufficient credits (`insufficient_credits`) for an AI-generation call or a schema with AI auto-fill, or the space's email allowance is exhausted (`email_limit_reached`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnprocessableEntity": { "description": "The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry `error.issues`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "The rate limit was exceeded.", "headers": { "Retry-After": { "description": "Retry delay as HTTP-date or seconds when supplied. Event per-item admission failures report retryAfterMilliseconds inside the result instead.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "The request body exceeds the 10 MB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "The request used an unsupported content type, charset, or content encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IngestUnavailable": { "description": "A downstream event dependency is unavailable: the ingest pipeline (`ingest_unavailable`, on `events.fire`/`events.fireBatch`) or the ClickHouse-backed event archive (`event_archive_unavailable`, on `events.list`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "The API failed to process a valid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ErrorObject": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "api_error" ] }, "code": { "type": [ "string", "null" ], "description": "A stable machine-readable code, or null." }, "message": { "type": "string" }, "issues": { "type": "array", "description": "Present only for validation-gate failures that report more than one distinct problem at once (e.g. `broadcasts.send`'s `broadcast_invalid`).\n", "items": { "type": "string" } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorObject" } } }, "Warnings": { "type": "array", "description": "Non-fatal warnings accumulated while processing the request.", "items": { "type": "string" }, "example": [] }, "Pagination": { "type": "object", "required": [ "limit", "offset", "totalCount", "hasMore" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "totalCount": { "type": "integer" }, "hasMore": { "type": "boolean", "description": "True only when more rows exist AND offset + limit is below 10000. False can reflect the traversal cap even if totalCount is larger; it does not guarantee a full export." } } }, "CursorPagination": { "type": "object", "description": "Cursor pagination envelope, used only by `events.list`.", "required": [ "limit", "nextCursor", "hasMore" ], "properties": { "limit": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when there are no more rows." }, "hasMore": { "type": "boolean" } } }, "Deleted": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } } }, "DeletedEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } }, "RecordEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Record" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } }, "SchemaType": { "type": "string", "enum": [ "contact", "object", "event" ] }, "ContactSource": { "type": "string", "enum": [ "import", "api", "form", "manual", "workflow", "integration" ] }, "CommunicationChannel": { "type": "string", "enum": [ "email" ] }, "BadgeColor": { "type": "string", "description": "A display color for tags and topics.", "enum": [ "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose", "zinc" ] }, "SuppressionReason": { "type": "string", "description": "All possible suppression reasons on read. Only `manual` and `legal` can be created or removed through the API; the rest are system-applied (bounce, complaint, unsubscribe) and read-only.\n", "enum": [ "manual", "legal", "unsubscribed", "hard_bounce", "soft_bounce_consecutive", "spam_complaint" ] }, "SuppressionCreateReason": { "type": "string", "enum": [ "manual", "legal" ] }, "RoleName": { "type": "string", "enum": [ "admin", "non-paid admin", "member" ] }, "Me": { "type": "object", "required": [ "apiKey", "user", "space", "role" ], "properties": { "apiKey": { "type": "object", "required": [ "id", "name", "keyDisplay", "createdAt" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "keyDisplay": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "user": { "type": "object", "required": [ "id", "email", "name" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } } }, "space": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" } } }, "role": { "type": [ "object", "null" ], "properties": { "name": { "$ref": "#/components/schemas/RoleName" }, "label": { "type": "string" }, "description": { "type": "string" } } } } }, "Schema": { "type": "object", "required": [ "id", "type", "slug", "name", "namePlural", "description", "integrationVendorName", "attributeCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/SchemaType" }, "slug": { "type": "string" }, "name": { "type": "string" }, "namePlural": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "integrationVendorName": { "type": [ "string", "null" ] }, "attributeCount": { "type": "integer", "description": "Count of custom attribute rows only (base attributes excluded)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AttributeDefinition": { "type": "object", "description": "Attribute definition metadata. Stored definitions carry nullable; evaluated definitions use target=schema or json. An aggregate keeps a stored type and adds valueSource.type=aggregate; it is not writable. Writable stored fields have no valueSource. Optional autoFill uses mode=default with defaultValue, or mode=ai with optional prompt. Evaluated and aggregate values require app/runtime expansion and are not included in public record reads. Types url/email/phone/ref/object do not exist; use string formats and json as documented. Generated evaluated expressions are never returned.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "decimal", "boolean", "date time", "date only", "time only", "string array", "json", "evaluated" ] }, "nullable": { "type": "boolean", "description": "Present on every stored definition. Absent on `evaluated`." }, "multiLine": { "type": "boolean", "description": "On `type: string` only. Selects which `format` values are available." }, "format": { "type": "string", "description": "On `type: string` only. With `multiLine` false or absent: `plain text`, `email`, `phone` or `url`. With `multiLine: true`: `plain text` or `code`.\n" }, "jsonSchema": { "type": "object", "description": "On `type: json` only. A simplified JSON Schema, including for nested structures." }, "autoFill": { "type": "object", "description": "Stored field: mode default with defaultValue, or mode ai with optional prompt.", "additionalProperties": true }, "valueSource": { "type": "object", "description": "Aggregate metadata: type=aggregate; sourceKind=event|track; eventSchemaId/trackDefinitionId; specification(operation=count|sum|latest,valueProperty,dimensionProperty,filter,windowSeconds); cadenceSeconds,enabled,revision. Makes this stored type non-writable.", "additionalProperties": true }, "target": { "type": "string", "enum": [ "schema", "json" ], "description": "Evaluated only. schema requires schemaId,cardinality,requirements,queryDescriptionMarkdown,expressionReferences. json requires jsonSchema,requirements,descriptionMarkdown,expressionReferences,expressionOutput=json|query." }, "cardinality": { "type": "string", "enum": [ "one", "many" ] }, "schemaId": { "type": "string" } }, "additionalProperties": true }, "Attribute": { "type": "object", "required": [ "id", "key", "label", "description", "sequence", "definition", "integrationVendorName", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "A custom attribute id, or `base:` for platform base attributes." }, "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "sequence": { "type": [ "string", "null" ], "description": "Ordering value for custom attributes; null for base attributes." }, "definition": { "$ref": "#/components/schemas/AttributeDefinition" }, "integrationVendorName": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "EmailStatistics": { "type": "object", "required": [ "sent", "delivered", "bounced", "complained", "unsubscribed", "uniqueOpens", "uniqueClicks" ], "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "uniqueOpens": { "type": "integer" }, "uniqueClicks": { "type": "integer" } } }, "ContactRecord": { "type": "object", "description": "Contact record. Stored custom values are top-level; platform fields override colliding keys. Evaluated/aggregate values are not expanded by public record reads.", "required": [ "id", "schemaId", "schemaSlug", "source", "fullName", "firstName", "lastName", "avatarUrl", "userId", "email", "phone", "subscriptions", "topicIds", "notes", "tags", "emailStatistics", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "schemaId": { "type": "string" }, "schemaSlug": { "type": "string" }, "source": { "$ref": "#/components/schemas/ContactSource" }, "fullName": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationChannel" } }, "topicIds": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "emailStatistics": { "oneOf": [ { "$ref": "#/components/schemas/EmailStatistics" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "ObjectRecord": { "type": "object", "description": "Object record. Stored custom values are top-level; platform fields override colliding keys. Evaluated/aggregate values are not expanded by public record reads.", "required": [ "id", "schemaId", "schemaSlug", "externalId", "notes", "tags", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "schemaId": { "type": "string" }, "schemaSlug": { "type": "string" }, "externalId": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "Record": { "description": "Contact or object record with stored custom values and platform fields flattened at the top level. Public record reads do not expand evaluated or aggregate attribute values.", "oneOf": [ { "$ref": "#/components/schemas/ContactRecord" }, { "$ref": "#/components/schemas/ObjectRecord" } ] }, "RecordInput": { "type": "object", "description": "Input for creating, upserting, or updating a record. All fields are optional. For a contact schema the contact fields apply; for an object schema the object fields apply. Custom attribute keys are passed at the top level.\n", "properties": { "id": { "type": "string" }, "fullName": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationChannel" } }, "topicIds": { "type": "array", "items": { "type": "string" } }, "externalId": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "AuditTrailEntry": { "type": "object", "required": [ "id", "createdAt", "communicationChannel", "communicationTopicIds", "eventType", "state", "optInLevel", "actorType", "actorIdentifier", "context" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "communicationChannel": { "$ref": "#/components/schemas/CommunicationChannel" }, "communicationTopicIds": { "type": "array", "items": { "type": "string" } }, "eventType": { "type": "string", "enum": [ "email_verification_sent", "email_verified", "phone_verification_sent", "phone_verified", "subscribed", "unsubscribed", "topics_added", "topics_removed", "suppressed", "unsuppressed" ] }, "state": { "type": [ "string", "null" ], "enum": [ "subscribed", "not_subscribed", "unsubscribed", "pending", "invalid", "redacted", null ] }, "optInLevel": { "type": [ "string", "null" ], "enum": [ "single", "double", "unknown", null ] }, "actorType": { "type": "string", "enum": [ "contact", "admin", "system", "api" ] }, "actorIdentifier": { "type": [ "string", "null" ] }, "context": { "description": "Raw JSON context (consent text/version, IP, user agent, source URL, form id, timestamp). `ipAddress` and `userAgent` are stripped before being returned.\n" } } }, "SuppressionInput": { "type": "object", "required": [ "identifier", "reason" ], "properties": { "identifier": { "type": "string", "format": "email", "description": "The email address to suppress." }, "reason": { "$ref": "#/components/schemas/SuppressionCreateReason" }, "notes": { "type": [ "string", "null" ] } } }, "Suppression": { "type": "object", "required": [ "id", "createdAt", "communicationChannel", "reason", "notes", "scope", "identifierHash" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "communicationChannel": { "$ref": "#/components/schemas/CommunicationChannel" }, "reason": { "$ref": "#/components/schemas/SuppressionReason" }, "notes": { "type": [ "string", "null" ] }, "scope": { "type": "string", "enum": [ "space", "global" ] }, "identifierHash": { "type": "string", "description": "A hash of the suppressed identifier. The raw identifier is never returned." }, "affectedContactCount": { "type": "integer", "description": "Present only on `suppressions.create` and `suppressions.batchCreate` responses: contacts in the space whose identifier matched.\n" } } }, "SuppressionBatchCreateRequest": { "type": "object", "required": [ "suppressions" ], "properties": { "suppressions": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SuppressionInput" } } } }, "SuppressionBatchCreateResultItem": { "type": "object", "required": [ "index", "status" ], "description": "Suppression fields are present when `status` is `created` or `exists`; `error` is present when `status` is `failed`.\n", "allOf": [ { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "exists", "failed" ] }, "error": { "$ref": "#/components/schemas/ErrorObject" } } }, { "$ref": "#/components/schemas/Suppression" } ] }, "SuppressionBatchCreateResult": { "type": "object", "required": [ "results", "summary" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionBatchCreateResultItem" } }, "summary": { "type": "object", "required": [ "created", "exists", "failed" ], "properties": { "created": { "type": "integer" }, "exists": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "SuppressionBatchDeleteRequest": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } } } }, "SuppressionBatchDeleteResultItem": { "type": "object", "required": [ "index", "status" ], "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "removed", "failed" ] }, "error": { "$ref": "#/components/schemas/ErrorObject" } } }, "SuppressionBatchDeleteResult": { "type": "object", "required": [ "results", "summary" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionBatchDeleteResultItem" } }, "summary": { "type": "object", "required": [ "removed", "failed" ], "properties": { "removed": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "EventInput": { "type": "object", "description": "Flat event acceptance input. Custom writable attribute keys are top-level and normalized against the event schema. Any id is ignored on fire. Reserved readiness fields are not caller-controlled. Supply eventId for retry deduplication. The normalized input has a 256 KiB ceiling.", "properties": { "eventId": { "type": [ "string", "null" ], "description": "Caller-owned occurrence identifier, scoped to the space and event schema. Reuse with identical input and occurredAt for retries. If omitted or null, the server generates a UUID; save the returned eventId. A changed payload under the same value returns event_id_conflict." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event occurred. Defaults to acceptance time; explicit values must be no more than 366 days old or five minutes in the future. Preserve the same explicit value on retries." }, "contactId": { "type": [ "string", "null" ], "description": "Explicit contact subject id in this space. Mutually exclusive with objectId." }, "objectId": { "type": [ "string", "null" ], "description": "Explicit object subject id in this space. Mutually exclusive with contactId." } }, "additionalProperties": true }, "FireResult": { "type": "object", "required": [ "accepted", "id", "eventId", "isDuplicate", "readinessAtAcceptance" ], "properties": { "accepted": { "type": "integer", "const": 1, "description": "One event occurrence was durably accepted or replayed." }, "id": { "type": "string", "description": "maxclicks event id; use it with events.status." }, "eventId": { "type": "string", "description": "Caller-supplied or generated occurrence identifier." }, "isDuplicate": { "type": "boolean" }, "readinessAtAcceptance": { "type": "string", "enum": [ "pending", "ready" ], "description": "Immutable original acceptance state. Poll events.status for current readiness." } }, "example": { "accepted": 1, "id": "ev_BcwDvBUeSaSDILA5tHgpmU7I", "eventId": "order_1042_paid", "isDuplicate": false, "readinessAtAcceptance": "pending" } }, "BatchFireItemResult": { "type": "object", "required": [ "index", "status" ], "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "accepted", "failed", "rolled_back" ] }, "error": { "$ref": "#/components/schemas/ErrorObject" }, "id": { "type": "string" }, "eventId": { "type": [ "string", "null" ] }, "isDuplicate": { "type": "boolean" }, "readinessAtAcceptance": { "type": "string", "enum": [ "pending", "ready" ] }, "retryAfterMilliseconds": { "type": "integer", "minimum": 0, "description": "Present on an event-admission failure; delay before retrying that occurrence." } } }, "BatchFireResult": { "type": "object", "required": [ "results", "summary" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchFireItemResult" } }, "summary": { "type": "object", "required": [ "accepted", "failed" ], "properties": { "accepted": { "type": "integer" }, "failed": { "type": "integer" } } }, "failedIndex": { "type": "integer", "description": "Present on abort. Index of the item whose failure stopped processing; later items were not attempted." } }, "example": { "results": [ { "index": 0, "status": "accepted", "id": "ev_BcwDvBUeSaSDILA5tHgpmU7I", "eventId": "order_1042_paid", "isDuplicate": false, "readinessAtAcceptance": "pending" } ], "summary": { "accepted": 1, "failed": 0 } } }, "EventBatchRequest": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/EventInput" } }, "onError": { "type": "string", "enum": [ "continue", "abort" ], "default": "continue" } } }, "Event": { "type": "object", "description": "A ready business event. Custom stored values are flattened into the top level. Pending or failed acceptances are available through events.status instead.", "required": [ "id", "schemaId", "schemaSlug", "eventId", "createdAt", "receivedAt", "occurredAt", "readyAt", "readinessState", "definitionRevision", "contactId", "objectId" ], "properties": { "id": { "type": "string" }, "schemaId": { "type": "string" }, "schemaSlug": { "type": "string" }, "eventId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "occurredAt": { "type": "string", "format": "date-time" }, "readyAt": { "type": [ "string", "null" ], "format": "date-time" }, "readinessState": { "type": "string", "enum": [ "pending", "ready", "failed", "outcome_unknown" ] }, "definitionRevision": { "type": "string" }, "contactId": { "type": [ "string", "null" ] }, "objectId": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "DnsRecord": { "type": "object", "required": [ "type", "name", "value", "priority", "status" ], "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "not started", "pending", "success", "failed", "temporary failure" ] } } }, "Domain": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "customReturnPath", "verificationStarted", "verifiedForSending" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "customReturnPath": { "type": "string" }, "verificationStarted": { "type": "boolean" }, "verifiedForSending": { "type": "boolean" }, "records": { "type": "array", "description": "Live-checked DNS records. Present on `get`, `create`, and `verify`; omitted on `list`.", "items": { "$ref": "#/components/schemas/DnsRecord" } } } }, "Sender": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "description", "code", "domainId", "email" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "code": { "type": "string", "description": "The email local part." }, "domainId": { "type": "string" }, "email": { "type": "string", "format": "email", "description": "`code`@domain, derived." } } }, "Topic": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "description", "color", "channel", "private" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "$ref": "#/components/schemas/BadgeColor" }, "channel": { "$ref": "#/components/schemas/CommunicationChannel" }, "private": { "type": "boolean", "description": "Private topics only appear in the contact preferences page if the contact has been granted access." } } }, "Segment": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "description", "contactSchemaId", "contactSchemaSlug", "requirements", "conditionDescriptionMarkdown", "integrationVendorName" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "contactSchemaId": { "type": "string" }, "contactSchemaSlug": { "type": "string" }, "requirements": { "type": "string", "description": "The refined natural-language specification used to generate the condition." }, "conditionDescriptionMarkdown": { "type": "string", "description": "Human-readable markdown description of the condition. The generated expression itself is never returned." }, "integrationVendorName": { "type": [ "string", "null" ] }, "matchingCount": { "type": "integer", "description": "Present when the segment was just created, or just updated with new `requirements`; omitted otherwise. A live count at that moment, not kept in sync afterward (call `segments.count` for the current value).\n" } } }, "SegmentCreate": { "type": "object", "required": [ "name", "contactSchema", "requirements" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "contactSchema": { "type": "string", "description": "A contact schema id or slug." }, "requirements": { "type": "string", "description": "Natural-language description of the filter criteria." } } }, "TemplateFrom": { "description": "A sender: either a verified domain with a manual slug and display name, or a saved sender profile.", "oneOf": [ { "type": "object", "required": [ "type", "domainId", "code" ], "properties": { "type": { "type": "string", "const": "domain" }, "domainId": { "type": "string" }, "code": { "type": "string", "description": "Email local part." }, "name": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "type", "senderId" ], "properties": { "type": { "type": "string", "const": "sender" }, "senderId": { "type": "string" } } } ] }, "DataPath": { "type": "array", "description": "A path into a data payload, as property-key segments.", "items": { "type": "string" } }, "DataRepresentationProperty": { "description": "One property of a data representation. `record` properties reference records from a schema; `json` properties are plain JSON values described by a JSON schema. `schema` accepts an id or slug on input; responses always echo the slug.\n", "oneOf": [ { "type": "object", "required": [ "key", "type", "schema" ], "properties": { "key": { "type": "string" }, "type": { "type": "string", "const": "record" }, "schema": { "type": "string", "description": "A schema id or slug." }, "isArray": { "type": "boolean", "default": false }, "description": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "key", "type", "jsonSchema" ], "properties": { "key": { "type": "string" }, "type": { "type": "string", "const": "json" }, "jsonSchema": { "type": "object", "description": "A simplified JSON Schema describing the value." }, "description": { "type": [ "string", "null" ] } } } ] }, "Template": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "description", "transactional", "contentFormat", "contentEditor", "content", "from", "recipientDataPath", "expectedDataRepresentation", "communicationTopicId" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "transactional": { "type": "boolean" }, "contentFormat": { "type": [ "string", "null" ], "enum": [ "mjml", "html", null ] }, "contentEditor": { "type": [ "string", "null" ], "enum": [ "rich", "raw", null ] }, "content": { "oneOf": [ { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "from": { "oneOf": [ { "$ref": "#/components/schemas/TemplateFrom" }, { "type": "null" } ] }, "recipientDataPath": { "$ref": "#/components/schemas/DataPath" }, "expectedDataRepresentation": { "type": "array", "items": { "$ref": "#/components/schemas/DataRepresentationProperty" } }, "communicationTopicId": { "type": [ "string", "null" ] } } }, "TemplateSendRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Payload keyed by the template's expected data-representation properties. Minimal identifiers suffice for record properties (e.g. `{ \"email\": \"user@example.com\" }` for a contact); the platform finds-or-creates the record, then reads it back for rendering.\n", "additionalProperties": true } } }, "TemplateSendResponse": { "type": "object", "required": [ "emailId", "status", "error" ], "properties": { "emailId": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "sent", "failed", null ] }, "error": { "type": [ "string", "null" ], "description": "A generic message when `status` is `failed`. The real failure detail stays server-side." } } }, "BroadcastSchedulingStatus": { "type": "string", "enum": [ "none", "draft", "send now", "send at" ] }, "BroadcastAudience": { "description": "The broadcast's resolved audience.", "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "all" } } }, { "type": "object", "required": [ "type", "segmentId" ], "properties": { "type": { "type": "string", "const": "segment" }, "segmentId": { "type": "string" } } }, { "type": "object", "required": [ "type", "requirements", "conditionDescriptionMarkdown" ], "properties": { "type": { "type": "string", "const": "custom filter" }, "requirements": { "type": "string" }, "conditionDescriptionMarkdown": { "type": "string" } } } ] }, "BroadcastAudienceInput": { "description": "The audience to point a broadcast at: everyone in its contact schema, or an existing segment. A `custom filter` audience is authored in the maxclicks app, where a human reviews the generated condition before it drives a mass send, and cannot be set here.\n", "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "all" } } }, { "type": "object", "required": [ "type", "segmentId" ], "properties": { "type": { "type": "string", "const": "segment" }, "segmentId": { "type": "string" } } } ] }, "Broadcast": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "description", "contactSchemaId", "contactSchemaSlug", "schedulingStatus", "scheduledFor", "sendingStartedAt", "sendingFinishedAt", "failureReason", "audience", "hasContent" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "contactSchemaId": { "type": "string" }, "contactSchemaSlug": { "type": "string" }, "schedulingStatus": { "$ref": "#/components/schemas/BroadcastSchedulingStatus" }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "sendingStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendingFinishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "audience": { "$ref": "#/components/schemas/BroadcastAudience" }, "hasContent": { "type": "boolean", "description": "Never includes the underlying email content itself (e.g. raw Adaptyle markup), only this boolean summary." } } }, "BroadcastUpdate": { "type": "object", "description": "At least one field must be provided. Only `name`/`description`/ `audience`/`scheduledFor` are updatable; content is not editable through this endpoint. Rejected once sending has started.\n", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "audience": { "$ref": "#/components/schemas/BroadcastAudienceInput" }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" } } }, "BroadcastSendRequest": { "type": "object", "description": "An empty or omitted body sends now; a `scheduledFor` schedules for later.", "properties": { "scheduledFor": { "type": "string", "format": "date-time" } } }, "BroadcastRun": { "type": "object", "required": [ "id", "createdAt", "contactId", "contactEmail", "status", "failureReason", "email" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "contactId": { "type": "string" }, "contactEmail": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "sent", "failed", "pending" ] }, "failureReason": { "type": [ "string", "null" ] }, "email": { "oneOf": [ { "type": "object", "required": [ "id", "sentAt", "opensCount", "clicksCount", "bounced", "complained" ], "properties": { "id": { "type": "string" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "opensCount": { "type": "integer" }, "clicksCount": { "type": "integer" }, "bounced": { "type": "boolean" }, "complained": { "type": "boolean" } } }, { "type": "null" } ] } }, "description": "A narrow public delivery projection. status is derived from email presence and delivery fields: no associated email is reported failed; email sentAt is sent; send/rejection error is failed; otherwise pending. This is not the complete internal planning, credit, quality-pause, or redrive state. An unsent email object can remain pending while operational work waits." }, "EmailAggregatedMetrics": { "type": "object", "required": [ "sent", "delivered", "bounced", "deliveryDelays", "rejected", "failed", "complained", "unsubscribed", "opens", "uniqueOpens", "clicks", "uniqueClicks" ], "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "deliveryDelays": { "type": "integer" }, "rejected": { "type": "integer" }, "failed": { "type": "integer" }, "complained": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "opens": { "type": "integer" }, "uniqueOpens": { "type": "integer" }, "clicks": { "type": "integer" }, "uniqueClicks": { "type": "integer" } } }, "BroadcastMetricsResponse": { "type": "object", "description": "`email` is omitted entirely when the broadcast has no email content yet.", "properties": { "email": { "$ref": "#/components/schemas/EmailAggregatedMetrics" } } }, "WebhookTrigger": { "type": "string", "enum": [ "contact upserted", "contact deleted", "object upserted", "object deleted", "event fired", "email event" ] }, "EmailEventType": { "type": "string", "enum": [ "scheduled", "sending failed", "sent", "rejected", "unsubscribed", "bounced", "complained", "delivered", "opened", "clicked", "delivery delayed" ] }, "WebhookStatus": { "type": "string", "enum": [ "live", "paused", "circuit breaker" ] }, "WebhookCondition": { "description": "The webhook's resolved filter condition. The generated expression is never returned, only its description.", "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "none" } } }, { "type": "object", "required": [ "type", "segmentId" ], "properties": { "type": { "type": "string", "const": "segment" }, "segmentId": { "type": "string" } } }, { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "const": "custom filter" }, "description": { "type": "string" } } } ] }, "WebhookConditionInput": { "description": "The filter condition to create or update a webhook with. A `custom filter` condition generates via AI from `requirements` (billed, `ai` rate bucket).\n", "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "none" } } }, { "type": "object", "required": [ "type", "segmentId" ], "properties": { "type": { "type": "string", "const": "segment" }, "segmentId": { "type": "string" } } }, { "type": "object", "required": [ "type", "requirements" ], "properties": { "type": { "type": "string", "const": "custom filter" }, "requirements": { "type": "string", "description": "Natural-language description of the filter criteria." } } } ] }, "Webhook": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "url", "trigger", "emailEventTypes", "schemaId", "condition", "status", "totalCalls", "failedCalls", "failedCallsInARow", "lastCalledAt", "lastCallErrorMessage", "integrationVendorName" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "trigger": { "$ref": "#/components/schemas/WebhookTrigger" }, "emailEventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/EmailEventType" } }, "schemaId": { "type": [ "string", "null" ] }, "condition": { "$ref": "#/components/schemas/WebhookCondition" }, "status": { "$ref": "#/components/schemas/WebhookStatus" }, "totalCalls": { "type": "integer" }, "failedCalls": { "type": "integer" }, "failedCallsInARow": { "type": "integer" }, "lastCalledAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCallErrorMessage": { "type": [ "string", "null" ] }, "integrationVendorName": { "type": [ "string", "null" ], "description": "Non-null means the webhook is integration-owned and cannot be updated, deleted, or rotated." } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "signatureVerificationSecret" ], "properties": { "signatureVerificationSecret": { "type": "string" } } } ] }, "WebhookCreate": { "type": "object", "required": [ "url", "trigger" ], "properties": { "url": { "type": "string", "format": "uri" }, "trigger": { "$ref": "#/components/schemas/WebhookTrigger" }, "emailEventTypes": { "type": "array", "description": "Required and non-empty only when trigger is `email event`.", "items": { "$ref": "#/components/schemas/EmailEventType" } }, "schemaId": { "type": [ "string", "null" ], "description": "A schema id or slug. Required for every trigger except `email event`." }, "condition": { "$ref": "#/components/schemas/WebhookConditionInput" } } }, "WebhookUpdate": { "type": "object", "description": "At least one field must be provided. Trigger and schema are not updatable.", "properties": { "url": { "type": "string", "format": "uri" }, "emailEventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/EmailEventType" } }, "condition": { "$ref": "#/components/schemas/WebhookConditionInput" }, "status": { "type": "string", "enum": [ "live", "paused" ] } } }, "RotatedWebhookSecret": { "type": "object", "required": [ "id", "signatureVerificationSecret", "updatedAt" ], "properties": { "id": { "type": "string" }, "signatureVerificationSecret": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Workflow": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "description", "paused", "isDirty", "published" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "paused": { "type": "boolean" }, "isDirty": { "type": "boolean", "description": "Has unpublished changes." }, "published": { "type": "boolean" } } }, "WorkflowRunStepHistoryRecord": { "type": "object", "required": [ "index", "stepId", "stepLabel", "slotKey", "enteredAt", "leftAt", "failureReason" ], "properties": { "stepId": { "type": "string" }, "stepLabel": { "type": [ "string", "null" ] }, "slotKey": { "type": [ "string", "null" ] }, "enteredAt": { "type": "string", "format": "date-time" }, "leftAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "index": { "type": "integer" } } }, "WorkflowRun": { "type": "object", "required": [ "id", "createdAt", "updatedAt", "versionId", "status", "failureReason", "stepHistory", "stepCount", "parentRunId", "parentExecutionOrdinal", "nextHistoryBeforeIndex" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "versionId": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "failureReason": { "type": [ "string", "null" ] }, "stepHistory": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunStepHistoryRecord" } }, "stepCount": { "type": "integer", "description": "Persisted execution ordinal; not the length of this history window." }, "parentRunId": { "type": [ "string", "null" ] }, "parentExecutionOrdinal": { "type": [ "integer", "null" ] }, "nextHistoryBeforeIndex": { "type": [ "integer", "null" ], "description": "Pass as history_before to get earlier history; null when no earlier cursor is available." } }, "example": { "id": "wfr_BcwDvBUeSaSDILA5tHgpmU7I", "createdAt": "2026-09-14T10:30:00.000Z", "updatedAt": "2026-09-14T10:30:01.000Z", "versionId": "wfv_BcwDvBUeSaSDILA5tHgpmU7I", "status": "running", "failureReason": null, "stepHistory": [ { "index": 0, "stepId": "wfs_BcwDvBUeSaSDILA5tHgpmU7I", "stepLabel": "Incoming webhook", "slotKey": "next", "enteredAt": "2026-09-14T10:30:00.000Z", "leftAt": "2026-09-14T10:30:01.000Z", "failureReason": null } ], "stepCount": 1, "parentRunId": null, "parentExecutionOrdinal": null, "nextHistoryBeforeIndex": null } }, "FormContactInput": { "type": "object", "description": "Flat contact input for the form's contact schema. Custom attribute keys are passed at the top level.", "properties": { "id": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "additionalProperties": true }, "FormSubmission": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/FormContactInput" }, "emailMarketingConsent": { "type": [ "boolean", "null" ] }, "captchaToken": { "type": [ "string", "null" ] } } }, "FormSubmissionResult": { "oneOf": [ { "type": "object", "required": [ "contactId" ], "properties": { "contactId": { "type": "string" } } }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "const": "verification_pending" } } } ] }, "RecordDeletionStatus": { "type": "object", "required": [ "operationId", "status", "message" ], "properties": { "operationId": { "type": "string", "description": "Opaque deletion operation identifier. Preserve the whole value." }, "status": { "type": "string", "enum": [ "pending", "blocked", "completed" ] }, "message": { "type": "string" } }, "example": { "operationId": "delete:records:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "status": "pending", "message": "Record deletion is in progress." } }, "EventStatus": { "type": "object", "required": [ "id", "eventId", "receivedAt", "occurredAt", "readyAt", "readinessState", "definitionRevision", "contactId", "objectId", "data" ], "properties": { "id": { "type": "string" }, "eventId": { "type": [ "string", "null" ] }, "receivedAt": { "type": "string", "format": "date-time" }, "occurredAt": { "type": "string", "format": "date-time" }, "readyAt": { "type": [ "string", "null" ], "format": "date-time" }, "readinessState": { "type": "string", "enum": [ "pending", "ready", "failed", "outcome_unknown" ] }, "definitionRevision": { "type": "string" }, "contactId": { "type": [ "string", "null" ] }, "objectId": { "type": [ "string", "null" ] }, "data": { "type": "object", "additionalProperties": true, "description": "Raw accepted input until readiness; prepared data when ready." } }, "example": { "id": "ev_BcwDvBUeSaSDILA5tHgpmU7I", "eventId": "order_1042_paid", "receivedAt": "2026-09-14T10:30:00.000Z", "occurredAt": "2026-09-14T10:30:00.000Z", "readyAt": null, "readinessState": "pending", "definitionRevision": "f2d9685136d4746456815a2b8a6d7a3f9eba98dfc4d6129497778d5037410d7a", "contactId": null, "objectId": null, "data": { "amount": 42 } } }, "EventIdentityInput": { "type": "object", "additionalProperties": false, "required": [ "sourceId", "subjectSchemaId", "anonymousId", "contactId", "operationId", "expectedAliasRevision" ], "properties": { "sourceId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "Source id matching an enabled contact track definition.", "example": "source_website" }, "subjectSchemaId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "Contact schema id (not a slug) used by the track.", "example": "sch_BcwDvBUeSaSDILA5tHgpmU7I" }, "anonymousId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "Browser identity in the configured source.", "example": "visitor_1042" }, "contactId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "Contact in the subject schema, or null to unbind.", "example": "con_BcwDvBUeSaSDILA5tHgpmU7I" }, "operationId": { "type": "string", "format": "uuid", "description": "Stable UUID for this identity change; reuse the same body on retries.", "example": "e125aecb-8b4e-4c7e-8f08-8f768bced7ab" }, "expectedAliasRevision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$", "description": "Last known revision for this alias. Use \"0\" only for a new alias.", "example": "0" } } }, "EventIdentityResult": { "type": "object", "required": [ "identityRevision", "affectedSubjectIds", "isDuplicate" ], "properties": { "identityRevision": { "type": "string", "description": "Committed revision as a decimal string; do not coerce to a floating-point number." }, "affectedSubjectIds": { "type": "array", "items": { "type": "string" }, "description": "Previous and new bound contacts whose track results can change." }, "isDuplicate": { "type": "boolean" } } }, "IdempotencyUnknownError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "const": "idempotency_outcome_unknown" }, "message": { "type": "string" }, "operationId": { "type": "string" }, "type": { "type": "string", "description": "May be omitted on a persistence failure." } } } } } } } }