{ "openapi": "3.1.0", "info": { "title": "Brew Public API v1", "version": "1.0.0", "description": "Brew Public API v1. Generated from the app Zod contracts (`lib//contracts.ts`): this document is the contract, and every operation documents exactly the error codes it can return.\n\n- Base URL `https://brew.new/api`; every path starts with `/v1`; JSON in and out. Request bodies and query strings are strict: an unknown key is `400 INVALID_REQUEST` and `error.param` names it.\n- Identity is always in the path. `GET /v1/` lists (`{ data, pagination: { limit, cursor, hasMore } }`; page until `cursor` is `null`), and `GET /v1//{id}` returns the bare resource, the same object a write returns. `?include=` expands relations on a detail read only, and is `400` on a list. There is no `?=` read anywhere.\n- Writes carry identity in the path and return the bare resource: `POST /v1/` creates (`201`, or `202` when work continues asynchronously), `PATCH` and `DELETE /v1//{id}` update or delete (`DELETE` answers `{ , deleted }` and is idempotent). Lifecycle state changes such as publishing ride `PATCH` as attributes. Two writes report more than the row and say so in their shape: `POST` and `PATCH /v1/contacts` are upserts that answer `{ contact, created | updated, … }` because whether a row was created, which fields changed, and which field definitions were minted are facts about the write, not about the contact.\n- Non-CRUD operations are explicit action sub-paths, for example `POST /v1/automations/{automationId}/test`, `POST /v1/domains/{domainId}/verify`, `POST /v1/sends/{sendId}/cancel` and `POST /v1/automations/triggers/{triggerEventId}/fire`.\n- Every resource has one root. Sends read and write at `/v1/sends`, fired triggers at `/v1/automations/trigger-instances`, and `/v1/analytics/*` holds only reports (aggregates over a window). Every endpoint answers in the same envelopes, with no exceptions.\n- Field names are camelCase; enum values are lowercase snake_case; timestamps are ISO 8601 UTC strings. Identifiers are opaque strings of at most 64 characters (`triggerEventId` up to 256); never parse a prefix.\n- Everything that runs shares one status vocabulary: `queued`, `scheduled`, `running`, `paused`, `completed`, `partially_completed`, `failed`, `canceled`. It covers sends, automation runs, manual audience runs, audience builds and inbox placement tests, so one status switch reads them all. A step inside a run is `running`, `completed`, `failed` or `skipped`.\n- Every error on every endpoint is `{ error: { code, type, message, suggestion, docs, param?, retryAfter?, details? } }`. Branch on `code`: the closed list is the `ApiErrorCode` component and every operation documents exactly the codes it can return. Non-fatal caveats arrive as `warnings: [{ code, message, field? }]` on `2xx` bodies.\n- A credential is brand-scoped (the brand is implicit; send nothing) or organization-scoped (name the brand with the `X-Brand-Id` header on brand-scoped operations, else `400 BRAND_ID_REQUIRED`; there is no default brand). Only `POST /v1/api-keys` carries a `brandId` field, and only a signed-in organization admin session may call `/v1/api-keys`. A brand outside your reach surfaces as `404`, never `403`.\n- Send `Idempotency-Key` (up to 100 characters) on any POST you might repeat: the same key and body replays the original response for 24 hours; the same key with a different body is `409 IDEMPOTENCY_CONFLICT`. Rate limits are per credential and named policy (`X-RateLimit-*` headers; `429` carries `Retry-After`). Credit-metered operations advertise `402` and carry `x-brew-credited: true` in the spec.\n- Discovery without a key: `GET /v1/help` (JSON catalog with scopes, credits and rate limits per operation), `GET /v1/llms.txt` (this guide) and `GET /v1/health`. The OpenAPI document is served at `/openapi.json`.", "contact": { "name": "Brew Support", "url": "https://docs.brew.new", "email": "support@brew.new" } }, "servers": [ { "url": "https://brew.new/api", "description": "Production" }, { "url": "http://localhost:3000/api", "description": "Local development" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "tags": [ { "name": "Emails", "description": "Email designs and sending. Generate a design with the Brew email agent, edit, version, restore — then send it: `POST /v1/sends` delivers a design to a target (a saved audience, an inline list, or a single address) via a verified domain, and `POST /v1/sends` with `test: true` fires a one-off test. Sending is not campaign-specific. Send reads live under Sends (`/v1/sends`)." }, { "name": "Sends", "description": "The unit of delivery and analytics. `POST /v1/sends` delivers a design to a target; `GET /v1/sends` lists campaign sends (with lifetime stats) or, with a join filter, one automation’s per-recipient deliveries; `GET /v1/sends/{sendId}` reads one send and its events. Cancel, pause and resume are action sub-paths." }, { "name": "Brands", "description": "Brand lifecycle for ORGANIZATION-scoped credentials: list the brands a credential can reach, read one, and create a new one (extraction runs asynchronously — poll `GET /v1/brands/{brandId}` until `status: completed`). These endpoints act on the organization, so they take no `X-Brand-Id`." }, { "name": "Analytics", "description": "Read-only cross-resource reports: the brand overview, windowed automation performance and the unified event feed. Send rows (with lifetime stats) live at `/v1/sends`; fired triggers at `/v1/automations/trigger-instances`." }, { "name": "Automations", "description": "Automation graphs — deterministic create from explicit `nodes` + `connections`, update, version, publish / unpublish, test. Includes trigger event definitions + the fire endpoint (`/v1/automations/triggers`) and run history (`/v1/automations/runs`)." }, { "name": "Contacts", "description": "Create, search, patch, and delete contacts. Email is the primary key." }, { "name": "Contact Fields", "description": "List, create, and delete custom contact field definitions." }, { "name": "Audiences", "description": "Saved contact filter sets — a recipient target for sends." }, { "name": "Domains", "description": "Sending domains: add, read DNS records, verify, configure sender defaults." }, { "name": "Templates", "description": "Public template gallery (read-only) usable as generation references." }, { "name": "Brand", "description": "The single brand bound to the API key." }, { "name": "Chats", "description": "List the brand's Brew chats, and read a brand-scoped digest of one — referenced emails/automations/triggers + a trimmed transcript — so an external agent can resume the conversation." }, { "name": "Notifications", "description": "The brand's notification feed, as the app's bell shows it. Each row is gated by the credential's access to its feature, and a comment mention reaches only the person it names." }, { "name": "Insights", "description": "Brew Insights, read-only: the insight engine’s deterministic findings about the brand, ranked as the Insights page shows them, one finding in full with its frozen metrics and evidence, and the intelligence layer beside them (weekly pulse, latest report, open suggestions, agent memo)." }, { "name": "Integrations", "description": "Brand-scoped catalog of connectable providers plus which ones are already connected. Connect itself stays in Settings (`/integrations/{provider}`)." }, { "name": "API Keys", "description": "Mint, list, and revoke API keys through a signed-in Clerk session whose active organization role is exactly `org:admin`. API-key and OAuth actors receive `403`. `POST` body `brandId` is the new key's binding (the only v1 body field named `brandId`)." }, { "name": "Meta", "description": "Public discovery surface (no auth): the machine-readable API catalog (`/v1/help`)." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Send your Brew API key as `Authorization: Bearer brew_xxx`.", "x-default": "Bearer brew_your_api_key" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Send your Brew API key as `X-API-Key: brew_xxx`.", "x-default": "brew_your_api_key" }, "sessionAuth": { "type": "apiKey", "in": "cookie", "name": "__session", "description": "A signed-in Clerk browser session whose active organization role is exactly `org:admin`. API-key and OAuth actors are rejected." } }, "schemas": { "EmailSummary": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ] }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last stable design update. While status is `generating`, collection reads hold this at `createdAt` so body chunks do not reorder or invalidate the whole list; the completion transition publishes the final source timestamp." }, "subjectLine": { "type": "string", "description": "The design's default inbox subject, persisted on the latest version. Distinct from `title` (canvas name). Detail-only; absent on rows where it has never been set (via the write surfaces' `subjectLine` field, or in-app). `POST /v1/sends` still requires an explicit `subject`." }, "previewText": { "type": "string", "description": "The design's inbox preview line, read directly from the latest version's JSX (its single source of truth) — what a send delivers when no explicit `previewText` override is passed to POST /v1/sends. Detail-only; absent when the design has no ." }, "lang": { "type": "string", "enum": [ "en", "de", "fr", "es", "pt", "it", "nl", "pl", "sv", "da", "no", "fi", "cs", "sk", "hu", "ro", "bg", "el", "tr", "ru", "uk", "hr", "sr", "sl", "lt", "lv", "et", "ca", "ar", "he", "fa", "ur", "hi", "bn", "th", "vi", "id", "ms", "tl", "ja", "ko", "zh-Hans", "zh-Hant", "sw", "af" ], "description": "The language the email's copy is written in (ISO 639-1, or zh-Hans / zh-Hant), read by Brew's language model after each content change unless a caller set it. Rendered as the HTML document's lang. Detail-only; absent until it has been read." }, "html": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "emailVersionId": { "type": "string", "minLength": 1 } }, "required": [ "version", "emailVersionId" ], "additionalProperties": false } }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "createdBy": { "type": "string", "description": "Creator as Brew shows it: a name or \"Former member\", \"API\" or \"MCP\", or both joined (\"Name · MCP\"); absent when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." } }, "required": [ "emailId", "title", "status", "updatedAt", "group" ], "additionalProperties": false }, "EmailDetail": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ] }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last stable design update. While status is `generating`, collection reads hold this at `createdAt` so body chunks do not reorder or invalidate the whole list; the completion transition publishes the final source timestamp." }, "subjectLine": { "type": "string", "description": "The design's default inbox subject, persisted on the latest version. Distinct from `title` (canvas name). Detail-only; absent on rows where it has never been set (via the write surfaces' `subjectLine` field, or in-app). `POST /v1/sends` still requires an explicit `subject`." }, "previewText": { "type": "string", "description": "The design's inbox preview line, read directly from the latest version's JSX (its single source of truth) — what a send delivers when no explicit `previewText` override is passed to POST /v1/sends. Detail-only; absent when the design has no ." }, "lang": { "type": "string", "enum": [ "en", "de", "fr", "es", "pt", "it", "nl", "pl", "sv", "da", "no", "fi", "cs", "sk", "hu", "ro", "bg", "el", "tr", "ru", "uk", "hr", "sr", "sl", "lt", "lv", "et", "ca", "ar", "he", "fa", "ur", "hi", "bn", "th", "vi", "id", "ms", "tl", "ja", "ko", "zh-Hans", "zh-Hant", "sw", "af" ], "description": "The language the email's copy is written in (ISO 639-1, or zh-Hans / zh-Hant), read by Brew's language model after each content change unless a caller set it. Rendered as the HTML document's lang. Detail-only; absent until it has been read." }, "html": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "emailVersionId": { "type": "string", "minLength": 1 } }, "required": [ "version", "emailVersionId" ], "additionalProperties": false } }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "createdBy": { "type": "string", "description": "Creator as Brew shows it: a name or \"Former member\", \"API\" or \"MCP\", or both joined (\"Name · MCP\"); absent when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." }, "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ], "description": "The version that was read: its number, or `latest` for the current head." }, "runId": { "type": "string", "description": "Echoes the `runId` query parameter when one was passed." }, "previewStatus": { "type": "string", "enum": [ "available", "unavailable", "not_ready" ], "description": "`available` when `previewImage` is set; `unavailable` when a ready design has no saved screenshot; `not_ready` while generating or after a failure." }, "content": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "mimeType": { "type": "string", "enum": [ "text/html" ] }, "bytes": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "url", "mimeType", "bytes", "expiresAt" ], "additionalProperties": false, "description": "MCP only: a signed, expiring download of the selected version’s HTML, in place of an `html` too large to inline." }, "text": { "type": "string", "description": "`include=text`: visible body text, merge tags kept (max 20,000 chars)." }, "textTruncated": { "type": "boolean" }, "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "count": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "href", "text", "count" ], "additionalProperties": false }, "description": "`include=links`: each destination once (`href`, first visible `text`, `count`); max 200." }, "linksTruncated": { "type": "boolean" }, "errorMessage": { "type": "string", "description": "Why the generation failed. Present when `status` is `failed`." }, "errorCause": { "type": "string", "description": "A stable failure category, when one was recorded." } }, "required": [ "emailId", "title", "status", "updatedAt", "group", "previewStatus" ], "additionalProperties": false }, "CanvasSession": { "type": "object", "properties": { "sessionId": { "type": "string" }, "embedUrl": { "type": "string", "format": "uri" }, "bootstrapToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "group" ] }, "groupId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type", "groupId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "emailId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type", "emailId" ] } ] } }, "required": [ "sessionId", "embedUrl", "bootstrapToken", "expiresAt", "target" ] }, "EmailGroupSummary": { "type": "object", "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 }, "emailCount": { "type": "integer", "minimum": 0 }, "createdBy": { "type": "string", "description": "Group creator as Brew shows it: a name or \"Former member\"; absent for an organization API key or when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." } }, "required": [ "groupId", "groupName", "emailCount" ], "additionalProperties": false }, "EmailGroupWriteResponse": { "type": "object", "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 }, "emailCount": { "type": "integer", "minimum": 0 }, "createdBy": { "type": "string", "description": "Group creator as Brew shows it: a name or \"Former member\"; absent for an organization API key or when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." }, "moved": { "type": "integer", "minimum": 0, "description": "Listed designs now in the group, counting any that were already there." }, "notMoved": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "enum": [ "not_found", "generating", "not_movable", "folder_full", "retry" ], "description": "`not_found`: no such design in this brand. `generating`: a generation is still running; move it after. `not_movable`: an older design stored in a format the folder move does not support. `folder_full`: the folder holds the 200 designs a move can place. `retry`: this call reached its read budget (large designs fit fewer per call); send these ids again." } }, "required": [ "emailId", "reason" ], "additionalProperties": false } } }, "required": [ "groupId", "groupName", "emailCount" ], "additionalProperties": false }, "Send": { "type": "object", "properties": { "sendId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "campaign", "automation" ] }, "messageClass": { "type": "string", "enum": [ "marketing", "transactional" ] }, "automationId": { "type": "string", "minLength": 1 }, "nodeId": { "type": "string", "minLength": 1 }, "automationRunId": { "type": "string", "minLength": 1 }, "audienceRunId": { "type": "string", "minLength": 1 }, "triggerInstanceId": { "type": "string", "minLength": 1 }, "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "scheduled", "queued", "running", "paused", "completed", "partially_completed", "failed", "canceled" ] }, "approvalState": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "pauseReason": { "type": "string", "enum": [ "manual", "plan_limit", "domain_unsendable" ], "description": "Why a paused send is held. `plan_limit`: the plan has too few sends left this period. `domain_unsendable`: its sending domain stopped passing DNS; fails after 7 days. Both resume on their own and can be canceled. `manual`: its operator paused the gradual ramp; resume it to continue." }, "subject": { "type": "string" }, "previewText": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Full from address; its host must be the domain named by `domainId`." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Sender display name." } }, "required": [ "email" ], "additionalProperties": false }, "replyTo": { "type": "string" }, "domainId": { "type": "string" }, "audienceId": { "type": "string", "minLength": 1 }, "audienceName": { "type": "string", "minLength": 1 }, "recipientCount": { "type": "integer", "minimum": 0 }, "scheduledAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "stats": { "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 } }, "required": [ "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "accepted": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "delayed": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "providerSuppressed": { "type": "integer", "minimum": 0 }, "preSendSkipped": { "type": "integer", "minimum": 0 }, "renderFailed": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accepted", "pending", "delayed", "delivered", "bounced", "failed", "providerSuppressed", "preSendSkipped", "renderFailed", "updatedAt" ], "additionalProperties": false }, "gradualSend": { "type": "object", "properties": { "startingPercentage": { "type": "number", "minimum": 0.1, "maximum": 100 }, "incrementPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "interval": { "oneOf": [ { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 24 }, "unit": { "type": "string", "enum": [ "hour" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 30 }, "unit": { "type": "string", "enum": [ "day" ] } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA timezone used to preserve local wall-clock time for day intervals." }, "rampEndsAt": { "type": "string", "format": "date-time", "description": "Rolling stuck-send deadline, re-stamped at every batch. Not when the ramp ends." }, "currentTranche": { "type": "integer", "exclusiveMinimum": 0 }, "sentSoFar": { "type": "integer", "minimum": 0 }, "pausedAt": { "type": "string", "format": "date-time" }, "pauseReason": { "type": "string", "enum": [ "manual" ] }, "resumedAt": { "type": "string", "format": "date-time" } }, "required": [ "startingPercentage", "incrementPercentage", "interval", "timeZone" ], "additionalProperties": false }, "smartSend": { "type": "object", "properties": { "windowEndsAt": { "type": "string", "format": "date-time", "description": "Every recipient is sent by then: 24 hours after timing starts." }, "assignedViaModel": { "type": "integer", "minimum": 0, "description": "Recipients timed from their own opens and clicks." }, "assignedImmediately": { "type": "integer", "minimum": 0, "description": "Recipients with no opens or clicks, sent right away." }, "modelFallbacks": { "type": "integer", "minimum": 0, "description": "Recipients with history that could not be timed, sent right away." } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "provider_suppressed", "suppressed", "quota_skipped", "received", "unsubscribed" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "recipientEmail": { "type": "string" }, "url": { "type": "string" }, "machineGenerated": { "type": "boolean" }, "clickBotReason": { "type": "string" } }, "required": [ "eventType", "occurredAt" ], "additionalProperties": false } } }, "required": [ "sendId", "kind", "emailId", "status", "createdAt", "updatedAt" ], "additionalProperties": false }, "SendEvent": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "provider_suppressed", "suppressed", "quota_skipped", "received", "unsubscribed" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "recipientEmail": { "type": "string" }, "url": { "type": "string" }, "machineGenerated": { "type": "boolean" }, "clickBotReason": { "type": "string" } }, "required": [ "eventType", "occurredAt" ], "additionalProperties": false }, "AutomationNode": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "trigger" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "event" ] }, "triggerEventId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "manualAudience" ] }, "audienceId": { "type": "string" } }, "required": [ "mode", "audienceId" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "sendEmail" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string", "description": "Informational duplicate of node.type; ignored." }, "emailId": { "type": "string", "minLength": 1, "description": "Email design id — required for sendEmail." }, "emailVersionId": { "type": "string", "minLength": 1, "description": "Email version id to send — required. A pin to the latest version follows new versions (prompt edit, restore) into an unpublished draft; older pins stay." }, "domainId": { "type": "string", "minLength": 1, "description": "Owned sending-domain id — optional at authoring; required, and verified (sendable: true), at publish and on every live run. A marketing domain enforces the unsubscribe link; a sendingPurpose \"transactional\" domain skips it and delivers even to unsubscribed contacts, so choose one only for genuinely transactional flows (receipts, password resets)." }, "subject": { "type": "string", "minLength": 1, "description": "Inbox subject — required. Supports {{var | fallback}} interpolation." }, "previewText": { "type": "string", "description": "Inbox preheader — optional; the email design's is the source of truth and wins when present." }, "fromName": { "type": "string", "minLength": 1, "description": "Sender display name; resolved from the domain default when unset." }, "replyTo": { "type": "string", "format": "email", "description": "Reply-to address; resolved from the domain default when unset." }, "emailTitle": { "type": "string", "description": "Informational email title mirror; tolerated for round-trips." }, "fromAddress": { "type": "string", "description": "Sender address on domainId's own domain; resolved from the domain default when unset." } }, "required": [ "emailId", "emailVersionId", "subject" ], "additionalProperties": false } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "wait" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "filter" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "payload" ] }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with" ] }, "value": { "type": "string", "description": "String value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "description": "Finite numeric value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "ISO date string or Unix timestamp in milliseconds to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "in", "not_in", "contains_any", "not_contains_any" ] }, "value": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Non-empty array of string values to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "in", "not_in" ] }, "value": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Non-empty array of finite numbers to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "description": "Inclusive [minimum, maximum] numeric bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] }, { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] } ], "description": "Inclusive [start, end] ISO-date or Unix-millisecond timestamp bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "bool" ] }, "operator": { "type": "string", "enum": [ "is_true", "is_false" ], "description": "Unary boolean check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false } ] }, "minItems": 1 } }, "required": [ "logicalOperator", "conditions" ], "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "engagement" ] }, "sourceNodeId": { "type": "string", "minLength": 1, "description": "Id of the upstream sendEmail node this filter watches for opens/clicks." }, "window": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ], "additionalProperties": false }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "condition": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "engaged", "not_engaged", "clicked_link" ] }, "events": { "type": "string", "enum": [ "opened", "clicked", "opened_or_clicked" ] }, "url": { "type": "string" }, "position": { "type": "string", "enum": [ "any", "first", "last" ] } }, "required": [ "kind" ] } }, "required": [ "id", "condition" ] }, "minItems": 1 } }, "required": [ "mode", "sourceNodeId", "window", "branches" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "split" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "percentage" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "leftPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "seed": { "type": "string" } }, "required": [ "mode", "leftLabel", "rightLabel", "leftPercentage" ], "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "condition" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with" ] }, "value": { "type": "string", "description": "String value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "description": "Finite numeric value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "ISO date string or Unix timestamp in milliseconds to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "in", "not_in", "contains_any", "not_contains_any" ] }, "value": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Non-empty array of string values to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "in", "not_in" ] }, "value": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Non-empty array of finite numbers to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "description": "Inclusive [minimum, maximum] numeric bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] }, { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] } ], "description": "Inclusive [start, end] ISO-date or Unix-millisecond timestamp bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "bool" ] }, "operator": { "type": "string", "enum": [ "is_true", "is_false" ], "description": "Unary boolean check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false } ] }, "minItems": 1 } }, "required": [ "mode", "leftLabel", "rightLabel", "logicalOperator", "conditions" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false } ] }, "AutomationConnection": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "branch": { "type": "string", "minLength": 1 } }, "required": [ "from", "to" ], "additionalProperties": false }, "AutomationRow": { "type": "object", "properties": { "automationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "published": { "type": "boolean" }, "isLive": { "type": "boolean" }, "liveVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "liveAutomationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } }, "paused": { "type": "boolean" }, "pausedAt": { "type": "number" }, "nodes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "trigger" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "event" ] }, "triggerEventId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "manualAudience" ] }, "audienceId": { "type": "string" } }, "required": [ "mode", "audienceId" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "sendEmail" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "emailId": { "type": "string" }, "emailVersionId": { "type": "string" }, "emailTitle": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string" }, "fromName": { "type": "string" }, "fromAddress": { "type": "string" }, "domainId": { "type": "string" }, "replyTo": { "type": "string" }, "to": {}, "html": { "type": "string" }, "variables": { "type": "object", "additionalProperties": {} } } } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "wait" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "filter" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "payload" ] }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ] }, "type": { "type": "string", "enum": [ "string", "number", "date", "bool" ] } }, "required": [ "field", "operator" ] } } }, "required": [ "logicalOperator", "conditions" ] }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "engagement" ] }, "sourceNodeId": { "type": "string" }, "window": { "type": "object", "properties": { "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "condition": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "engaged", "not_engaged", "clicked_link" ] }, "events": { "type": "string", "enum": [ "opened", "clicked", "opened_or_clicked" ] }, "url": { "type": "string" }, "position": { "type": "string", "enum": [ "any", "first", "last" ] } }, "required": [ "kind" ] } }, "required": [ "id", "condition" ] } } }, "required": [ "mode", "sourceNodeId", "window", "branches" ] } ] } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "split" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "percentage" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "leftPercentage": { "type": "number" }, "seed": { "type": "string" } }, "required": [ "mode", "leftLabel", "rightLabel", "leftPercentage" ] }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "condition" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ] }, "type": { "type": "string", "enum": [ "string", "number", "date", "bool" ] } }, "required": [ "field", "operator" ] } } }, "required": [ "mode", "leftLabel", "rightLabel", "logicalOperator", "conditions" ] } ] } }, "required": [ "id", "label", "type", "config" ] } ] } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "branch": { "type": "string" } }, "required": [ "from", "to" ] } }, "emailIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "createdBy": { "type": "string", "description": "Creator as Brew shows it: a name or \"Former member\", \"API\" or \"MCP\", or both joined (\"Name · MCP\"); absent when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." }, "publishedBy": { "type": "string", "description": "Who published the live version; absent while not live." }, "publishedByUserId": { "type": "string", "description": "Publisher user id of the live version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "version", "automationVersionId" ], "additionalProperties": false } } }, "required": [ "automationId", "automationVersionId", "name", "version", "published", "emailIds" ], "additionalProperties": false }, "ApiWarning": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DRAFT_SAVED_NOT_LIVE", "NODE_ID_REPLACED", "TRIGGER_EVENT_NOT_RECEIVED", "ENFORCEMENT_LOOSENED_WHILE_PUBLISHED", "REQUIRED_FIELD_SATISFIED_BY_FALLBACK", "RESUBSCRIBE_SKIPPED", "CORE_FIELD_IGNORED", "DATE_ORDER_ASSUMED", "FIELD_TYPE_COERCED", "CSV_ROW_SKIPPED", "CONTACT_EXISTS_SKIPPED", "CSV_COLUMN_IGNORED", "VALIDATION_SKIPPED", "RECIPIENTS_EXCLUDED", "CONSENT_RECORD_MISSING" ] }, "message": { "type": "string" }, "field": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "AutomationDryRunReport": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the graph would publish cleanly. false when any `blockers[]` entry or any `blockingIssues[]` entry is present." }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "description": "Id of the offending node. Absent on graph-level findings." }, "nodeLabel": { "type": "string", "description": "Label of the offending node. Absent on graph-level findings." }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string", "description": "Human-readable description of the finding." } }, "required": [ "severity", "message" ], "additionalProperties": false }, "description": "Publish blockers (`severity: \"error\"`). Publishing fails while any remain." }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "description": "Id of the offending node. Absent on graph-level findings." }, "nodeLabel": { "type": "string", "description": "Label of the offending node. Absent on graph-level findings." }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string", "description": "Human-readable description of the finding." } }, "required": [ "severity", "message" ], "additionalProperties": false }, "description": "Advisory findings (`severity: \"warning\"`). Publishing succeeds despite them." }, "blockingIssues": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeLabel": { "type": "string" }, "surface": { "type": "string", "enum": [ "triggerBinding", "subject", "previewText", "fromName", "replyTo", "emailBody", "filterCondition", "splitCondition" ], "description": "Where on the node the orphaned reference lives." }, "variable": { "type": "string", "description": "The bare variable / field name that cannot be resolved." }, "reason": { "type": "string", "description": "Short user-facing reason." }, "fatal": { "type": "boolean", "description": "What the reference would do at send time. true — a filter/split condition or triple-brace `{{{ }}}` body token: the run would break. false — a subject/previewText/fromName/replyTo or double-brace body tag: it would render empty. Both block publish." }, "hasFallback": { "type": "boolean", "description": "The token carries an inline `{{ name | fallback }}` fallback. It still blocks publish: a fallback covers a missing value, not a field the trigger never declares." } }, "required": [ "nodeId", "nodeLabel", "surface", "variable", "reason", "fatal", "hasFallback" ], "additionalProperties": false }, "description": "Trigger-payload / draft-variable compatibility findings. Present (possibly empty) on POST and PATCH dry-run responses. Every entry blocks publish, and `valid` is false when any is present." }, "nodeCounts": { "type": "object", "properties": { "sendEmail": { "type": "integer", "minimum": 0 }, "wait": { "type": "integer", "minimum": 0 }, "filter": { "type": "integer", "minimum": 0 }, "split": { "type": "integer", "minimum": 0 } }, "required": [ "sendEmail", "wait", "filter", "split" ], "additionalProperties": false, "description": "Per-kind node counts of the validated graph." } }, "required": [ "valid", "blockers", "warnings", "nodeCounts" ], "additionalProperties": false }, "AudienceRun": { "type": "object", "properties": { "audienceRunId": { "type": "string" }, "automationId": { "type": "string" }, "automationName": { "type": "string" }, "audienceId": { "type": "string" }, "audienceName": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "running", "paused", "completed", "failed", "canceled" ] }, "approvalState": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "pauseReason": { "type": "string", "enum": [ "manual", "plan_limit" ], "description": "Why a paused run is held. `plan_limit` means the plan has too few sends left this period; the run resumes on its own once the allowance has room (`resumeAudienceRun` refuses it), or you can cancel it. `manual` means an operator paused it; resume it to continue." }, "scheduledAt": { "type": "string", "format": "date-time" }, "totalRecipients": { "type": "number" }, "sentCount": { "type": "number" }, "failedCount": { "type": "number" }, "skippedCount": { "type": "number" }, "nodeStats": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeType": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "entered": { "type": "number" }, "sent": { "type": "number" }, "failed": { "type": "number" }, "skipped": { "type": "number" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "description": "A send step's own send (`arn_…`). Its delivery and, on a gradual run, its batch progress are at GET /v1/sends/{sendId}." } }, "required": [ "nodeId", "nodeType" ] } }, "gradualSend": { "type": "object", "properties": { "startingPercentage": { "type": "number", "minimum": 0.1, "maximum": 100 }, "incrementPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "interval": { "oneOf": [ { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 24 }, "unit": { "type": "string", "enum": [ "hour" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 30 }, "unit": { "type": "string", "enum": [ "day" ] } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA timezone used to preserve local wall-clock time for day intervals." }, "rampEndsAt": { "type": "string", "format": "date-time", "description": "Rolling stuck-send deadline, re-stamped at every batch. Not when the ramp ends." }, "currentTranche": { "type": "integer", "exclusiveMinimum": 0 }, "sentSoFar": { "type": "integer", "minimum": 0 }, "pausedAt": { "type": "string", "format": "date-time" }, "pauseReason": { "type": "string", "enum": [ "manual" ] }, "resumedAt": { "type": "string", "format": "date-time" } }, "required": [ "startingPercentage", "incrementPercentage", "interval", "timeZone" ], "additionalProperties": false, "description": "The run's authored ramp. Each send step ramps its own segment, so batch progress is per step: follow `nodeStats[].sendId`." }, "error": { "type": "string" }, "stalledAt": { "type": "string", "format": "date-time" }, "resumeGeneration": { "type": "number" }, "resumedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "audienceRunId", "automationId", "audienceId", "status", "createdAt", "updatedAt" ] }, "AutomationRunRow": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "definitionHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "triggerInstanceId": { "type": "string", "minLength": 4, "maxLength": 64 }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "recipientEmail": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" } }, "required": [ "automationRunId", "automationId", "mode", "status" ], "additionalProperties": false }, "AutomationRunLogRow": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "nodeId": { "type": "string", "minLength": 1 }, "nodeName": { "type": "string", "minLength": 1 }, "nodeType": { "type": "string", "enum": [ "trigger", "wait", "filter", "split", "sendEmail" ] }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "skipped" ] }, "orderIndex": { "type": "integer", "minimum": 0 }, "branch": { "type": "string", "minLength": 1 }, "durationMs": { "type": "integer", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" } }, "required": [ "automationRunId", "nodeId", "nodeName", "nodeType", "status", "orderIndex", "startedAt" ], "additionalProperties": false }, "TriggerRow": { "type": "object", "properties": { "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "provider": { "type": "string", "enum": [ "brew_api", "custom", "brew_event", "clerk", "stytch", "supabase", "workos", "stripe", "shopify", "revenuecat", "framer" ] }, "providerEventKey": { "type": "string" }, "brewEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "contact.unsubscribed" ], "description": "The Brew event this trigger starts on." }, "scope": { "type": "string", "enum": [ "domain", "all" ], "description": "`domain`: unsubscribes from one marketing sending domain (its list). `all`: unsubscribes from every email the brand sends." }, "domainHost": { "type": "string", "minLength": 1, "description": "The sending domain whose list this trigger watches, e.g. `news.acme.com`. Present only when `scope` is `domain`." } }, "required": [ "event", "scope" ], "additionalProperties": false }, "payloadSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" } } }, "required": [ "type", "fields" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "skill": { "type": "string" } }, "required": [ "triggerEventId", "title", "provider", "payloadSchema", "createdAt", "updatedAt" ], "additionalProperties": false }, "TriggerPayloadField": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "Email/automation variable name, e.g. firstName. Use descriptive keys; fields have no separate description." }, "type": { "type": "string", "enum": [ "string", "int", "boolean", "object", "array" ] }, "required": { "type": "boolean", "description": "True when the inbound payload must carry this key for the trigger to fire." }, "fallbackValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "Substitution value when the inbound payload is missing this field. Also used as the email agent's `e.g. {{ key | fallback }}` example. Scalar leaves only." }, "pii": { "type": "string", "enum": [ "none", "low", "high" ], "description": "PII classification for redaction. \"high\" auto-redacts the value in execution logs and the inbound log. \"low\" (default when omitted) preserves the value. \"none\" is an explicit marker that the field is non-personal. On a container, \"high\" redacts the whole subtree." }, "secret": { "type": "boolean", "description": "True for a value used only to render this email: never stored on contacts, in logs or analytics; cannot be used in filters, splits or recipient fields. Scalars only, never `email`. False explicitly permits ordinary PII outside rendering; pii still controls log masking. When omitted, legacy high-PII scalar protection applies except for email and top-level firstName/lastName." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" }, "description": "Nested field nodes for type \"object\", or the element shape for an array of objects. Emails reference nested leaves as dotted paths ({{ order.total }}) and arrays via {% for %}." }, "itemType": { "type": "string", "enum": [ "string", "int", "boolean" ], "description": "Element type for a type \"array\" of scalars. Omit when the array carries objects (declare `children` instead)." } }, "required": [ "key", "type", "required" ] }, "TriggerInstance": { "type": "object", "properties": { "triggerInstanceId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "api", "integration", "brew_event" ] }, "provider": { "type": "string" }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "state": { "type": "string", "enum": [ "received", "verified", "matched", "partially_fired", "fired", "rejected", "dead_letter" ] }, "matchedAutomationIds": { "type": "array", "items": { "type": "string" } }, "automationRunIds": { "type": "array", "items": { "type": "string" } }, "rejectionReason": { "type": "string" }, "attempts": { "type": "integer", "minimum": 0 }, "receivedAt": { "type": "string", "format": "date-time" }, "processedAt": { "type": "string", "format": "date-time" } }, "required": [ "triggerInstanceId", "source", "state", "matchedAutomationIds", "automationRunIds", "attempts", "receivedAt" ], "additionalProperties": false }, "Contact": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import", "app", "integration" ], "description": "Who captured it: `api` (an API caller asserted it), `form` (a signup form), `import` (a bulk import), `app` (the in-app CSV wizard checkbox), `integration` (an integration sync such as Stripe created the contact; provenance only, not an opt-in)." }, "capturedAt": { "type": "string", "format": "date-time", "description": "When it was captured." }, "policyVersion": { "type": "string", "description": "The policy or terms version in force when it was captured." }, "evidence": { "type": "string", "description": "Free-text evidence: a form URL, a ticket, a checkbox label." } }, "required": [ "source", "capturedAt" ], "additionalProperties": false }, "validationStatus": { "type": "string", "enum": [ "valid", "risky", "invalid" ], "description": "The latest verdict. `valid` only ever comes from a deliverability check (`validate: true` on ingest, or POST /v1/contacts/validate), which also sets `lastValidatedAt`. Without a check the free format check on ingest stores `risky` (disposable or role address) or `invalid`, and leaves the field unset otherwise: not validated." }, "suppressed": { "type": "boolean", "default": false }, "suppressedReason": { "type": [ "string", "null" ] }, "unsubscribedDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "validationDetails": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "brew" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "provider" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "importId": { "type": [ "string", "null" ] }, "csvFileName": { "type": [ "string", "null" ] }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "email", "createdAt", "updatedAt" ], "additionalProperties": false }, "ContactFieldDefinition": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1 }, "fieldType": { "type": "string", "enum": [ "string", "number", "date", "bool" ] }, "label": { "type": "string" }, "isCore": { "type": "boolean" }, "isFilterable": { "type": "boolean" }, "isSortable": { "type": "boolean" }, "isSearchable": { "type": "boolean" }, "coverage": { "type": "object", "properties": { "percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "approximate": { "type": "boolean" }, "topValues": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "percent": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "value", "count", "percent" ], "additionalProperties": false } }, "dominantValue": { "type": "string" } }, "required": [ "percent", "approximate", "topValues" ], "additionalProperties": false } }, "required": [ "fieldName", "fieldType" ], "additionalProperties": false }, "Audience": { "type": "object", "properties": { "audienceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "audienceName": { "type": "string", "minLength": 1, "maxLength": 200 }, "filters": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "contains_any", "not_contains_any", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "between", "is_true", "is_false", "in", "not_in", "is_empty", "not_exists", "is_not_empty", "exists", "is_set", "before", "after", "on_date" ] }, "value": {}, "type": { "type": "string", "description": "Saved audiences infer omitted types from the field registry. Unknown fields compare as strings. Date ranges require type: \"date\"." } }, "required": [ "field", "operator" ], "additionalProperties": false } }, "logicalOperator": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "filters", "logicalOperator" ], "additionalProperties": false }, "count": { "type": "integer", "minimum": 0 }, "materializationStatus": { "type": "string", "enum": [ "pending", "running", "ready", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "build": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "cohort": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "skipped", "unsubscribed" ] }, "minItems": 1, "maxItems": 10 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Scope to one send (a `sendId` from a send or send-analytics row). With `sendId` the window may be omitted." }, "emailId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "Scope to events from sends that targeted these audiences." }, "recipient": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 10, "description": "Recipient rule tokens using the Events-page grammar." }, "includeMachineClicks": { "type": "boolean" }, "exclude": { "type": "object", "properties": { "baseAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "baseAudienceId" ], "additionalProperties": false } }, "required": [ "eventTypes", "from", "to" ], "additionalProperties": false }, "field": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "date" ] } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "eventsScanned": { "type": "integer", "minimum": 0 }, "stampedContacts": { "type": "integer", "minimum": 0 } }, "required": [ "eventsScanned" ], "additionalProperties": false }, "error": { "type": "string" }, "enqueuedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "jobId", "status", "cohort", "field", "counts", "enqueuedAt" ], "additionalProperties": false } }, "required": [ "audienceId", "audienceName", "filters", "count", "createdAt", "updatedAt" ], "additionalProperties": false }, "AudienceBuild": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "cohort": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "skipped", "unsubscribed" ] }, "minItems": 1, "maxItems": 10 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Scope to one send (a `sendId` from a send or send-analytics row). With `sendId` the window may be omitted." }, "emailId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "Scope to events from sends that targeted these audiences." }, "recipient": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 10, "description": "Recipient rule tokens using the Events-page grammar." }, "includeMachineClicks": { "type": "boolean" }, "exclude": { "type": "object", "properties": { "baseAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "baseAudienceId" ], "additionalProperties": false } }, "required": [ "eventTypes", "from", "to" ], "additionalProperties": false }, "field": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "date" ] } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "eventsScanned": { "type": "integer", "minimum": 0 }, "stampedContacts": { "type": "integer", "minimum": 0 } }, "required": [ "eventsScanned" ], "additionalProperties": false }, "error": { "type": "string" }, "enqueuedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "jobId", "status", "cohort", "field", "counts", "enqueuedAt" ], "additionalProperties": false }, "Domain": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainUrl": { "type": "string", "format": "uri" }, "name": { "type": "string", "minLength": 1, "maxLength": 253 }, "region": { "type": "string" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed", "temporary_failure", "partially_verified", "partially_failed" ] }, "sendingEnabled": { "type": "boolean" }, "sendable": { "type": "boolean" }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "marketing (default) or transactional. Transactional domains skip unsubscribe and send via automation sendEmail nodes (or a test send)." }, "records": { "type": "array", "items": { "type": "object", "properties": { "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "ttl": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "number" } }, "required": [ "record", "name", "type", "ttl", "status", "value" ], "additionalProperties": false } }, "openTracking": { "type": "boolean" }, "clickTracking": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "domainId", "domainUrl", "name", "region", "status", "sendingEnabled", "sendable", "sendingPurpose", "records", "createdAt", "updatedAt" ], "additionalProperties": false }, "DomainUnsubscribeRow": { "type": "object", "properties": { "email": { "type": "string" }, "scope": { "type": "string", "enum": [ "domain", "all", "both" ] }, "unsubscribedAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "link", "one_click", "api", "import", "manual" ] }, "sendId": { "type": "string" } }, "required": [ "email", "scope" ], "additionalProperties": false }, "Template": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "brand": { "type": "string", "minLength": 1 }, "html": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "minLength": 1, "format": "date-time" } }, "required": [ "emailId", "title", "html", "previewImage", "updatedAt" ], "additionalProperties": false }, "Flow": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "brand": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "logo": { "type": "string", "format": "uri" } }, "required": [ "name" ], "additionalProperties": false }, "title": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "newsletter", "signup" ] }, "kind": { "type": "string", "enum": [ "onboarding", "trial", "events", "product_updates", "promotions" ] }, "category": { "type": "string", "minLength": 1 }, "categoryLabel": { "type": "string", "minLength": 1 }, "emailCount": { "type": "integer", "minimum": 1 }, "spanDays": { "type": "number", "minimum": 0 }, "remixCount": { "type": "integer", "minimum": 0 }, "previewImages": { "type": "array", "items": { "type": "string", "format": "uri" } }, "publishedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "anchor": { "type": "string", "enum": [ "submittedAt", "signedUpAt", "verifiedAt", "firstEmail" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer", "minimum": 1 }, "dayOffset": { "type": "number", "minimum": 0 }, "delayDays": { "type": "number", "minimum": 0 }, "subject": { "type": "string", "minLength": 1 }, "previewText": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "categoryLabel": { "type": "string", "minLength": 1 }, "emailId": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "html": { "type": "string", "minLength": 1 } }, "required": [ "order", "dayOffset", "delayDays", "subject", "category", "categoryLabel", "emailId" ], "additionalProperties": false } } }, "required": [ "slug", "brand", "title", "type", "category", "categoryLabel", "emailCount", "spanDays", "remixCount", "previewImages", "publishedAt", "updatedAt" ], "additionalProperties": false }, "FlowStep": { "type": "object", "properties": { "order": { "type": "integer", "minimum": 1 }, "dayOffset": { "type": "number", "minimum": 0 }, "delayDays": { "type": "number", "minimum": 0 }, "subject": { "type": "string", "minLength": 1 }, "previewText": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "categoryLabel": { "type": "string", "minLength": 1 }, "emailId": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "html": { "type": "string", "minLength": 1 } }, "required": [ "order", "dayOffset", "delayDays", "subject", "category", "categoryLabel", "emailId" ], "additionalProperties": false }, "ChatListRow": { "type": "object", "properties": { "chatId": { "type": "string", "description": "Resume the chat with the chat-context read." }, "title": { "type": [ "string", "null" ] }, "firstUserPrompt": { "type": [ "string", "null" ], "description": "The opening prompt, cut at 80 characters." }, "lastAssistantPreview": { "type": [ "string", "null" ], "description": "Brew's latest reply, cut at 140 characters." }, "status": { "type": [ "string", "null" ], "enum": [ "idle", "streaming", "background_finalizing", "completed", "failed", "interrupted", "stopped", "persistence_failed", null ], "description": "`streaming` or `background_finalizing` while a run is still going; null before the first run." }, "origin": { "type": [ "string", "null" ], "enum": [ "slack", null ], "description": "The chat app the conversation started in; null for the Brew web app." }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "Opens the chat in the Brew app." } }, "required": [ "chatId", "title", "firstUserPrompt", "lastAssistantPreview", "status", "origin", "updatedAt", "url" ], "additionalProperties": false }, "InsightListRow": { "type": "object", "properties": { "insightId": { "type": "string" }, "title": { "type": "string", "description": "What the finding is about." }, "description": { "type": "string", "description": "The detector’s deterministic headline; quote it, never restate its numbers." }, "severity": { "type": "string", "enum": [ "critical", "warning", "opportunity", "info" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "kind": { "type": "string", "enum": [ "answer", "insight", "strategy" ], "description": "`answer` reports what happened, `insight` a change that passed its statistical test, `strategy` a recommended next step." }, "category": { "type": "string" }, "detectorId": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "snoozed", "cleared", "dismissed", "resolved", "stale" ], "description": "A snooze that has ended reads as `active`." }, "firstSeenAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "recurrenceCount": { "type": "integer", "minimum": 0 }, "action": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "navigate" ] }, "label": { "type": "string" }, "url": { "type": "string", "description": "Absolute link to the page in Brew." } }, "required": [ "kind", "label", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assistant" ] }, "label": { "type": "string" }, "intent": { "type": "string", "enum": [ "review_domain_health", "validate_contacts", "create_campaign", "repeat_campaign", "review_recommendation" ] }, "prompt": { "type": "string", "description": "The request the Insights page sends to Brew’s assistant." } }, "required": [ "kind", "label", "intent", "prompt" ], "additionalProperties": false } ] }, "url": { "type": "string", "description": "The finding’s page in Brew." } }, "required": [ "insightId", "title", "description", "severity", "confidence", "kind", "category", "detectorId", "state", "firstSeenAt", "lastSeenAt", "recurrenceCount", "url" ], "additionalProperties": false }, "InsightList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightListRow" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false }, "freshness": { "type": "object", "properties": { "dataAsOf": { "type": [ "string", "null" ], "format": "date-time", "description": "How current the data behind the findings is; null before the first successful run." }, "lastSuccessfulRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "latestAttempt": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "succeeded", "failed", "running", "unknown" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "status", "at" ], "additionalProperties": false, "description": "The newest engine run and its outcome; `failed` means the findings may be stale." } }, "required": [ "dataAsOf", "lastSuccessfulRunAt", "latestAttempt" ], "additionalProperties": false }, "pulse": { "type": [ "object", "null" ], "properties": { "windowEnd": { "type": "string", "format": "date-time", "description": "Exclusive end of the 7-day window: the start of the newest incomplete day." }, "delivered": { "type": "number" }, "priorDelivered": { "type": "number" }, "uniqueOpens": { "type": "number" }, "priorUniqueOpens": { "type": "number" }, "uniqueClicks": { "type": "number" }, "priorUniqueClicks": { "type": "number" }, "unsubscribed": { "type": "number" }, "priorUnsubscribed": { "type": "number" }, "openRatePct": { "type": [ "number", "null" ], "description": "Percent, one decimal; null when counts-only or not measured." }, "priorOpenRatePct": { "type": [ "number", "null" ] }, "clickRatePct": { "type": [ "number", "null" ] }, "priorClickRatePct": { "type": [ "number", "null" ] }, "openDirection": { "type": "string", "enum": [ "up", "down", "steady" ], "description": "`up` or `down` only when the change is statistically real." }, "clickDirection": { "type": "string", "enum": [ "up", "down", "steady" ] }, "countsOnly": { "type": "boolean", "description": "Too few deliveries for rates; read the counts." }, "measured": { "type": "boolean", "description": "False when opens or clicks are not measured; an unmeasured rate is null, not zero." } }, "required": [ "windowEnd", "delivered", "priorDelivered", "uniqueOpens", "priorUniqueOpens", "uniqueClicks", "priorUniqueClicks", "unsubscribed", "priorUnsubscribed", "openRatePct", "priorOpenRatePct", "clickRatePct", "priorClickRatePct", "openDirection", "clickDirection", "countsOnly", "measured" ], "additionalProperties": false, "description": "With `include` pulse: the weekly pulse, or null before the first run." }, "report": { "type": [ "object", "null" ], "properties": { "reportId": { "type": "string" }, "chatId": { "type": "string", "description": "The Brew chat whose analysis run wrote the report." }, "runTrigger": { "type": "string", "enum": [ "manual", "scheduled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "insights": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "performance", "audience", "trend", "risk", "content", "setup" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "impact": { "type": [ "string", "null" ] }, "suggestionId": { "type": [ "string", "null" ], "description": "The suggestion this insight proposes, if any." } }, "required": [ "key", "kind", "title", "body", "impact", "suggestionId" ], "additionalProperties": false } } }, "required": [ "reportId", "chatId", "runTrigger", "createdAt", "insights" ], "additionalProperties": false, "description": "With `include` report: the latest intelligence report, or null when none was published." }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "suggestionId": { "type": "string" }, "title": { "type": "string" }, "prompt": { "type": "string", "description": "Exactly what launching the suggestion asks Brew to do." }, "kind": { "type": "string", "enum": [ "audience", "campaign", "automation", "deliverability", "schedule" ] }, "status": { "type": "string", "enum": [ "proposed", "launched", "dismissed", "concluded" ] }, "rationale": { "type": [ "string", "null" ] }, "sourceInsightKeys": { "type": "array", "items": { "type": "string" }, "description": "The report insight keys that motivated it." }, "executionChatId": { "type": [ "string", "null" ], "description": "The chat a launched suggestion runs in." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "suggestionId", "title", "prompt", "kind", "status", "rationale", "sourceInsightKeys", "executionChatId", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 25, "description": "With `include` suggestions: proposed and launched suggestions, most recently updated first." }, "memo": { "type": [ "object", "null" ], "properties": { "markdown": { "type": "string", "description": "Learnings, Watchlist, Experiments and History sections; at most 8192 bytes." }, "version": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedByChatId": { "type": [ "string", "null" ] } }, "required": [ "markdown", "version", "updatedAt", "updatedByChatId" ], "additionalProperties": false, "description": "With `include` memo: the memo, or null before the first run." } }, "required": [ "data", "pagination", "freshness" ], "additionalProperties": false }, "Insight": { "type": "object", "properties": { "insightId": { "type": "string" }, "title": { "type": "string", "description": "What the finding is about." }, "description": { "type": "string", "description": "The detector’s deterministic headline; quote it, never restate its numbers." }, "severity": { "type": "string", "enum": [ "critical", "warning", "opportunity", "info" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "kind": { "type": "string", "enum": [ "answer", "insight", "strategy" ], "description": "`answer` reports what happened, `insight` a change that passed its statistical test, `strategy` a recommended next step." }, "category": { "type": "string" }, "detectorId": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "snoozed", "cleared", "dismissed", "resolved", "stale" ], "description": "A snooze that has ended reads as `active`." }, "firstSeenAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "recurrenceCount": { "type": "integer", "minimum": 0 }, "action": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "navigate" ] }, "label": { "type": "string" }, "url": { "type": "string", "description": "Absolute link to the page in Brew." } }, "required": [ "kind", "label", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assistant" ] }, "label": { "type": "string" }, "intent": { "type": "string", "enum": [ "review_domain_health", "validate_contacts", "create_campaign", "repeat_campaign", "review_recommendation" ] }, "prompt": { "type": "string", "description": "The request the Insights page sends to Brew’s assistant." } }, "required": [ "kind", "label", "intent", "prompt" ], "additionalProperties": false } ] }, "url": { "type": "string", "description": "The finding’s page in Brew." }, "rationale": { "type": [ "string", "null" ] }, "closedReason": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastActedAt": { "type": [ "string", "null" ], "format": "date-time" }, "churnCount": { "type": "integer", "minimum": 0, "description": "How often the finding has closed and reopened." }, "metrics": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] }, "value": { "type": "number" }, "noun": { "type": "string" } }, "required": [ "kind", "value", "noun" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rate" ] }, "value": { "type": [ "number", "null" ] }, "numerator": { "type": "number" }, "denominator": { "type": "number" }, "basis": { "type": "string", "enum": [ "delivered", "sent", "uniqueOpened", "recipients" ] }, "anomalous": { "type": "boolean" } }, "required": [ "kind", "value", "numerator", "denominator", "basis" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "share" ] }, "value": { "type": [ "number", "null" ] }, "part": { "type": "number" }, "whole": { "type": "number" }, "wholeNoun": { "type": "string" } }, "required": [ "kind", "value", "part", "whole", "wholeNoun" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "duration" ] }, "ms": { "type": "number" }, "bucketIndex": { "type": "number" } }, "required": [ "kind", "ms" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "delta" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "pp", "pct", "abs" ] }, "from": { "type": "number" }, "to": { "type": "number" } }, "required": [ "kind", "value", "unit", "from", "to" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "hourOfDay" ] }, "hour": { "type": "number" }, "slot": { "type": "number" }, "basis": { "type": "string", "enum": [ "utc", "brand_zone" ] }, "timeZone": { "type": "string" } }, "required": [ "kind", "hour", "basis" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "multiple" ] }, "value": { "type": "number" }, "referenceLabel": { "type": "string" } }, "required": [ "kind", "value", "referenceLabel" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rank" ] }, "position": { "type": "number" }, "outOf": { "type": "number" } }, "required": [ "kind", "position", "outOf" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "interval" ] }, "lo": { "type": "number" }, "hi": { "type": "number" }, "confidenceLevel": { "anyOf": [ { "type": "number", "enum": [ 0.9 ] }, { "type": "number", "enum": [ 0.95 ] } ] }, "as": { "type": "string", "enum": [ "rate", "delta", "count" ] } }, "required": [ "kind", "lo", "hi", "confidenceLevel", "as" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "label" ] }, "text": { "type": "string" } }, "required": [ "kind", "text" ], "additionalProperties": false } ] }, "description": "Frozen when the finding was computed: the figures it rests on, which later data does not change." }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } }, "subject": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "kind", "id", "label" ], "additionalProperties": false, "description": "What the finding is about: a send, an automation, a domain." }, "method": { "type": [ "object", "null" ], "properties": { "what": { "type": "string" }, "how": { "type": "string" }, "comparedAgainst": { "type": "string" }, "resolvesWhen": { "type": "string" }, "caveat": { "type": "string" } }, "required": [ "what", "how", "comparedAgainst", "resolvesWhen" ], "additionalProperties": false, "description": "How the detector works; null when none is recorded." }, "generatedBy": { "type": [ "object", "null" ], "properties": { "trigger": { "type": "string", "enum": [ "cron_daily", "send_settled", "lifecycle_event", "manual_refresh" ] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "blindSpots": { "type": "array", "items": { "type": "string" }, "description": "What that run could not see." } }, "required": [ "trigger", "startedAt", "completedAt", "blindSpots" ], "additionalProperties": false, "description": "The engine run that last produced the finding." }, "freshness": { "type": "object", "properties": { "dataAsOf": { "type": [ "string", "null" ], "format": "date-time", "description": "How current the data behind the findings is; null before the first successful run." }, "lastSuccessfulRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "latestAttempt": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "succeeded", "failed", "running", "unknown" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "status", "at" ], "additionalProperties": false, "description": "The newest engine run and its outcome; `failed` means the findings may be stale." } }, "required": [ "dataAsOf", "lastSuccessfulRunAt", "latestAttempt" ], "additionalProperties": false } }, "required": [ "insightId", "title", "description", "severity", "confidence", "kind", "category", "detectorId", "state", "firstSeenAt", "lastSeenAt", "recurrenceCount", "url", "rationale", "closedReason", "closedAt", "lastActedAt", "churnCount", "metrics", "evidence", "subject", "method", "generatedBy", "freshness" ], "additionalProperties": false }, "Notification": { "type": "object", "properties": { "notificationId": { "type": "string", "pattern": "^ntf_[0-9a-f]{20}$", "description": "`ntf_` + 20 hex characters: a one-way hash, stable for the row’s life." }, "type": { "type": "string", "enum": [ "chat_stream", "import_job", "brand_image_import", "validation_job", "email_sent", "email_scheduled", "preview_email", "brand_extracted", "domain_status", "domain_score_run", "api_key_created", "email_send_failed", "gradual_send_paused", "gradual_send_completed", "send_limit_reached", "automation_pause_window_closed", "send_review_rejected", "comment_mention", "comment_reply", "integration_attention" ] }, "status": { "type": "string", "enum": [ "uploading", "preparing", "processing", "finalizing", "streaming", "background_finalizing", "completed", "partial", "failed", "interrupted", "stopped", "persistence_failed" ] }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "progressPercent": { "type": "number", "description": "0-100 while work is running, where it reports progress." }, "url": { "type": "string", "description": "Where the bell opens it in the Brew app." }, "chatId": { "type": "string" }, "emailId": { "type": "string" }, "domainId": { "type": "string" }, "domainName": { "type": "string" }, "isPersonal": { "type": "boolean", "description": "Addressed to the caller alone: a comment mention or reply, shown only on a personal connection." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "notificationId", "type", "status", "title", "subtitle", "isPersonal", "createdAt", "updatedAt" ], "additionalProperties": false }, "EmailCommentThread": { "type": "object", "properties": { "commentId": { "type": "string", "description": "`cmt_…`; the app opens it with `?commentId=`." }, "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "open" ] }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "element" ] }, "elementId": { "type": "string", "description": "The element the thread is pinned to (`elm_…`)." }, "nodeType": { "type": "string", "description": "What the element is: `button`, `image`, `heading`, …" } }, "required": [ "kind" ], "additionalProperties": false } ], "description": "Whether the thread is on the whole design or one element of it." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "userId", "name" ], "additionalProperties": false }, "description": "Who started, replied to, or was mentioned in the thread: the 12 most recent." }, "participantCount": { "type": "integer", "minimum": 0, "description": "How many people are in the thread; `participants` lists at most 12." }, "messageCount": { "type": "integer", "minimum": 0 }, "lastMessageAt": { "type": "string", "format": "date-time" }, "lastMessagePreview": { "type": "string", "description": "The latest message, shortened to 140 characters; mentions read as in `body`." }, "url": { "type": "string", "description": "Opens the thread on the design in the Brew app." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "description": "`cmm_…`" }, "author": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "userId", "name" ], "additionalProperties": false }, "body": { "type": "string", "description": "The message text. Each mention reads `@` + the name `mentions` gives; other `@` text is as typed." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "userId", "name" ], "additionalProperties": false } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "messageId", "author", "body", "mentions", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Only with messages: the thread's newest messages (or, after a `messagesCursor`, the next older ones) that fit the page's size budget, oldest first." }, "messagesCursor": { "type": [ "string", "null" ], "description": "Only with messages: pass it back with this thread's `commentId` to read its older messages; null when none remain." } }, "required": [ "commentId", "emailId", "status", "target", "participants", "participantCount", "messageCount", "lastMessageAt", "lastMessagePreview", "url" ], "additionalProperties": false }, "EmailsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ] }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last stable design update. While status is `generating`, collection reads hold this at `createdAt` so body chunks do not reorder or invalidate the whole list; the completion transition publishes the final source timestamp." }, "subjectLine": { "type": "string", "description": "The design's default inbox subject, persisted on the latest version. Distinct from `title` (canvas name). Detail-only; absent on rows where it has never been set (via the write surfaces' `subjectLine` field, or in-app). `POST /v1/sends` still requires an explicit `subject`." }, "previewText": { "type": "string", "description": "The design's inbox preview line, read directly from the latest version's JSX (its single source of truth) — what a send delivers when no explicit `previewText` override is passed to POST /v1/sends. Detail-only; absent when the design has no ." }, "lang": { "type": "string", "enum": [ "en", "de", "fr", "es", "pt", "it", "nl", "pl", "sv", "da", "no", "fi", "cs", "sk", "hu", "ro", "bg", "el", "tr", "ru", "uk", "hr", "sr", "sl", "lt", "lv", "et", "ca", "ar", "he", "fa", "ur", "hi", "bn", "th", "vi", "id", "ms", "tl", "ja", "ko", "zh-Hans", "zh-Hant", "sw", "af" ], "description": "The language the email's copy is written in (ISO 639-1, or zh-Hans / zh-Hant), read by Brew's language model after each content change unless a caller set it. Rendered as the HTML document's lang. Detail-only; absent until it has been read." }, "html": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "emailVersionId": { "type": "string", "minLength": 1 } }, "required": [ "version", "emailVersionId" ], "additionalProperties": false } }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "createdBy": { "type": "string", "description": "Creator as Brew shows it: a name or \"Former member\", \"API\" or \"MCP\", or both joined (\"Name · MCP\"); absent when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." } }, "required": [ "emailId", "title", "status", "updatedAt", "group" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "ApiErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ApiErrorCode" }, "type": { "type": "string", "enum": [ "authentication_error", "authorization_error", "invalid_request", "not_found", "not_implemented", "conflict", "rate_limit", "payment_required", "service_unavailable", "internal_error" ] }, "message": { "type": "string", "minLength": 1 }, "param": { "type": "string", "minLength": 1 }, "suggestion": { "type": "string", "minLength": 1 }, "docs": { "type": "string", "format": "uri" }, "retryAfter": { "type": "integer", "minimum": 0 }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "code", "type", "message", "suggestion", "docs" ] } }, "required": [ "error" ] }, "ApiErrorCode": { "type": "string", "enum": [ "ACCOUNT_SUSPENDED", "API_KEY_REVOKED", "AUDIENCE_BUILD_ACTIVE", "AUDIENCE_BUILD_ALREADY_ACTIVE", "AUDIENCE_EDIT_CONFLICT", "AUDIENCE_MEMBERSHIP_NOT_EXPRESSIBLE", "AUDIENCE_NOT_FOUND", "AUDIENCE_RUN_NOT_FOUND", "AUDIT_NOT_FOUND", "AUTHENTICATION_REQUIRED", "AUTOMATION_GRAPH_INVALID", "AUTOMATION_NOT_FOUND", "AUTOMATION_NOT_PAUSABLE", "AUTOMATION_NOT_PUBLISHED", "AUTOMATION_RUN_NOT_FOUND", "AUTOMATION_VERSION_CONFLICT", "AUTOMATION_VERSION_NOT_FOUND", "BATCH_TOO_LARGE", "BRAND_DOMAIN_CONFLICT", "BRAND_ID_REQUIRED", "BRAND_LIMIT_REACHED", "BRAND_NOT_FOUND", "BRAND_NOT_READY", "BRAND_SCOPE_MISMATCH", "CHAT_NOT_FOUND", "COMMENT_NOT_FOUND", "CONSENT_REQUIRED", "CONTACT_NOT_FOUND", "CONTENT_OPERATION_FAILED", "CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS", "CORE_FIELD_IMMUTABLE", "DOMAIN_ALREADY_EXISTS", "DOMAIN_CLAIMED_ELSEWHERE", "DOMAIN_NOT_FOUND", "DOMAIN_NOT_READY", "DOMAIN_OTHER_BRAND", "DOMAIN_PROVIDER_ERROR", "DOMAIN_PURPOSE_NOT_ALLOWED", "DOMAIN_VERIFICATION_FAILED", "DOMAIN_VERIFIED_ELSEWHERE", "EMAIL_GENERATION_FAILED", "EMAIL_GROUP_NAME_CONFLICT", "EMAIL_GROUP_NOT_FOUND", "EMAIL_IMAGES_MISSING", "EMAIL_IMPORT_FAILED", "EMAIL_IN_PROGRESS", "EMAIL_IN_USE_BY_AUTOMATION", "EMAIL_NOT_FOUND", "EMAIL_NOT_READY", "EMAIL_RESULT_UNAVAILABLE", "EMAIL_RUN_AMBIGUOUS", "EMAIL_TEMPLATE_INVALID", "EMAIL_VERSION_NOT_FOUND", "EXPORT_PROVIDER_ERROR", "EXPORT_UNSUPPORTED", "FIELD_NAME_COLLISION", "FIELD_NOT_FOUND", "FIELD_TYPE_MISMATCH", "FIGMA_ACCESS_DENIED", "FIGMA_CONVERSION_FAILED", "FIGMA_FRAME_NOT_FOUND", "FIGMA_NOT_CONNECTED", "FIGMA_UNAVAILABLE", "FIGMA_URL_INVALID", "FLOW_NOT_FOUND", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "INSIGHT_NOT_FOUND", "INSUFFICIENT_CREDITS", "INSUFFICIENT_PERMISSIONS", "INSUFFICIENT_ROLE", "INTEGRATION_NOT_CONNECTED", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_EMAIL", "INVALID_PAYLOAD", "INVALID_REQUEST", "LIQUID_RENDER_ERROR", "METHOD_NOT_ALLOWED", "MISSING_EMAIL", "NO_ELIGIBLE_RECIPIENTS", "NO_PUBLISHED_AUTOMATION", "NOT_FOUND", "NOT_IMPLEMENTED", "ORG_SCOPE_REQUIRED", "PAYLOAD_SCHEMA_EMAIL_REQUIRED", "PAYLOAD_TOO_LARGE", "PREVIEW_NOT_FOUND", "PUBLISH_VALIDATION_FAILED", "RATE_LIMITED", "RECIPIENT_UNSUBSCRIBED", "REFERENCE_EMAIL_NOT_FOUND", "RESUBSCRIBE_NOT_ALLOWED", "RUN_IN_PROGRESS", "RUN_NOT_CANCELLABLE", "RUN_NOT_PAUSABLE", "RUN_NOT_PAUSED", "RUN_NOT_RESUMABLE", "RUN_START_FAILED", "RUN_STOP_FAILED", "SEND_NOT_CANCELLABLE", "SEND_NOT_FOUND", "SEND_NOT_PAUSABLE", "SEND_NOT_RESUMABLE", "SEND_QUOTA_EXCEEDED", "SERVICE_UNAVAILABLE", "TEMPLATE_NOT_FOUND", "TEST_RECIPIENT_NOT_ALLOWED", "TRIGGER_ALREADY_EXISTS", "TRIGGER_EVENT_NOT_FOUND", "TRIGGER_HAS_DEPENDENT_AUTOMATIONS", "TRIGGER_IMMUTABLE", "TRIGGER_INSTANCE_NOT_FOUND", "TRIGGER_LIMIT_REACHED", "TRIGGER_NOT_FIREABLE", "UPLOAD_IN_PROGRESS", "UPLOAD_NOT_FOUND", "UPLOAD_NOT_RECEIVED" ] }, "EmailGenerateTextResponse": { "type": "object", "properties": { "response": { "type": "string", "minLength": 1 } }, "required": [ "response" ], "additionalProperties": false }, "EmailGenerateGeneratedResponse": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "previewImage": { "type": "string", "format": "uri" }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "subjectLine": { "type": "string" }, "title": { "type": "string" } }, "required": [ "emailId", "emailVersionId", "html", "group" ], "additionalProperties": false }, "EmailGenerateRequest": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "What the email is about — campaign goal, key content, offer, tone. The more specific (product names, dates, discount, audience), the better the design." }, "contentUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 8, "description": "Up to 8 source URLs to build the email FROM — each is crawled and synthesized into one email (newsletters, recaps, product roundups)." }, "referenceEmailId": { "type": "string", "description": "The `emailId` of an existing design to redraw in this brand's voice — one of this brand's own designs (GET /v1/emails) or a public gallery template (GET /v1/templates). Its layout and structure are the reference; the copy, imagery and styling become this brand's." }, "category": { "type": "string", "enum": [ "welcome", "onboarding", "newsletter", "content", "event-invitation", "event-reminder", "event-recap", "product-launch", "product-update", "product-pitch", "promotional", "cart-abandonment", "re-engagement", "subscription", "feedback-request", "referral", "company-news", "fundraising", "order-confirmation", "shipping-update", "receipt", "password-reset", "verification", "security-alert", "account-update", "notification", "support", "internal", "business", "general" ], "description": "Email category that steers the design treatment (exemplars, hero recipe, personalization) — mirrors what the in-app agent infers per request. One of: welcome, onboarding, newsletter, content, event-invitation, event-reminder, event-recap, product-launch, product-update, product-pitch, promotional, cart-abandonment, re-engagement, subscription, feedback-request, referral, company-news, fundraising, order-confirmation, shipping-update, receipt, password-reset, verification, security-alert, account-update, notification, support, internal, business, general. Omit for a general treatment. Transactional categories (receipt, password-reset, order-confirmation, …) steer receipt/reset design conventions; to DELIVER those emails, wire the design into an automation with a trigger and a transactional-purpose sending domain, then fire the trigger." }, "subjectLine": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Inbox subject line to set on the design (`subjectLine` — distinct from `title`, the canvas name). Sends still take an explicit per-send `subject`; this is the design's default, seeded into the send dialog and returned by `GET /v1/emails/{emailId}`." }, "lang": { "type": "string", "enum": [ "en", "de", "fr", "es", "pt", "it", "nl", "pl", "sv", "da", "no", "fi", "cs", "sk", "hu", "ro", "bg", "el", "tr", "ru", "uk", "hr", "sr", "sl", "lt", "lv", "et", "ca", "ar", "he", "fa", "ur", "hi", "bn", "th", "vi", "id", "ms", "tl", "ja", "ko", "zh-Hans", "zh-Hant", "sw", "af" ], "description": "ISO 639-1 language code of the email's copy (or zh-Hans / zh-Hant). Omit and Brew's language model reads it from the finished body; a value you set is kept and never re-detected. Becomes the HTML document's lang (and dir for right-to-left languages) on every send and export. One of: en, de, fr, es, pt, it, nl, pl, sv, da, no, fi, cs, sk, hu, ro, bg, el, tr, ru, uk, hr, sr, sl, lt, lv, et, ca, ar, he, fa, ur, hi, bn, th, vi, id, ms, tl, ja, ko, zh-Hans, zh-Hant, sw, af." }, "groupId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "File the design under an existing group (`grp_…`), or `ungrouped`. Mutually exclusive with `groupName`." }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60, "description": "File the design under a group resolved (or created) by this name. Mutually exclusive with `groupId`." } }, "required": [ "prompt" ], "additionalProperties": false }, "EmailImportResponse": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "previewImage": { "type": "string", "format": "uri" }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "subjectLine": { "type": "string" }, "title": { "type": "string" }, "assetReport": { "type": "object", "properties": { "discovered": { "type": "integer", "minimum": 0 }, "rehosted": { "type": "integer", "minimum": 0 }, "retained": { "type": "integer", "minimum": 0 }, "stripped": { "type": "integer", "minimum": 0 }, "dropped": { "type": "integer", "minimum": 0, "default": 0 }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "fetch_failed_retained", "non_image_resource_retained", "social_icon_substituted", "tracking_pixel_dropped", "unsafe_url_stripped", "unsupported_resource_retained", "upload_failed_retained", "inline_asset_retained", "attachment_dropped", "embedded_reference_unresolved", "tailwind_config_unresolved", "tailwind_class_dropped", "foreign_component_dropped", "element_dropped" ] }, "location": { "type": "string", "enum": [ "background", "css-url", "data-src", "data-srcset", "markup", "module", "preload", "src", "srcset", "stylesheet", "vml-src" ] }, "host": { "type": "string" } }, "required": [ "code", "location" ], "additionalProperties": false } } }, "required": [ "discovered", "rehosted", "retained", "stripped", "warnings" ], "additionalProperties": false } }, "required": [ "emailId", "emailVersionId", "html", "group", "assetReport" ], "additionalProperties": false }, "EmailImportRequest": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "html", "mjml", "jsx", "eml" ], "description": "`html`: an HTML email document or fragment · `mjml`: MJML markup · `jsx`: React Email — a module with a default-exported component, or a bare `` element · `eml`: a saved RFC 822 message" }, "content": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "subjectLine": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Inbox subject line to set on the design (`subjectLine` — distinct from `title`, the canvas name). Sends still take an explicit per-send `subject`; this is the design's default, seeded into the send dialog and returned by `GET /v1/emails/{emailId}`." }, "baseUrl": { "type": "string", "format": "uri" }, "groupId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "File the design under an existing group (`grp_…`), or `ungrouped`. Mutually exclusive with `groupName`." }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60, "description": "File the design under a group resolved (or created) by this name. Mutually exclusive with `groupId`." } }, "required": [ "format", "content" ], "additionalProperties": false }, "FigmaToEmailResponse": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "jsx", "html" ] }, "content": { "type": "string", "minLength": 1 }, "warningCount": { "type": "integer", "minimum": 0 }, "exportedNodeCount": { "type": "integer", "minimum": 0 }, "previewImage": { "type": "string", "format": "uri" }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "subjectLine": { "type": "string" } }, "required": [ "emailId", "emailVersionId", "title", "format", "content", "warningCount", "exportedNodeCount", "group" ], "additionalProperties": false }, "FigmaToEmailRequest": { "type": "object", "properties": { "hrefMap": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxProperties": 100, "description": "Optional Figma node-id to destination map (at most 100 entries). Overrides authored text/CTA links and prevents linked content being flattened into artwork." }, "figmaUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "description": "A figma.com design, file, or prototype URL for a specific frame. The URL must include a node-id query parameter." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional design title; defaults to the Figma frame name." }, "groupId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "File the design under an existing group (`grp_…`), or `ungrouped`. Mutually exclusive with `groupName`." }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60, "description": "File the design under a group resolved (or created) by this name. Mutually exclusive with `groupId`." }, "subjectLine": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Inbox subject line to set on the design (`subjectLine` — distinct from `title`, the canvas name). Sends still take an explicit per-send `subject`; this is the design's default, seeded into the send dialog and returned by `GET /v1/emails/{emailId}`." }, "format": { "type": "string", "enum": [ "jsx", "html" ], "default": "jsx", "description": "Source representation returned in `content`: React Email JSX by default, or rendered email-safe HTML." } }, "required": [ "figmaUrl" ], "additionalProperties": false }, "EmailGenerateResponse": { "anyOf": [ { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "previewImage": { "type": "string", "format": "uri" }, "group": { "type": [ "object", "null" ], "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "groupId", "groupName" ], "additionalProperties": false }, "subjectLine": { "type": "string" }, "title": { "type": "string" } }, "required": [ "emailId", "emailVersionId", "html", "group" ], "additionalProperties": false }, { "type": "object", "properties": { "response": { "type": "string", "minLength": 1 } }, "required": [ "response" ], "additionalProperties": false } ] }, "EmailEditRequest": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The edit to make, in plain language — e.g. \"swap the hero for the spring campaign image and tighten the CTA copy\". Scoped edits beat full rewrites. Omit to only patch `title`, `subjectLine`, `lang` or `groupId` (at least one of the five is required)." }, "emailVersionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Pin the edit to a specific source version (from `GET /v1/emails/{emailId}?include=versions`). Requires `prompt`. Omit to edit the current latest." }, "contentUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 8, "description": "Up to 8 URLs whose content grounds the edit (e.g. the product page the new section should describe)." }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Rename the design (its canvas name, distinct from `subjectLine`). Deterministic and free; alone it patches the head in place, with `prompt` the new version inherits it." }, "subjectLine": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Inbox subject line to set on the design (`subjectLine` — distinct from `title`, the canvas name). Sends still take an explicit per-send `subject`; this is the design's default, seeded into the send dialog and returned by `GET /v1/emails/{emailId}`." }, "lang": { "type": [ "string", "null" ], "enum": [ "en", "de", "fr", "es", "pt", "it", "nl", "pl", "sv", "da", "no", "fi", "cs", "sk", "hu", "ro", "bg", "el", "tr", "ru", "uk", "hr", "sr", "sl", "lt", "lv", "et", "ca", "ar", "he", "fa", "ur", "hi", "bn", "th", "vi", "id", "ms", "tl", "ja", "ko", "zh-Hans", "zh-Hant", "sw", "af", null ], "description": "Set the language of the email (ISO 639-1, or zh-Hans / zh-Hant). Part of the free envelope patch: no AI run, no new version. Once set it is kept: Brew no longer re-detects it after edits. null clears a language you set, and Brew reads it again from the email." }, "groupId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "description": "Move the design into this existing group (`grp_…`); `null` moves it to Ungrouped; omit to leave its group alone. Part of the free envelope patch: no AI run, no new version." } }, "additionalProperties": false }, "EmailsDeleteResponse": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "deleted": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "already_deleted", "not_found" ], "description": "Present when `deleted` is false: `already_deleted` means this design was hard-deleted earlier (see `deletedAt`) — it is gone, do not retry; `not_found` means no design with this id exists on this brand." }, "deletedAt": { "type": "string", "format": "date-time", "description": "ISO timestamp of the earlier hard-delete (present with `reason: \"already_deleted\"`)." } }, "required": [ "emailId", "deleted" ], "additionalProperties": false }, "EmailCloneRequest": { "type": "object", "properties": { "emailVersionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Exact source version to clone (from GET /v1/emails/{emailId}?include=versions). Omit to clone the current latest version." }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name for the clone. Omit for `Copy of `; rename later with `PATCH /v1/emails/{emailId} { title }` over HTTP, update_email_metadata over MCP." }, "groupId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "File the design under an existing group (`grp_…`), or `ungrouped`. Mutually exclusive with `groupName`." }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60, "description": "File the design under a group resolved (or created) by this name. Mutually exclusive with `groupId`." } }, "additionalProperties": false }, "EmailRestoreRequest": { "type": "object", "properties": { "emailVersionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "One of the design’s versions (`GET /v1/emails/{emailId}?include=versions`)." } }, "required": [ "emailVersionId" ], "additionalProperties": false }, "EmailExportResponse": { "type": "object", "properties": { "emailId": { "type": "string" }, "provider": { "type": "string", "enum": [ "braze", "brevo", "hubspot", "klaviyo", "mailchimp", "mailjet", "iterable", "postmark", "onesignal", "mailgun", "sendgrid", "loops" ] }, "providerName": { "type": "string" }, "templateName": { "type": "string" }, "templateId": { "type": "string" }, "dryRun": { "type": "boolean" } }, "required": [ "emailId", "provider", "providerName", "templateName", "dryRun" ] }, "EmailExportRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "braze", "brevo", "hubspot", "klaviyo", "mailchimp", "mailjet", "iterable", "postmark", "onesignal", "mailgun", "sendgrid", "loops" ], "description": "The connected ESP to export the design to as a template." }, "templateName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Template name in the ESP. Defaults to the email title." }, "senderEmail": { "type": "string", "maxLength": 320, "format": "email", "description": "Active sender email for Brevo or Mailjet. Omit when the account has exactly one active sender; Brew selects it automatically." }, "dryRun": { "type": "boolean", "description": "Validate the design, brand ownership, and ESP connection without creating a template." } }, "required": [ "provider" ], "additionalProperties": false }, "EmailAuditResponse": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "rulesetVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "auditId": { "type": "string", "format": "uuid" }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "auditedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "policy": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "marketing", "transactional", "unknown" ] }, "source": { "type": "string", "enum": [ "provided", "defaulted", "trusted_adapter", "inferred" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "unsubscribe": { "type": "string", "enum": [ "required", "not_required", "not_evaluated" ] } }, "required": [ "purpose", "source", "unsubscribe" ], "additionalProperties": false }, "summary": { "type": "object", "properties": { "blockers": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 }, "warnings": { "type": "integer", "minimum": 0 }, "info": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "blockers", "errors", "warnings", "info", "total" ], "additionalProperties": false }, "checks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "passed" ] }, "durationMs": { "type": "integer", "minimum": 0 }, "findingCount": { "type": "number", "enum": [ 0 ] } }, "required": [ "id", "status", "durationMs", "findingCount" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "issues" ] }, "durationMs": { "type": "integer", "minimum": 0 }, "findingCount": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "status", "durationMs", "findingCount" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "not_applicable" ] }, "reason": { "type": "string", "enum": [ "no_remote_links", "no_remote_images", "no_remote_assets", "missing_copy", "requires_sending_domain", "send_transport_owned", "requires_audience_context", "separate_deliverability_test", "transactional_purpose", "unknown_purpose" ] } }, "required": [ "id", "status", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "unavailable" ] }, "reason": { "type": "string", "enum": [ "timeout", "upstream", "invalid_response" ] }, "retryable": { "type": "boolean" }, "durationMs": { "type": "integer", "minimum": 0 } }, "required": [ "id", "status", "reason", "retryable", "durationMs" ], "additionalProperties": false } ] }, "maxItems": 32 }, "metrics": { "type": "object", "properties": { "htmlBytes": { "type": "integer", "minimum": 0 }, "linkCount": { "type": "integer", "minimum": 0 }, "imageCount": { "type": "integer", "minimum": 0 }, "gifCount": { "type": "integer", "minimum": 0 }, "loadedSize": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "exact" ] }, "htmlBytes": { "type": "integer", "minimum": 0 }, "remoteAssetBytes": { "type": "integer", "minimum": 0 }, "totalBytes": { "type": "integer", "minimum": 0 }, "assetCount": { "type": "integer", "minimum": 0 } }, "required": [ "status", "htmlBytes", "remoteAssetBytes", "totalBytes", "assetCount" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "lower_bound" ] }, "htmlBytes": { "type": "integer", "minimum": 0 }, "knownRemoteAssetBytes": { "type": "integer", "minimum": 0 }, "knownTotalBytes": { "type": "integer", "minimum": 0 }, "unknownAssetCount": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "status", "htmlBytes", "knownRemoteAssetBytes", "knownTotalBytes", "unknownAssetCount" ], "additionalProperties": false } ] } }, "required": [ "htmlBytes", "linkCount", "imageCount", "gifCount", "loadedSize" ], "additionalProperties": false }, "findings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "ruleId": { "type": "string", "minLength": 1, "maxLength": 128 }, "category": { "type": "string", "enum": [ "compliance", "links", "images", "accessibility", "compatibility", "copy", "size", "markup" ] }, "severity": { "type": "string", "enum": [ "blocker", "error", "warning", "info" ] }, "impact": { "type": "string", "enum": [ "block", "confirm", "advisory" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "remediation": { "type": "string", "minLength": 1, "maxLength": 1000 }, "occurrenceCount": { "type": "integer", "exclusiveMinimum": 0, "description": "Total occurrences of this RULE across the email, stamped on every representative finding of the rule so the total survives representative truncation. Reconcile by max per rule — summing across findings overcounts." }, "sources": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 16 }, "standards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "url": { "type": "string", "maxLength": 2048, "pattern": "^https?:\\/\\/" } }, "required": [ "id" ], "additionalProperties": false }, "maxItems": 8 }, "evidence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "http" ] }, "status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "failure": { "type": "string", "enum": [ "dns", "tls", "connect", "timeout", "private_host", "redirects" ] } }, "required": [ "kind", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "clients" ] }, "unsupported": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 24 } }, "required": [ "kind", "unsupported" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "judgment" ] }, "question": { "type": "string", "minLength": 1, "maxLength": 64 }, "probability": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "kind", "question", "probability" ], "additionalProperties": false } ] }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "subject" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "preview_text" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "index": { "type": "integer", "minimum": 0 }, "displayUrl": { "type": "string", "maxLength": 300 } }, "required": [ "kind", "index", "displayUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ] }, "index": { "type": "integer", "minimum": 0 }, "displayUrl": { "type": "string", "maxLength": 300 } }, "required": [ "kind", "index", "displayUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "element" ] }, "selector": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "kind", "selector" ], "additionalProperties": false } ] } }, "required": [ "id", "ruleId", "category", "severity", "impact", "message", "remediation", "sources", "target" ], "additionalProperties": false }, "maxItems": 100 }, "totalFindings": { "type": "integer", "minimum": 0 }, "findingsTruncated": { "type": "boolean" }, "completion": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete" ] }, "readiness": { "type": "string", "enum": [ "ready", "needs_review", "not_ready" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "status", "readiness", "score" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "partial" ] }, "readiness": { "type": "string", "enum": [ "unknown", "not_ready" ] }, "score": { "type": "null" } }, "required": [ "status", "readiness", "score" ], "additionalProperties": false } ] } }, "required": [ "schemaVersion", "rulesetVersion", "auditId", "contentHash", "auditedAt", "expiresAt", "policy", "summary", "checks", "metrics", "findings", "totalFindings", "findingsTruncated", "completion" ], "additionalProperties": false }, "EmailAuditRequest": { "anyOf": [ { "type": "object", "properties": { "emailHtml": { "type": "string", "minLength": 1, "description": "Rendered email HTML." }, "subject": { "type": "string", "maxLength": 1000, "description": "Subject line to judge. Omit it and the subject is not evaluated; an empty string is reported as a missing subject." }, "previewText": { "type": "string", "maxLength": 1000, "description": "Inbox preview text. Omit it to read the preheader from the email." }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "marketing (unsubscribe link and postal address required) or transactional. Omit it and the audit infers the purpose from the content." } }, "required": [ "emailHtml" ], "additionalProperties": false }, { "type": "object", "properties": { "emailJsx": { "type": "string", "minLength": 1, "description": "React Email JSX, rendered by Brew before the audit." }, "subject": { "type": "string", "maxLength": 1000, "description": "Subject line to judge. Omit it and the subject is not evaluated; an empty string is reported as a missing subject." }, "previewText": { "type": "string", "maxLength": 1000, "description": "Inbox preview text. Omit it to read the preheader from the email." }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "marketing (unsubscribe link and postal address required) or transactional. Omit it and the audit infers the purpose from the content." } }, "required": [ "emailJsx" ], "additionalProperties": false }, { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A saved email design, rendered exactly as a send renders it." }, "emailVersionId": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The exact design version; omit for the latest version." }, "subject": { "type": "string", "maxLength": 1000, "description": "Subject line to judge. Omit it and the subject is not evaluated; an empty string is reported as a missing subject." }, "previewText": { "type": "string", "maxLength": 1000, "description": "Inbox preview text. Omit it to read the preheader from the email." }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "marketing (unsubscribe link and postal address required) or transactional. Omit it and the audit infers the purpose from the content." } }, "required": [ "emailId" ], "additionalProperties": false } ] }, "EmailClientPreviewResponse": { "type": "object", "properties": { "previewId": { "type": "string" }, "emailId": { "type": "string" }, "emailVersionId": { "type": "string", "description": "Portable version ID when present. previewId pins the saved snapshot." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ], "description": "The job: `queued` or `running` until every client settles, then `completed`, `partially_completed` (some screenshots failed) or `failed`." }, "previews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string", "enum": [ "gmail", "outlook", "apple", "yahoo", "other" ] }, "os": { "type": "string" }, "dark": { "type": "boolean" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "reason": { "type": "string", "enum": [ "pending", "upstream_unavailable", "unsupported_client", "render_failed", "rehost_failed", "expired", "submission_unknown", "authorization_changed", "snapshot_unavailable" ] }, "retryable": { "type": "boolean" } }, "required": [ "id", "label", "category", "os", "dark", "status", "imageUrl", "retryable" ], "additionalProperties": false } }, "pending": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "nextPollAfterMs": { "type": "integer", "minimum": 0 }, "credits": { "type": "object", "properties": { "cost": { "type": "number" }, "status": { "type": "string", "enum": [ "reserved", "settled", "released" ] } }, "required": [ "cost", "status" ], "additionalProperties": false } }, "required": [ "previewId", "emailId", "status", "previews", "pending", "createdAt", "expiresAt", "nextPollAfterMs", "credits" ], "additionalProperties": false }, "EmailClientPreviewRequest": { "type": "object", "properties": { "emailVersionId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Exact email version to render; omit for latest." }, "clients": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 12, "description": "Client ids to render. Omit for popular Gmail, Outlook, Apple Mail and iOS clients. Supported: gmailcom-lm_chrcurrent_win10 = Gmail (Web); gmailcom-dm_chrcurrent_win10 = Gmail (Web, Dark); android16_gmailapp_pixel10_lm = Gmail (Android); android16_gmailapp_pixel10_dm = Gmail (Android, Dark); outlook2021_win11_lm_dt = Outlook 2021 (Windows); outlook2021_win11_dm_dt = Outlook 2021 (Windows, Dark); o365_w10_lm_dt = Outlook 365 (Windows); outlookcom-lm_chrcurrent_win10 = Outlook.com (Web); applemail16 = Apple Mail (macOS); applemail16_dm = Apple Mail (macOS, Dark); iphone16_18 = Apple Mail (iOS); iphone16_18_dm = Apple Mail (iOS, Dark); yahoocom-lm_chrcurrent_win10 = Yahoo Mail (Web)." } }, "additionalProperties": false }, "EmailInboxPlacementTest": { "type": "object", "properties": { "testId": { "type": "string" }, "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "phase": { "type": "string", "enum": [ "sending", "collecting" ] }, "domainId": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string" }, "emailVersionId": { "type": "string" }, "seedCount": { "type": "integer", "minimum": 0 }, "results": { "type": [ "object", "null" ], "properties": { "overall": { "type": "object", "properties": { "provider": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "inbox": { "type": "integer", "minimum": 0 }, "spam": { "type": "integer", "minimum": 0 }, "missing": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "categories": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "folders": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "authentication": { "type": "object", "properties": { "spf": { "type": "string", "enum": [ "pass", "fail", "mixed" ] }, "dkim": { "type": "string", "enum": [ "pass", "fail", "mixed" ] }, "dmarc": { "type": "string", "enum": [ "pass", "fail", "mixed" ] } }, "additionalProperties": false } }, "required": [ "provider", "total", "inbox", "spam", "missing", "pending" ], "additionalProperties": false }, "byProvider": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "inbox": { "type": "integer", "minimum": 0 }, "spam": { "type": "integer", "minimum": 0 }, "missing": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "categories": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "folders": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "authentication": { "type": "object", "properties": { "spf": { "type": "string", "enum": [ "pass", "fail", "mixed" ] }, "dkim": { "type": "string", "enum": [ "pass", "fail", "mixed" ] }, "dmarc": { "type": "string", "enum": [ "pass", "fail", "mixed" ] } }, "additionalProperties": false } }, "required": [ "provider", "total", "inbox", "spam", "missing", "pending" ], "additionalProperties": false } }, "authentication": { "type": "object", "properties": { "spf": { "type": "string" }, "dkim": { "type": "string" }, "dmarc": { "type": "string" } }, "additionalProperties": false }, "spamFilter": { "type": "object", "properties": { "flagged": { "type": "boolean" }, "score": { "type": "number" }, "threshold": { "type": "number" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "description": { "type": "string" } }, "required": [ "name", "score" ], "additionalProperties": false } } }, "required": [ "flagged", "score", "threshold", "rules" ], "additionalProperties": false }, "microsoftFilter": { "type": "object", "properties": { "spamConfidenceLevel": { "type": "number" }, "bulkComplaintLevel": { "type": "number" }, "sampleCount": { "type": "integer", "minimum": 0 }, "junked": { "type": "boolean" } }, "required": [ "spamConfidenceLevel", "bulkComplaintLevel", "sampleCount", "junked" ], "additionalProperties": false }, "spoofingDetected": { "type": "boolean" }, "headers": { "type": "object", "properties": { "listUnsubscribe": { "type": "boolean" }, "oneClickUnsubscribe": { "type": "boolean" }, "plainTextPart": { "type": "boolean" }, "feedbackId": { "type": "boolean" } }, "required": [ "listUnsubscribe", "oneClickUnsubscribe", "plainTextPart", "feedbackId" ], "additionalProperties": false } }, "required": [ "overall", "byProvider", "authentication" ], "additionalProperties": false }, "diagnosis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "spoofing_detected", "aggregate_auth_failure", "provider_auth_failure", "microsoft_junk_filtering", "provider_spam_placement", "promotions_tab_placement", "bulk_folder_placement", "content_filter_flagged", "content_rule", "missing_list_unsubscribe", "missing_plain_text_part" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "provider": { "type": "string" }, "summary": { "type": "string" }, "remediation": { "type": "string" } }, "required": [ "id", "severity", "summary", "remediation" ], "additionalProperties": false } }, "errorMessage": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "testId", "emailId", "status", "domainId", "seedCount", "results", "createdAt", "updatedAt" ], "additionalProperties": false }, "EmailInboxPlacementRequest": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Verified sending domain id to test FROM (the seed send goes out on this domain, so the result reflects its real reputation)." }, "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Subject line for the seed send; defaults to the email title. A VARIANT dimension — run several tests on one design varying only the subject to compare placement." }, "previewText": { "type": "string", "maxLength": 200, "description": "Preview/preheader text for the seed send — overrides the design's JSX for this test. A VARIANT dimension, like `subject`: run several tests varying only the preheader to compare placement." }, "emailVersionId": { "type": "string", "minLength": 1, "description": "Pin a specific design version already available in the current surface; omit for the latest. A VARIANT dimension — test two versions of one design against each other." }, "providers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 30, "description": "Restrict seed mailbox providers (e.g. [\"gmail.com\",\"outlook.com\",\"yahoo.com\"]); omit for a broad default spread." } }, "required": [ "domainId" ], "additionalProperties": false }, "EmailInboxPlacementTestList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "testId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "phase": { "type": "string", "enum": [ "sending", "collecting" ] }, "domainId": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string" }, "emailVersionId": { "type": "string" }, "seedCount": { "type": "integer", "minimum": 0 }, "overall": { "type": [ "object", "null" ], "properties": { "provider": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "inbox": { "type": "integer", "minimum": 0 }, "spam": { "type": "integer", "minimum": 0 }, "missing": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "categories": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "folders": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "authentication": { "type": "object", "properties": { "spf": { "type": "string", "enum": [ "pass", "fail", "mixed" ] }, "dkim": { "type": "string", "enum": [ "pass", "fail", "mixed" ] }, "dmarc": { "type": "string", "enum": [ "pass", "fail", "mixed" ] } }, "additionalProperties": false } }, "required": [ "provider", "total", "inbox", "spam", "missing", "pending" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "testId", "status", "domainId", "subject", "seedCount", "overall", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "EmailGroupsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "groupName": { "type": "string", "minLength": 1, "maxLength": 60 }, "emailCount": { "type": "integer", "minimum": 0 }, "createdBy": { "type": "string", "description": "Group creator as Brew shows it: a name or \"Former member\"; absent for an organization API key or when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." } }, "required": [ "groupId", "groupName", "emailCount" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "EmailGroupCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Named folder label (1–60 chars). Reserved names `Ungrouped` / `ungrouped` / `__ungrouped__` are rejected." }, "emailIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50, "description": "Designs (`emailId`) to move into this group; up to 50 in one call, which is one request against the rate limit. They land at the top in this order; designs already in the group keep their place. Designs that cannot move come back in `notMoved` — send the `retry` ones again." } }, "required": [ "name" ], "additionalProperties": false }, "EmailGroupPatchRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Named folder label (1–60 chars). Reserved names `Ungrouped` / `ungrouped` / `__ungrouped__` are rejected." }, "emailIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50, "description": "Designs (`emailId`) to move into this group; up to 50 in one call, which is one request against the rate limit. They land at the top in this order; designs already in the group keep their place. Designs that cannot move come back in `notMoved` — send the `retry` ones again." } }, "additionalProperties": false }, "EmailGroupDeleteResponse": { "type": "object", "properties": { "groupId": { "type": "string", "minLength": 1, "maxLength": 64 }, "deleted": { "type": "boolean" } }, "required": [ "groupId", "deleted" ], "additionalProperties": false }, "SendsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sendId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "campaign", "automation" ] }, "messageClass": { "type": "string", "enum": [ "marketing", "transactional" ] }, "automationId": { "type": "string", "minLength": 1 }, "nodeId": { "type": "string", "minLength": 1 }, "automationRunId": { "type": "string", "minLength": 1 }, "audienceRunId": { "type": "string", "minLength": 1 }, "triggerInstanceId": { "type": "string", "minLength": 1 }, "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "scheduled", "queued", "running", "paused", "completed", "partially_completed", "failed", "canceled" ] }, "approvalState": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "pauseReason": { "type": "string", "enum": [ "manual", "plan_limit", "domain_unsendable" ], "description": "Why a paused send is held. `plan_limit`: the plan has too few sends left this period. `domain_unsendable`: its sending domain stopped passing DNS; fails after 7 days. Both resume on their own and can be canceled. `manual`: its operator paused the gradual ramp; resume it to continue." }, "subject": { "type": "string" }, "previewText": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Full from address; its host must be the domain named by `domainId`." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Sender display name." } }, "required": [ "email" ], "additionalProperties": false }, "replyTo": { "type": "string" }, "domainId": { "type": "string" }, "audienceId": { "type": "string", "minLength": 1 }, "audienceName": { "type": "string", "minLength": 1 }, "recipientCount": { "type": "integer", "minimum": 0 }, "scheduledAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "stats": { "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 } }, "required": [ "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "accepted": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "delayed": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "providerSuppressed": { "type": "integer", "minimum": 0 }, "preSendSkipped": { "type": "integer", "minimum": 0 }, "renderFailed": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accepted", "pending", "delayed", "delivered", "bounced", "failed", "providerSuppressed", "preSendSkipped", "renderFailed", "updatedAt" ], "additionalProperties": false }, "gradualSend": { "type": "object", "properties": { "startingPercentage": { "type": "number", "minimum": 0.1, "maximum": 100 }, "incrementPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "interval": { "oneOf": [ { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 24 }, "unit": { "type": "string", "enum": [ "hour" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 30 }, "unit": { "type": "string", "enum": [ "day" ] } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA timezone used to preserve local wall-clock time for day intervals." }, "rampEndsAt": { "type": "string", "format": "date-time", "description": "Rolling stuck-send deadline, re-stamped at every batch. Not when the ramp ends." }, "currentTranche": { "type": "integer", "exclusiveMinimum": 0 }, "sentSoFar": { "type": "integer", "minimum": 0 }, "pausedAt": { "type": "string", "format": "date-time" }, "pauseReason": { "type": "string", "enum": [ "manual" ] }, "resumedAt": { "type": "string", "format": "date-time" } }, "required": [ "startingPercentage", "incrementPercentage", "interval", "timeZone" ], "additionalProperties": false }, "smartSend": { "type": "object", "properties": { "windowEndsAt": { "type": "string", "format": "date-time", "description": "Every recipient is sent by then: 24 hours after timing starts." }, "assignedViaModel": { "type": "integer", "minimum": 0, "description": "Recipients timed from their own opens and clicks." }, "assignedImmediately": { "type": "integer", "minimum": 0, "description": "Recipients with no opens or clicks, sent right away." }, "modelFallbacks": { "type": "integer", "minimum": 0, "description": "Recipients with history that could not be timed, sent right away." } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "provider_suppressed", "suppressed", "quota_skipped", "received", "unsubscribed" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "recipientEmail": { "type": "string" }, "url": { "type": "string" }, "machineGenerated": { "type": "boolean" }, "clickBotReason": { "type": "string" } }, "required": [ "eventType", "occurredAt" ], "additionalProperties": false } } }, "required": [ "sendId", "kind", "emailId", "status", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "SendEmailTestResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ] }, "recipient": { "type": "string" } }, "required": [ "status", "recipient" ], "additionalProperties": false }, "SendsPostResponse": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "scheduled" ] }, "sendId": { "type": "string", "minLength": 1 }, "scheduledAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } } }, "required": [ "status", "sendId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending_approval" ] }, "sendId": { "type": "string", "minLength": 1 }, "scheduledAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } } }, "required": [ "status", "sendId" ], "additionalProperties": false } ] }, "SendEmailRequest": { "anyOf": [ { "type": "object", "properties": { "test": { "type": "boolean", "enum": [ true ] }, "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1 }, "previewText": { "type": "string", "maxLength": 200, "description": "Inbox preheader for this test send — overrides the design's JSX . Omit to deliver the design's own preview line." }, "to": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$", "description": "The one address that receives this test. Max 5: you, brand teammates, or your company or verified domain." }, "replyTo": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$" }, "domainId": { "type": "string", "minLength": 1, "description": "OPTIONAL verified sending domain for this test. Omit for the Brew default sender (hello@email.brew.new). Must be a verified domain owned by this org/brand — an unverified or foreign domain is rejected (404/422), never silently downgraded to the Brew default." }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Full from address; its host must be the domain named by `domainId`." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Sender display name." } }, "required": [ "email" ], "additionalProperties": false, "description": "Sender override `{ email, name? }`; the address must be on the send domain. Omit to use the domain defaults." }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "Example values for {{ var | fallback }} merge tags in the subject, previewText, and body. A supplied value wins over contact fields and the declared fallback; undefined variables render their fallback (or empty). Max 25 entries; keys must match the merge-tag grammar (letter/_/$ start, then word chars/dots/$, max 64 chars); values max 256 chars." }, "payload": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SendPayloadValue" }, "description": "Nested JSON template data, exposed to the ONE Liquid engine as trigger.* / payload.* and as top-level keys. Nested values are always legal and resolve via dotted access ({{ plan.name }}) and {% for %}. Flat `variables` resolve {{ tag | fallback }} merge tags at higher precedence; send both if a design mixes syntaxes." } }, "required": [ "test", "emailId", "subject", "to" ], "additionalProperties": false }, { "type": "object", "properties": { "test": { "type": "boolean", "enum": [ false ] }, "emailId": { "type": "string", "minLength": 1 }, "emailVersionId": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1 }, "previewText": { "type": "string", "maxLength": 200, "description": "Inbox preheader for THIS send — overrides the design's JSX . Omit to deliver the design's own preview line (returned as `previewText` on `GET /v1/emails/{emailId}`)." }, "replyTo": { "type": "string", "description": "Reply-to address. Accepts a bare email (`a@b.com`) or the display-name form (`Name `)." }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Full from address; its host must be the domain named by `domainId`." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Sender display name." } }, "required": [ "email" ], "additionalProperties": false, "description": "Sender override `{ email, name? }`; the address must be on the send domain. Omit to use the domain defaults." }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Consent provenance for inline recipients that are not yet contacts; each is created as a subscribed contact carrying this record. Never re-subscribes an existing opt-out." }, "domainId": { "type": "string", "minLength": 1 }, "audienceId": { "type": "string", "minLength": 1, "description": "A saved audience id, or \"all\" to target EVERY contact in the brand." }, "to": { "anyOf": [ { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$" }, "minItems": 1, "maxItems": 50 } ], "description": "Inline recipient addresses (max 50). Mutually exclusive with `audienceId`." }, "scheduledAt": { "type": "string", "format": "date-time" }, "gradualSend": { "type": "object", "properties": { "startingPercentage": { "type": "number", "minimum": 0.1, "maximum": 100 }, "incrementPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "interval": { "oneOf": [ { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 24 }, "unit": { "type": "string", "enum": [ "hour" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 30 }, "unit": { "type": "string", "enum": [ "day" ] } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA timezone used to preserve local wall-clock time for day intervals." } }, "required": [ "startingPercentage", "incrementPercentage", "interval", "timeZone" ], "additionalProperties": false }, "smartSend": { "type": "boolean", "description": "Intelligent Send: true sends each recipient with past opens or clicks at the upcoming hour (within 24 hours) their own history makes them most likely to open, and everyone else right away. Composes with scheduledAt; not with gradualSend." } }, "required": [ "emailId", "subject", "domainId" ], "additionalProperties": false } ] }, "SendPayloadValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SendPayloadValue" }, { "type": "null" } ] }, "maxItems": 250 }, { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/SendPayloadValue" }, { "type": "null" } ] } } ] }, "SendCancelResponse": { "type": "object", "properties": { "sendId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "canceled" ] } }, "required": [ "sendId", "status" ], "additionalProperties": false }, "SendPauseResponse": { "type": "object", "properties": { "sendId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "paused" ] } }, "required": [ "sendId", "status" ], "additionalProperties": false }, "SendResumeResponse": { "type": "object", "properties": { "sendId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "running" ] } }, "required": [ "sendId", "status" ], "additionalProperties": false }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "accepted": { "type": "integer", "minimum": 0, "default": 0 }, "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "providerSuppressed": { "type": "integer", "minimum": 0, "default": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "quotaSkipped": { "type": "integer", "minimum": 0, "default": 0 }, "preSendSkipped": { "type": "integer", "minimum": 0, "default": 0 }, "pending": { "type": "integer", "minimum": 0, "default": 0 }, "deliveryDelayed": { "type": "integer", "minimum": 0 } }, "required": [ "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "failed", "suppressed", "deliveryDelayed" ], "additionalProperties": false }, "rates": { "type": "object", "properties": { "deliveryRate": { "type": [ "number", "null" ] }, "openRate": { "type": [ "number", "null" ] }, "clickRate": { "type": [ "number", "null" ] }, "bounceRate": { "type": [ "number", "null" ] }, "complaintRate": { "type": [ "number", "null" ] }, "unsubscribeRate": { "type": [ "number", "null" ] } }, "required": [ "deliveryRate", "openRate", "clickRate", "bounceRate", "complaintRate", "unsubscribeRate" ], "additionalProperties": false }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "deliveryDelayed": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "providerSuppressed": { "type": "integer", "minimum": 0, "default": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "quotaSkipped": { "type": "integer", "minimum": 0, "default": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 } }, "required": [ "at", "sent", "delivered", "deliveryDelayed", "opened", "clicked", "bounced", "complained", "failed", "suppressed", "unsubscribed" ], "additionalProperties": false } }, "granularity": { "type": "string", "enum": [ "5m", "1h", "1d" ] }, "timeZone": { "type": "string" }, "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "totals", "rates", "buckets", "granularity", "timeZone", "range", "truncated" ], "additionalProperties": false }, "AutomationAnalyticsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "published": { "type": "boolean" }, "triggerEventId": { "type": "string" }, "runs": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 }, "successRate": { "type": [ "number", "null" ] }, "openRate": { "type": [ "number", "null" ] }, "clickRate": { "type": [ "number", "null" ] }, "clickThroughRate": { "type": [ "number", "null" ] }, "unsubscribeRate": { "type": [ "number", "null" ] }, "lastRunAt": { "type": "string", "format": "date-time" }, "lastRunStatus": { "type": "string" } }, "required": [ "automationId", "name", "published", "runs", "completed", "failed", "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "successRate", "openRate", "clickRate", "clickThroughRate", "unsubscribeRate" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "runs": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 } }, "required": [ "runs", "completed", "failed", "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed" ], "additionalProperties": false }, "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "data", "totals", "range", "truncated" ], "additionalProperties": false }, "EventsAnalyticsSuccessResponse": { "anyOf": [ { "$ref": "#/components/schemas/EventsAnalyticsResponse" }, { "$ref": "#/components/schemas/EventsBreakdownResponse" } ] }, "EventsAnalyticsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time" }, "domain": { "type": "string", "enum": [ "email", "automation", "trigger", "inbound" ] }, "eventType": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string" }, "sendId": { "type": "string" }, "emailId": { "type": "string" }, "emailName": { "type": "string" }, "automationId": { "type": "string" }, "automationName": { "type": "string" }, "nodeId": { "type": "string" }, "automationRunId": { "type": "string" }, "triggerInstanceId": { "type": "string" }, "audienceRunId": { "type": "string" }, "triggerEventId": { "type": "string" }, "provider": { "type": "string" }, "machineGenerated": { "type": "boolean" }, "clickBotReason": { "type": "string" }, "openBotReason": { "type": "string" }, "openFetchSource": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "summary": { "type": "string" }, "sendSource": { "type": "string", "enum": [ "audience", "api", "automation_manual", "automation_integration", "automation_custom" ] }, "messageClass": { "type": "string", "enum": [ "marketing", "transactional" ] }, "sendContext": { "type": "string" }, "triggerProvider": { "type": "string" }, "triggerTitle": { "type": "string" } }, "required": [ "id", "occurredAt", "domain", "eventType" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false }, "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "required": [ "data", "pagination", "range" ], "additionalProperties": false }, "EventsBreakdownResponse": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "description": "Email events counted." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "bucket": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "exclusiveMinimum": 0 }, "recipients": { "type": "integer", "minimum": 0, "description": "On a group of opened, clicked or delivered events (its `eventType` key, or the `eventType` filter), unless grouped by `link`: recipients counted once per message sent to them, by the overview's rule, within `range` only; with `bucket`, in the period of their first open or click. Repeat opens and clicks, machine ones, and deliveries a later bounce overturned are not counted. A send's lifetime `stats` can be higher, since they also count clicks recorded before bot screening, which these rows leave out." } }, "required": [ "key", "count" ], "additionalProperties": false }, "description": "The largest 200 groups, largest first. `key` maps each `groupBy` field to its value (`null` when the event has none); `bucket` is the UTC period start; `count` counts events, so one recipient's repeat opens each count. `unsubscribeReason` counts an unsubscribe once per reason it gave." }, "otherCount": { "type": "integer", "minimum": 0, "description": "The summed counts of the groups not listed." }, "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "truncated": { "type": "boolean", "description": "True when the window held more than the 20,000 events one count reads: the counts cover the newest events back to `coveredFrom`. Narrow the window or add `eventType`." }, "coveredFrom": { "type": "string", "format": "date-time", "description": "With `truncated`: every event after this instant is counted; older ones are not." } }, "required": [ "count", "groups", "otherCount", "range", "truncated" ], "additionalProperties": false }, "AutomationsPostRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "nodes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "trigger" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "event" ] }, "triggerEventId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "manualAudience" ] }, "audienceId": { "type": "string" } }, "required": [ "mode", "audienceId" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "sendEmail" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string", "description": "Informational duplicate of node.type; ignored." }, "emailId": { "type": "string", "minLength": 1, "description": "Email design id — required for sendEmail." }, "emailVersionId": { "type": "string", "minLength": 1, "description": "Email version id to send — required. A pin to the latest version follows new versions (prompt edit, restore) into an unpublished draft; older pins stay." }, "domainId": { "type": "string", "minLength": 1, "description": "Owned sending-domain id — optional at authoring; required, and verified (sendable: true), at publish and on every live run. A marketing domain enforces the unsubscribe link; a sendingPurpose \"transactional\" domain skips it and delivers even to unsubscribed contacts, so choose one only for genuinely transactional flows (receipts, password resets)." }, "subject": { "type": "string", "minLength": 1, "description": "Inbox subject — required. Supports {{var | fallback}} interpolation." }, "previewText": { "type": "string", "description": "Inbox preheader — optional; the email design's is the source of truth and wins when present." }, "fromName": { "type": "string", "minLength": 1, "description": "Sender display name; resolved from the domain default when unset." }, "replyTo": { "type": "string", "format": "email", "description": "Reply-to address; resolved from the domain default when unset." }, "emailTitle": { "type": "string", "description": "Informational email title mirror; tolerated for round-trips." }, "fromAddress": { "type": "string", "description": "Sender address on domainId's own domain; resolved from the domain default when unset." } }, "required": [ "emailId", "emailVersionId", "subject" ], "additionalProperties": false } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "wait" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "filter" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "payload" ] }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with" ] }, "value": { "type": "string", "description": "String value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "description": "Finite numeric value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "ISO date string or Unix timestamp in milliseconds to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "in", "not_in", "contains_any", "not_contains_any" ] }, "value": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Non-empty array of string values to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "in", "not_in" ] }, "value": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Non-empty array of finite numbers to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "description": "Inclusive [minimum, maximum] numeric bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] }, { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] } ], "description": "Inclusive [start, end] ISO-date or Unix-millisecond timestamp bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "bool" ] }, "operator": { "type": "string", "enum": [ "is_true", "is_false" ], "description": "Unary boolean check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false } ] }, "minItems": 1 } }, "required": [ "logicalOperator", "conditions" ], "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "engagement" ] }, "sourceNodeId": { "type": "string", "minLength": 1, "description": "Id of the upstream sendEmail node this filter watches for opens/clicks." }, "window": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ], "additionalProperties": false }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "condition": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "engaged", "not_engaged", "clicked_link" ] }, "events": { "type": "string", "enum": [ "opened", "clicked", "opened_or_clicked" ] }, "url": { "type": "string" }, "position": { "type": "string", "enum": [ "any", "first", "last" ] } }, "required": [ "kind" ] } }, "required": [ "id", "condition" ] }, "minItems": 1 } }, "required": [ "mode", "sourceNodeId", "window", "branches" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "split" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "percentage" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "leftPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "seed": { "type": "string" } }, "required": [ "mode", "leftLabel", "rightLabel", "leftPercentage" ], "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "condition" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with" ] }, "value": { "type": "string", "description": "String value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "description": "Finite numeric value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "ISO date string or Unix timestamp in milliseconds to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "in", "not_in", "contains_any", "not_contains_any" ] }, "value": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Non-empty array of string values to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "in", "not_in" ] }, "value": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Non-empty array of finite numbers to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "description": "Inclusive [minimum, maximum] numeric bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] }, { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] } ], "description": "Inclusive [start, end] ISO-date or Unix-millisecond timestamp bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "bool" ] }, "operator": { "type": "string", "enum": [ "is_true", "is_false" ], "description": "Unary boolean check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false } ] }, "minItems": 1 } }, "required": [ "mode", "leftLabel", "rightLabel", "logicalOperator", "conditions" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false } ] }, "maxItems": 500 }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "branch": { "type": "string", "minLength": 1 } }, "required": [ "from", "to" ], "additionalProperties": false }, "maxItems": 1000, "default": [] }, "dryRun": { "type": "boolean", "description": "Validate only — runs the full publish-gate check and returns blockers/warnings without creating anything." } }, "required": [ "name", "nodes" ], "additionalProperties": false }, "AutomationsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "published": { "type": "boolean" }, "isLive": { "type": "boolean" }, "liveVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "liveAutomationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } }, "paused": { "type": "boolean" }, "pausedAt": { "type": "number" }, "nodes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "trigger" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "event" ] }, "triggerEventId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "manualAudience" ] }, "audienceId": { "type": "string" } }, "required": [ "mode", "audienceId" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "sendEmail" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "emailId": { "type": "string" }, "emailVersionId": { "type": "string" }, "emailTitle": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string" }, "fromName": { "type": "string" }, "fromAddress": { "type": "string" }, "domainId": { "type": "string" }, "replyTo": { "type": "string" }, "to": {}, "html": { "type": "string" }, "variables": { "type": "object", "additionalProperties": {} } } } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "wait" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "filter" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "payload" ] }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ] }, "type": { "type": "string", "enum": [ "string", "number", "date", "bool" ] } }, "required": [ "field", "operator" ] } } }, "required": [ "logicalOperator", "conditions" ] }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "engagement" ] }, "sourceNodeId": { "type": "string" }, "window": { "type": "object", "properties": { "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "condition": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "engaged", "not_engaged", "clicked_link" ] }, "events": { "type": "string", "enum": [ "opened", "clicked", "opened_or_clicked" ] }, "url": { "type": "string" }, "position": { "type": "string", "enum": [ "any", "first", "last" ] } }, "required": [ "kind" ] } }, "required": [ "id", "condition" ] } } }, "required": [ "mode", "sourceNodeId", "window", "branches" ] } ] } }, "required": [ "id", "label", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "split" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "percentage" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "leftPercentage": { "type": "number" }, "seed": { "type": "string" } }, "required": [ "mode", "leftLabel", "rightLabel", "leftPercentage" ] }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "condition" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ] }, "type": { "type": "string", "enum": [ "string", "number", "date", "bool" ] } }, "required": [ "field", "operator" ] } } }, "required": [ "mode", "leftLabel", "rightLabel", "logicalOperator", "conditions" ] } ] } }, "required": [ "id", "label", "type", "config" ] } ] } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "branch": { "type": "string" } }, "required": [ "from", "to" ] } }, "emailIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "createdBy": { "type": "string", "description": "Creator as Brew shows it: a name or \"Former member\", \"API\" or \"MCP\", or both joined (\"Name · MCP\"); absent when the creator cannot be named." }, "createdByUserId": { "type": "string", "description": "Creator user id; absent for an organization API key." }, "publishedBy": { "type": "string", "description": "Who published the live version; absent while not live." }, "publishedByUserId": { "type": "string", "description": "Publisher user id of the live version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "enum": [ "latest" ] } ] }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "version", "automationVersionId" ], "additionalProperties": false } } }, "required": [ "automationId", "automationVersionId", "name", "version", "published", "emailIds" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "AutomationsUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "nodes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "trigger" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "event" ] }, "triggerEventId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "eventName": { "type": "string" }, "mode": { "type": "string", "enum": [ "manualAudience" ] }, "audienceId": { "type": "string" } }, "required": [ "mode", "audienceId" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "sendEmail" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string", "description": "Informational duplicate of node.type; ignored." }, "emailId": { "type": "string", "minLength": 1, "description": "Email design id — required for sendEmail." }, "emailVersionId": { "type": "string", "minLength": 1, "description": "Email version id to send — required. A pin to the latest version follows new versions (prompt edit, restore) into an unpublished draft; older pins stay." }, "domainId": { "type": "string", "minLength": 1, "description": "Owned sending-domain id — optional at authoring; required, and verified (sendable: true), at publish and on every live run. A marketing domain enforces the unsubscribe link; a sendingPurpose \"transactional\" domain skips it and delivers even to unsubscribed contacts, so choose one only for genuinely transactional flows (receipts, password resets)." }, "subject": { "type": "string", "minLength": 1, "description": "Inbox subject — required. Supports {{var | fallback}} interpolation." }, "previewText": { "type": "string", "description": "Inbox preheader — optional; the email design's is the source of truth and wins when present." }, "fromName": { "type": "string", "minLength": 1, "description": "Sender display name; resolved from the domain default when unset." }, "replyTo": { "type": "string", "format": "email", "description": "Reply-to address; resolved from the domain default when unset." }, "emailTitle": { "type": "string", "description": "Informational email title mirror; tolerated for round-trips." }, "fromAddress": { "type": "string", "description": "Sender address on domainId's own domain; resolved from the domain default when unset." } }, "required": [ "emailId", "emailVersionId", "subject" ], "additionalProperties": false } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "wait" ] }, "config": { "type": "object", "properties": { "actionType": { "type": "string" }, "duration": { "type": "number" }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "filter" ] }, "config": { "anyOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "payload" ] }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with" ] }, "value": { "type": "string", "description": "String value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "description": "Finite numeric value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "ISO date string or Unix timestamp in milliseconds to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "in", "not_in", "contains_any", "not_contains_any" ] }, "value": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Non-empty array of string values to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "in", "not_in" ] }, "value": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Non-empty array of finite numbers to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "description": "Inclusive [minimum, maximum] numeric bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] }, { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] } ], "description": "Inclusive [start, end] ISO-date or Unix-millisecond timestamp bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "bool" ] }, "operator": { "type": "string", "enum": [ "is_true", "is_false" ], "description": "Unary boolean check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false } ] }, "minItems": 1 } }, "required": [ "logicalOperator", "conditions" ], "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "engagement" ] }, "sourceNodeId": { "type": "string", "minLength": 1, "description": "Id of the upstream sendEmail node this filter watches for opens/clicks." }, "window": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "enum": [ "ms", "seconds", "minutes", "hours", "days", "weeks" ] } }, "required": [ "duration", "unit" ], "additionalProperties": false }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "condition": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "engaged", "not_engaged", "clicked_link" ] }, "events": { "type": "string", "enum": [ "opened", "clicked", "opened_or_clicked" ] }, "url": { "type": "string" }, "position": { "type": "string", "enum": [ "any", "first", "last" ] } }, "required": [ "kind" ] } }, "required": [ "id", "condition" ] }, "minItems": 1 } }, "required": [ "mode", "sourceNodeId", "window", "branches" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "split" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "percentage" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "leftPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "seed": { "type": "string" } }, "required": [ "mode", "leftLabel", "rightLabel", "leftPercentage" ], "additionalProperties": false }, { "type": "object", "properties": { "actionType": { "type": "string" }, "mode": { "type": "string", "enum": [ "condition" ] }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "logicalOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with" ] }, "value": { "type": "string", "description": "String value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "description": "Finite numeric value to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "ISO date string or Unix timestamp in milliseconds to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "in", "not_in", "contains_any", "not_contains_any" ] }, "value": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Non-empty array of string values to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "in", "not_in" ] }, "value": { "type": "array", "items": { "type": "number" }, "minItems": 1, "description": "Non-empty array of finite numbers to compare against." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "description": "Inclusive [minimum, maximum] numeric bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "between" ] }, "value": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] }, { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ] } ], "description": "Inclusive [start, end] ISO-date or Unix-millisecond timestamp bounds." } }, "required": [ "field", "type", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "string" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "number" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "date" ] }, "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Unary empty check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Trigger payload path (trackingNumber, order.total, items[0].sku) or contact. to read the recipient contact (contact.plan)." }, "type": { "type": "string", "enum": [ "bool" ] }, "operator": { "type": "string", "enum": [ "is_true", "is_false" ], "description": "Unary boolean check; do not provide a value." } }, "required": [ "field", "type", "operator" ], "additionalProperties": false } ] }, "minItems": 1 } }, "required": [ "mode", "leftLabel", "rightLabel", "logicalOperator", "conditions" ], "additionalProperties": false } ] } }, "required": [ "id", "label", "type", "config" ], "additionalProperties": false } ] }, "maxItems": 500 }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "branch": { "type": "string", "minLength": 1 } }, "required": [ "from", "to" ], "additionalProperties": false }, "maxItems": 1000 }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "expectedBaseVersionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Optimistic concurrency guard: the exact version read before deriving this update. Supply together with expectedBaseDefinitionSha256." }, "expectedBaseDefinitionSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Optimistic concurrency guard: SHA-256 of the exact definition read before deriving this update. Supply together with expectedBaseVersionId." }, "dryRun": { "type": "boolean", "description": "Validate only — runs the full publish-gate check and returns blockers/warnings without writing." }, "published": { "type": "boolean", "description": "Lifecycle action: `true` validates + publishes the STORED latest version (a saved edit goes live only after this); `false` unpublishes. Cannot be combined with field/graph updates — update first, then publish." }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Exact version to publish; requires `published: true`." }, "stopInFlight": { "type": "boolean", "description": "With `published: false` only — ALSO permanently stop contacts already mid-flow (default: they drain to completion). On an automation that is already a draft it only stops those contacts, and is a 422 AUTOMATION_NOT_PUBLISHED when none are in flight." }, "paused": { "type": "boolean", "description": "Freeze (`true`) / resume (`false`) a LIVE automation without unpublishing; held contacts resume from the same point." } }, "additionalProperties": false }, "AutomationsDeleteResponse": { "type": "object", "properties": { "automationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "deleted": { "type": "boolean" } }, "required": [ "automationId", "deleted" ], "additionalProperties": false }, "AutomationRunStartedResponse": { "type": "object", "properties": { "triggerInstanceId": { "type": "string", "minLength": 4, "maxLength": 64 }, "automationRunIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "testMode": { "type": "string", "enum": [ "smoke", "scenario" ] }, "status": { "type": "string", "enum": [ "triggered", "idempotent_replay", "test_started", "replay_started" ] }, "counts": { "type": "object", "properties": { "automations": { "type": "integer", "minimum": 0 } }, "required": [ "automations" ], "additionalProperties": false }, "receivedAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" }, "expectedType": { "type": "string" }, "actualType": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": {} } } }, "required": [ "automationRunIds", "status", "receivedAt" ], "additionalProperties": false }, "AutomationTestRequest": { "type": "object", "properties": { "payload": { "type": "object", "additionalProperties": {} }, "testRecipient": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$" }, "scenario": { "type": "object", "properties": { "engagement": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "opened" ] }, "afterMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "description": "Milliseconds after the node starts waiting at which the simulated event happens; must fall inside that node's window." } }, "required": [ "type", "afterMs" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "clicked" ] }, "afterMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "description": "Milliseconds after the node starts waiting at which the simulated event happens; must fall inside that node's window." }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The clicked http(s) link." } }, "required": [ "type", "afterMs", "url" ], "additionalProperties": false } ] }, "maxItems": 100 } }, "required": [ "nodeId", "events" ], "additionalProperties": false }, "maxItems": 1000, "default": [], "description": "Simulated opens/clicks per engagement-filter node; a node not listed here sees no engagement." }, "splits": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string", "enum": [ "left", "right" ] } }, "required": [ "nodeId", "branch" ], "additionalProperties": false }, "maxItems": 1000, "default": [], "description": "Forced branch per percentage-split node; a node not listed here picks deterministically." } }, "additionalProperties": false, "description": "Simulated engagement and forced split branches for this test run; omit for a plain dry run in which engagement filters take their else branch." } }, "additionalProperties": false }, "AutomationRunDryRunResponse": { "type": "object", "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "automationId": { "type": "string" }, "audienceId": { "type": "string" }, "audienceName": { "type": "string" }, "recipientCount": { "type": "number" }, "sendNodeCount": { "type": "number" }, "scheduledAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } } }, "required": [ "dryRun", "automationId", "audienceId", "recipientCount", "sendNodeCount" ] }, "AudienceAutomationRunStartedResponse": { "type": "object", "properties": { "audienceRunId": { "type": "string" }, "automationId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "scheduled" ] }, "totalRecipients": { "type": "number" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } }, "workflowRunId": { "type": "string" }, "approvalState": { "type": "string", "enum": [ "pending" ], "description": "Present when org-level send approval holds the run for admin review: no workflow starts until an admin approves; rejection cancels the run with zero deliveries." }, "receivedAt": { "type": "string", "format": "date-time" } }, "required": [ "audienceRunId", "automationId", "status", "totalRecipients", "receivedAt" ] }, "AutomationRunRequest": { "type": "object", "properties": { "dryRun": { "type": "boolean", "description": "Preview who will receive the email, and the flow, without launching a run (no sends, no side effects). recipientCount already excludes unsubscribed, suppressed and undeliverable contacts." }, "scheduledAt": { "type": "string", "format": "date-time" }, "gradualSend": { "type": "object", "properties": { "startingPercentage": { "type": "number", "minimum": 0.1, "maximum": 100 }, "incrementPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "interval": { "oneOf": [ { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 24 }, "unit": { "type": "string", "enum": [ "hour" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 30 }, "unit": { "type": "string", "enum": [ "day" ] } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA timezone used to preserve local wall-clock time for day intervals." } }, "required": [ "startingPercentage", "incrementPercentage", "interval", "timeZone" ], "additionalProperties": false } }, "additionalProperties": false }, "AudienceRunsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "audienceRunId": { "type": "string" }, "automationId": { "type": "string" }, "automationName": { "type": "string" }, "audienceId": { "type": "string" }, "audienceName": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "running", "paused", "completed", "failed", "canceled" ] }, "approvalState": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "pauseReason": { "type": "string", "enum": [ "manual", "plan_limit" ], "description": "Why a paused run is held. `plan_limit` means the plan has too few sends left this period; the run resumes on its own once the allowance has room (`resumeAudienceRun` refuses it), or you can cancel it. `manual` means an operator paused it; resume it to continue." }, "scheduledAt": { "type": "string", "format": "date-time" }, "totalRecipients": { "type": "number" }, "sentCount": { "type": "number" }, "failedCount": { "type": "number" }, "skippedCount": { "type": "number" }, "nodeStats": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeType": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "entered": { "type": "number" }, "sent": { "type": "number" }, "failed": { "type": "number" }, "skipped": { "type": "number" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "description": "A send step's own send (`arn_…`). Its delivery and, on a gradual run, its batch progress are at GET /v1/sends/{sendId}." } }, "required": [ "nodeId", "nodeType" ] } }, "gradualSend": { "type": "object", "properties": { "startingPercentage": { "type": "number", "minimum": 0.1, "maximum": 100 }, "incrementPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "interval": { "oneOf": [ { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 24 }, "unit": { "type": "string", "enum": [ "hour" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 30 }, "unit": { "type": "string", "enum": [ "day" ] } }, "required": [ "value", "unit" ], "additionalProperties": false } ] }, "timeZone": { "type": "string", "minLength": 1, "description": "IANA timezone used to preserve local wall-clock time for day intervals." }, "rampEndsAt": { "type": "string", "format": "date-time", "description": "Rolling stuck-send deadline, re-stamped at every batch. Not when the ramp ends." }, "currentTranche": { "type": "integer", "exclusiveMinimum": 0 }, "sentSoFar": { "type": "integer", "minimum": 0 }, "pausedAt": { "type": "string", "format": "date-time" }, "pauseReason": { "type": "string", "enum": [ "manual" ] }, "resumedAt": { "type": "string", "format": "date-time" } }, "required": [ "startingPercentage", "incrementPercentage", "interval", "timeZone" ], "additionalProperties": false, "description": "The run's authored ramp. Each send step ramps its own segment, so batch progress is per step: follow `nodeStats[].sendId`." }, "error": { "type": "string" }, "stalledAt": { "type": "string", "format": "date-time" }, "resumeGeneration": { "type": "number" }, "resumedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "audienceRunId", "automationId", "audienceId", "status", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "AudienceRunActionResponse": { "type": "object", "properties": { "audienceRunId": { "type": "string" }, "status": { "type": "string", "enum": [ "paused", "running", "canceled" ] }, "resumedFrom": { "type": "string", "enum": [ "paused", "failed" ] } }, "required": [ "audienceRunId", "status" ], "additionalProperties": false }, "AutomationRunsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "definitionHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "triggerInstanceId": { "type": "string", "minLength": 4, "maxLength": 64 }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "recipientEmail": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "testCoverage": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "smoke", "scenario" ] }, "complete": { "type": "boolean" }, "visitedNodes": { "type": "array", "items": { "type": "string" } }, "unvisitedNodes": { "type": "array", "items": { "type": "string" } }, "traversedConnections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "to": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string" } }, "required": [ "from", "to" ] } }, "untraversedConnections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "to": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string" } }, "required": [ "from", "to" ] } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string" }, "source": { "type": "string", "enum": [ "simulated", "forced", "deterministic", "payload", "smoke", "upstream_not_delivered" ] } }, "required": [ "nodeId", "branch", "source" ] } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "complete", "visitedNodes", "unvisitedNodes", "traversedConnections", "untraversedConnections", "decisions", "limitations" ] }, "logs": { "type": "array", "items": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "nodeId": { "type": "string", "minLength": 1 }, "nodeName": { "type": "string", "minLength": 1 }, "nodeType": { "type": "string", "enum": [ "trigger", "wait", "filter", "split", "sendEmail" ] }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "skipped" ] }, "orderIndex": { "type": "integer", "minimum": 0 }, "branch": { "type": "string", "minLength": 1 }, "durationMs": { "type": "integer", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" } }, "required": [ "automationRunId", "nodeId", "nodeName", "nodeType", "status", "orderIndex", "startedAt" ], "additionalProperties": false } }, "logsTruncated": { "type": "boolean" } }, "required": [ "automationRunId", "automationId", "mode", "status" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "AutomationRun": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationVersionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "definitionHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "triggerInstanceId": { "type": "string", "minLength": 4, "maxLength": 64 }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "recipientEmail": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "testCoverage": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "smoke", "scenario" ] }, "complete": { "type": "boolean" }, "visitedNodes": { "type": "array", "items": { "type": "string" } }, "unvisitedNodes": { "type": "array", "items": { "type": "string" } }, "traversedConnections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "to": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string" } }, "required": [ "from", "to" ] } }, "untraversedConnections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "to": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string" } }, "required": [ "from", "to" ] } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The id of the automation node this control applies to." }, "branch": { "type": "string" }, "source": { "type": "string", "enum": [ "simulated", "forced", "deterministic", "payload", "smoke", "upstream_not_delivered" ] } }, "required": [ "nodeId", "branch", "source" ] } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "complete", "visitedNodes", "unvisitedNodes", "traversedConnections", "untraversedConnections", "decisions", "limitations" ] }, "logs": { "type": "array", "items": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "nodeId": { "type": "string", "minLength": 1 }, "nodeName": { "type": "string", "minLength": 1 }, "nodeType": { "type": "string", "enum": [ "trigger", "wait", "filter", "split", "sendEmail" ] }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "skipped" ] }, "orderIndex": { "type": "integer", "minimum": 0 }, "branch": { "type": "string", "minLength": 1 }, "durationMs": { "type": "integer", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" } }, "required": [ "automationRunId", "nodeId", "nodeName", "nodeType", "status", "orderIndex", "startedAt" ], "additionalProperties": false } }, "logsTruncated": { "type": "boolean" } }, "required": [ "automationRunId", "automationId", "mode", "status" ], "additionalProperties": false }, "AutomationRunCancelResponse": { "type": "object", "properties": { "automationRunId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "canceled" ] }, "previousStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] } }, "required": [ "automationRunId", "status", "previousStatus" ], "additionalProperties": false }, "AutomationRunCancelRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the run was stopped; stored on the run for the audit trail." } }, "additionalProperties": false }, "BrewEventTriggerSaved": { "type": "object", "properties": { "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "provider": { "type": "string", "enum": [ "brew_api", "custom", "brew_event", "clerk", "stytch", "supabase", "workos", "stripe", "shopify", "revenuecat", "framer" ] }, "providerEventKey": { "type": "string" }, "brewEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "contact.unsubscribed" ], "description": "The Brew event this trigger starts on." }, "scope": { "type": "string", "enum": [ "domain", "all" ], "description": "`domain`: unsubscribes from one marketing sending domain (its list). `all`: unsubscribes from every email the brand sends." }, "domainHost": { "type": "string", "minLength": 1, "description": "The sending domain whose list this trigger watches, e.g. `news.acme.com`. Present only when `scope` is `domain`." } }, "required": [ "event", "scope" ], "additionalProperties": false }, "payloadSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" } } }, "required": [ "type", "fields" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "skill": { "type": "string" }, "created": { "type": "boolean", "description": "True when this call created the trigger; false when it already existed." } }, "required": [ "triggerEventId", "title", "provider", "payloadSchema", "createdAt", "updatedAt", "created" ], "additionalProperties": false }, "BrewEventTriggersPostRequest": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "contact.unsubscribed" ], "description": "The Brew event. `contact.unsubscribed`: a contact unsubscribed with an email unsubscribe link or their mail app’s unsubscribe button." }, "scope": { "type": "string", "enum": [ "domain", "all" ], "description": "`domain`: unsubscribes from one marketing sending domain (pass `domainId`). `all`: unsubscribes from every email the brand sends." }, "domainId": { "type": "string", "minLength": 1, "description": "The marketing domain (from `GET /v1/domains`) whose unsubscribe list this trigger watches. Required when `scope` is `domain`; omit for `all`." } }, "required": [ "event", "scope" ], "additionalProperties": false }, "TriggersPostRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "payloadSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" } } }, "required": [ "type", "fields" ] } }, "required": [ "title", "payloadSchema" ], "additionalProperties": false }, "TriggersListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "provider": { "type": "string", "enum": [ "brew_api", "custom", "brew_event", "clerk", "stytch", "supabase", "workos", "stripe", "shopify", "revenuecat", "framer" ] }, "providerEventKey": { "type": "string" }, "brewEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "contact.unsubscribed" ], "description": "The Brew event this trigger starts on." }, "scope": { "type": "string", "enum": [ "domain", "all" ], "description": "`domain`: unsubscribes from one marketing sending domain (its list). `all`: unsubscribes from every email the brand sends." }, "domainHost": { "type": "string", "minLength": 1, "description": "The sending domain whose list this trigger watches, e.g. `news.acme.com`. Present only when `scope` is `domain`." } }, "required": [ "event", "scope" ], "additionalProperties": false }, "payloadSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" } } }, "required": [ "type", "fields" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "skill": { "type": "string" } }, "required": [ "triggerEventId", "title", "provider", "payloadSchema", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "TriggersPatchRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "payloadSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" } } }, "required": [ "type", "fields" ] } }, "additionalProperties": false }, "TriggersDeleteResponse": { "type": "object", "properties": { "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "deleted": { "type": "boolean" } }, "required": [ "triggerEventId", "deleted" ], "additionalProperties": false }, "TriggerReadiness": { "type": "object", "properties": { "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "ready": { "type": "boolean", "description": "True when a fire right now would start at least one run." }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NO_PUBLISHED_AUTOMATION" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "title": { "type": "string" }, "description": { "type": "string" }, "provider": { "type": "string" }, "providerEventKey": { "type": "string" }, "payloadSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerPayloadField" } } }, "required": [ "type", "fields" ] }, "endpoint": { "type": "string", "description": "The fire URL to POST events to." }, "publishedAutomations": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string" }, "name": { "type": "string" }, "primaryFromAddress": { "type": "string" } }, "required": [ "automationId" ], "additionalProperties": {} } }, "counts": { "type": "object", "properties": { "automations": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "required": [ "automations", "skipped" ], "additionalProperties": false }, "delivery": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "received", "never_received", "none_recent", "waiting_for_test_event" ] }, "lastReceivedAt": { "type": "string", "format": "date-time" }, "sourceEvent": { "type": "string", "description": "The provider dashboard name (Shopify Admin: \"Customer update\")." }, "message": { "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": false, "description": "Integration triggers only: whether Brew has received this event from its source (`none_recent`: not in the 90-day receipt window). Never affects `ready`." } }, "required": [ "triggerEventId", "ready", "blockers", "publishedAutomations", "counts" ], "additionalProperties": false }, "TriggerFireAccepted": { "type": "object", "properties": { "triggerInstanceId": { "type": "string", "description": "The persisted inbound row — `GET /v1/automations/trigger-instances/{triggerInstanceId}` for its match state." }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "type": "string", "enum": [ "triggered", "replayed" ], "description": "`triggered` = this call accepted and matched the event; `automationRunIds` lists the runs it started and `notStarted` any it could not. `replayed` = the same `Idempotency-Key` already fired; nothing ran twice." }, "automationRunIds": { "type": "array", "items": { "type": "string" }, "description": "The runs this fire started — `GET /v1/automations/runs/{automationRunId}`." }, "notStarted": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string" }, "reason": { "type": "string", "description": "Why its run did not start. A refusal (a merge tag or condition field the trigger does not declare, a step the run gate finds incomplete) repeats on every fire until the automation or trigger is fixed; an unexpected error is retried automatically." } }, "required": [ "automationId", "reason" ], "additionalProperties": false }, "default": [], "description": "Matched automations whose run failed to start, each with the reason; one skipped on purpose (paused past its window, a suppressed contact) is not listed. A fire can answer `triggered` with no runs; this says why." }, "publishedAutomations": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string" }, "name": { "type": "string" }, "primaryFromAddress": { "type": "string" } }, "required": [ "automationId" ], "additionalProperties": {} } }, "counts": { "type": "object", "properties": { "automations": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "required": [ "automations", "skipped" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" }, "expectedType": { "type": "string" }, "actualType": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": {} } }, "receivedAt": { "type": "string", "format": "date-time" } }, "required": [ "triggerInstanceId", "triggerEventId", "status", "automationRunIds", "publishedAutomations", "counts", "warnings", "receivedAt" ], "additionalProperties": false }, "TriggerFireRequest": { "type": "object", "properties": { "payload": { "type": "object", "additionalProperties": {}, "description": "Event payload — fields and types must match the trigger's `payloadSchema`. Unknown fields are accepted but reported as `unexpected_key` warnings." } }, "required": [ "payload" ], "additionalProperties": false }, "PayloadContractGetResponse": { "oneOf": [ { "type": "object", "properties": { "subjectKind": { "type": "string", "enum": [ "trigger" ] }, "subjectId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "stored", "derived_from_schema", "derived_from_template" ] }, "typeName": { "type": "string", "minLength": 1 }, "contractHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "version": { "type": "integer", "minimum": 1 }, "enforcement": { "type": "string", "enum": [ "off", "prune", "strict" ] }, "driftStatus": { "type": "string", "enum": [ "fresh", "stale" ] }, "format": { "type": "string", "enum": [ "json" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadContractFieldNode" } } }, "required": [ "subjectKind", "subjectId", "source", "typeName", "format", "fields" ], "additionalProperties": false }, { "type": "object", "properties": { "subjectKind": { "type": "string", "enum": [ "trigger" ] }, "subjectId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "stored", "derived_from_schema", "derived_from_template" ] }, "typeName": { "type": "string", "minLength": 1 }, "contractHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "version": { "type": "integer", "minimum": 1 }, "enforcement": { "type": "string", "enum": [ "off", "prune", "strict" ] }, "driftStatus": { "type": "string", "enum": [ "fresh", "stale" ] }, "format": { "type": "string", "enum": [ "ts", "zod", "jsonschema", "skill" ] }, "content": { "type": "string" } }, "required": [ "subjectKind", "subjectId", "source", "typeName", "format", "content" ], "additionalProperties": false } ] }, "PayloadContractFieldNode": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "type": "string", "enum": [ "string", "int", "float", "boolean", "date", "enum", "object", "array", "unknown" ] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "exampleValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "fallbackValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "pii": { "type": "string", "enum": [ "none", "low", "high" ] }, "secret": { "type": "boolean", "description": "True for a value used only to render this email: never stored on contacts, in logs or analytics; cannot be used in filters, splits or recipient fields. Scalars only, never `email`. False explicitly permits ordinary PII outside rendering; pii still controls log masking. When omitted, legacy high-PII scalar protection applies except for email and top-level firstName/lastName." }, "syncToContact": { "type": "boolean", "description": "false keeps this value off the contact record: it reaches the email and nothing else. Omitted means true. The top-level email always identifies the contact." }, "enumValues": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 }, "itemType": { "anyOf": [ { "type": "string", "enum": [ "string", "int", "float", "boolean", "date", "enum" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "usedIn": { "type": "array", "items": { "type": "string", "enum": [ "body", "subject", "previewText" ] }, "maxItems": 3 }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadContractFieldNode" }, "maxItems": 100 } }, "required": [ "key", "type", "required" ], "additionalProperties": false }, "PayloadContractPutResponse": { "type": "object", "properties": { "subjectKind": { "type": "string", "enum": [ "trigger" ] }, "subjectId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "stored", "derived_from_schema", "derived_from_template" ] }, "typeName": { "type": "string", "minLength": 1 }, "contractHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "version": { "type": "integer", "minimum": 1 }, "enforcement": { "type": "string", "enum": [ "off", "prune", "strict" ] }, "driftStatus": { "type": "string", "enum": [ "fresh", "stale" ] }, "format": { "type": "string", "enum": [ "json" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadContractFieldNode" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" } } }, "required": [ "subjectKind", "subjectId", "source", "typeName", "format", "fields", "warnings" ], "additionalProperties": false }, "PayloadContractPutRequest": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadContractFieldNode" }, "minItems": 1, "maxItems": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "enforcement": { "type": "string", "enum": [ "off", "prune", "strict" ], "description": "How live fires use the contract. `off`: advisory only. `prune`: a fire that breaks a declared field is refused and undeclared keys are dropped. `strict`: undeclared keys are refused too. Omit to keep the current setting." } }, "additionalProperties": false }, "PayloadContractValidateResponse": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "payload_not_object", "missing_required", "invalid_type", "unexpected_key", "required_satisfied_by_fallback", "invalid_email" ] }, "field": { "type": "string" }, "message": { "type": "string" }, "expectedType": { "type": "string" }, "actualType": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "payload_not_object", "missing_required", "invalid_type", "unexpected_key", "required_satisfied_by_fallback", "invalid_email" ] }, "field": { "type": "string" }, "message": { "type": "string" }, "expectedType": { "type": "string" }, "actualType": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "resolvedPayload": { "type": "object", "additionalProperties": {} }, "prunedKeys": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "stored", "derived_from_schema", "derived_from_template" ] }, "contractHash": { "type": "string", "minLength": 64, "maxLength": 64 } }, "required": [ "valid", "errors", "warnings", "resolvedPayload", "prunedKeys", "source" ], "additionalProperties": false }, "PayloadContractValidateRequest": { "type": "object", "properties": { "payload": { "type": "object", "additionalProperties": {} }, "enforcement": { "type": "string", "enum": [ "prune", "strict" ], "description": "Check as this mode instead of the stored one: `prune` drops undeclared keys, `strict` reports them as errors. Omit for the stored mode (`prune` when enforcement is off)." } }, "required": [ "payload" ], "additionalProperties": false }, "PayloadContractInferResponse": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadContractFieldNode" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "fields", "issues" ], "additionalProperties": false }, "PayloadContractInferRequest": { "type": "object", "properties": { "example": { "type": "object", "additionalProperties": {} }, "subjectKind": { "type": "string", "enum": [ "trigger" ] } }, "required": [ "example" ], "additionalProperties": false }, "TriggerInstancesListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "triggerInstanceId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "api", "integration", "brew_event" ] }, "provider": { "type": "string" }, "triggerEventId": { "type": "string", "minLength": 1, "maxLength": 256 }, "state": { "type": "string", "enum": [ "received", "verified", "matched", "partially_fired", "fired", "rejected", "dead_letter" ] }, "matchedAutomationIds": { "type": "array", "items": { "type": "string" } }, "automationRunIds": { "type": "array", "items": { "type": "string" } }, "rejectionReason": { "type": "string" }, "attempts": { "type": "integer", "minimum": 0 }, "receivedAt": { "type": "string", "format": "date-time" }, "processedAt": { "type": "string", "format": "date-time" } }, "required": [ "triggerInstanceId", "source", "state", "matchedAutomationIds", "automationRunIds", "attempts", "receivedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "ContactsPostBatchResponse": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "inserted": { "type": "integer", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "inserted", "updated", "failed" ], "additionalProperties": false }, "fieldsCreated": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "row": { "type": "integer", "exclusiveMinimum": 0, "description": "The 1-based row that failed: `contacts[row - 1]`, or the CSV data row (header and blank lines not counted)." }, "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "email", "code", "message" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "row": { "type": "integer", "exclusiveMinimum": 0, "description": "The 1-based row it is about (CSV: data row; header and blank lines not counted)." }, "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "original": { "type": "string", "minLength": 1 }, "normalized": { "type": "string", "minLength": 1 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "valid": { "type": "integer", "minimum": 0 }, "risky": { "type": "integer", "minimum": 0 }, "invalid": { "type": "integer", "minimum": 0 }, "unscored": { "type": "integer", "minimum": 0 }, "persistence": { "type": "object", "properties": { "matched": { "type": "integer", "minimum": 0 }, "modified": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "matched", "modified", "failed" ], "additionalProperties": false } }, "required": [ "valid", "risky", "invalid", "unscored" ], "additionalProperties": false }, "validationJobId": { "type": "string" } }, "required": [ "summary", "fieldsCreated", "errors", "warnings" ], "additionalProperties": false }, "ContactsPostSingleResponse": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import", "app", "integration" ], "description": "Who captured it: `api` (an API caller asserted it), `form` (a signup form), `import` (a bulk import), `app` (the in-app CSV wizard checkbox), `integration` (an integration sync such as Stripe created the contact; provenance only, not an opt-in)." }, "capturedAt": { "type": "string", "format": "date-time", "description": "When it was captured." }, "policyVersion": { "type": "string", "description": "The policy or terms version in force when it was captured." }, "evidence": { "type": "string", "description": "Free-text evidence: a form URL, a ticket, a checkbox label." } }, "required": [ "source", "capturedAt" ], "additionalProperties": false }, "validationStatus": { "type": "string", "enum": [ "valid", "risky", "invalid" ], "description": "The latest verdict. `valid` only ever comes from a deliverability check (`validate: true` on ingest, or POST /v1/contacts/validate), which also sets `lastValidatedAt`. Without a check the free format check on ingest stores `risky` (disposable or role address) or `invalid`, and leaves the field unset otherwise: not validated." }, "suppressed": { "type": "boolean", "default": false }, "suppressedReason": { "type": [ "string", "null" ] }, "unsubscribedDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "validationDetails": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "brew" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "provider" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "importId": { "type": [ "string", "null" ] }, "csvFileName": { "type": [ "string", "null" ] }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "email", "createdAt", "updatedAt" ], "additionalProperties": false }, "created": { "type": "boolean" }, "fieldsCreated": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "row": { "type": "integer", "exclusiveMinimum": 0, "description": "The 1-based row it is about (CSV: data row; header and blank lines not counted)." }, "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "original": { "type": "string", "minLength": 1 }, "normalized": { "type": "string", "minLength": 1 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "valid": { "type": "integer", "minimum": 0 }, "risky": { "type": "integer", "minimum": 0 }, "invalid": { "type": "integer", "minimum": 0 }, "unscored": { "type": "integer", "minimum": 0 }, "persistence": { "type": "object", "properties": { "matched": { "type": "integer", "minimum": 0 }, "modified": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "matched", "modified", "failed" ], "additionalProperties": false } }, "required": [ "valid", "risky", "invalid", "unscored" ], "additionalProperties": false } }, "required": [ "contact", "created", "fieldsCreated", "warnings" ], "additionalProperties": false }, "ContactsPostRequest": { "anyOf": [ { "$ref": "#/components/schemas/ContactsPostSingleRequest" }, { "$ref": "#/components/schemas/ContactsPostBatchRequest" } ] }, "ContactsPostSingleRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean" }, "customFields": { "type": "object", "additionalProperties": {} }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Marketing consent provenance to record on this contact. Optional at creation; an inline marketing send to this address later needs the contact to be subscribed and warns when no record exists." }, "validate": { "type": "boolean", "description": "Optional deliverability check on ingestion. When true, each address is validated with the provider (2 credits per address, charged on success) and the verdict is saved to the contact’s `validationStatus`. Submissions above the inline cap (100 addresses) upsert first and validate as a background job, returning a `validationJobId`." } }, "required": [ "email" ], "additionalProperties": false }, "ContactsPostBatchRequest": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean" }, "customFields": { "type": "object", "additionalProperties": {} }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Marketing consent provenance to record on this contact. Optional at creation; an inline marketing send to this address later needs the contact to be subscribed and warns when no record exists." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "validate": { "type": "boolean", "description": "Optional deliverability check on ingestion. When true, each address is validated with the provider (2 credits per address, charged on success) and the verdict is saved to the contact’s `validationStatus`. Submissions above the inline cap (100 addresses) upsert first and validate as a background job, returning a `validationJobId`." }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Default consent record for every row that does not carry its own `consent`." } }, "required": [ "contacts" ], "additionalProperties": false }, "ContactsPatchResponse": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import", "app", "integration" ], "description": "Who captured it: `api` (an API caller asserted it), `form` (a signup form), `import` (a bulk import), `app` (the in-app CSV wizard checkbox), `integration` (an integration sync such as Stripe created the contact; provenance only, not an opt-in)." }, "capturedAt": { "type": "string", "format": "date-time", "description": "When it was captured." }, "policyVersion": { "type": "string", "description": "The policy or terms version in force when it was captured." }, "evidence": { "type": "string", "description": "Free-text evidence: a form URL, a ticket, a checkbox label." } }, "required": [ "source", "capturedAt" ], "additionalProperties": false }, "validationStatus": { "type": "string", "enum": [ "valid", "risky", "invalid" ], "description": "The latest verdict. `valid` only ever comes from a deliverability check (`validate: true` on ingest, or POST /v1/contacts/validate), which also sets `lastValidatedAt`. Without a check the free format check on ingest stores `risky` (disposable or role address) or `invalid`, and leaves the field unset otherwise: not validated." }, "suppressed": { "type": "boolean", "default": false }, "suppressedReason": { "type": [ "string", "null" ] }, "unsubscribedDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "validationDetails": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "brew" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "provider" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "importId": { "type": [ "string", "null" ] }, "csvFileName": { "type": [ "string", "null" ] }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "email", "createdAt", "updatedAt" ], "additionalProperties": false }, "updated": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The fields whose stored value changed (`consent` included). Empty when every value sent matched what was stored; nothing is written then and `updatedAt` stays the same." }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "row": { "type": "integer", "exclusiveMinimum": 0, "description": "The 1-based row it is about (CSV: data row; header and blank lines not counted)." }, "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "original": { "type": "string", "minLength": 1 }, "normalized": { "type": "string", "minLength": 1 } }, "required": [ "code", "message" ], "additionalProperties": false } } }, "required": [ "contact", "updated", "warnings" ], "additionalProperties": false }, "ContactsPatchRequest": { "type": "object", "properties": { "fields": { "type": "object", "additionalProperties": {} }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Record (or replace) the marketing consent provenance. Never re-subscribes an opted-out contact." } }, "additionalProperties": false }, "ContactDeleteResponse": { "type": "object", "properties": { "email": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "email", "deleted" ], "additionalProperties": false }, "ContactsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import", "app", "integration" ], "description": "Who captured it: `api` (an API caller asserted it), `form` (a signup form), `import` (a bulk import), `app` (the in-app CSV wizard checkbox), `integration` (an integration sync such as Stripe created the contact; provenance only, not an opt-in)." }, "capturedAt": { "type": "string", "format": "date-time", "description": "When it was captured." }, "policyVersion": { "type": "string", "description": "The policy or terms version in force when it was captured." }, "evidence": { "type": "string", "description": "Free-text evidence: a form URL, a ticket, a checkbox label." } }, "required": [ "source", "capturedAt" ], "additionalProperties": false }, "validationStatus": { "type": "string", "enum": [ "valid", "risky", "invalid" ], "description": "The latest verdict. `valid` only ever comes from a deliverability check (`validate: true` on ingest, or POST /v1/contacts/validate), which also sets `lastValidatedAt`. Without a check the free format check on ingest stores `risky` (disposable or role address) or `invalid`, and leaves the field unset otherwise: not validated." }, "suppressed": { "type": "boolean", "default": false }, "suppressedReason": { "type": [ "string", "null" ] }, "unsubscribedDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "validationDetails": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "brew" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "provider" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "importId": { "type": [ "string", "null" ] }, "csvFileName": { "type": [ "string", "null" ] }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "email", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "ContactWithOpenProfile": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import", "app", "integration" ], "description": "Who captured it: `api` (an API caller asserted it), `form` (a signup form), `import` (a bulk import), `app` (the in-app CSV wizard checkbox), `integration` (an integration sync such as Stripe created the contact; provenance only, not an opt-in)." }, "capturedAt": { "type": "string", "format": "date-time", "description": "When it was captured." }, "policyVersion": { "type": "string", "description": "The policy or terms version in force when it was captured." }, "evidence": { "type": "string", "description": "Free-text evidence: a form URL, a ticket, a checkbox label." } }, "required": [ "source", "capturedAt" ], "additionalProperties": false }, "validationStatus": { "type": "string", "enum": [ "valid", "risky", "invalid" ], "description": "The latest verdict. `valid` only ever comes from a deliverability check (`validate: true` on ingest, or POST /v1/contacts/validate), which also sets `lastValidatedAt`. Without a check the free format check on ingest stores `risky` (disposable or role address) or `invalid`, and leaves the field unset otherwise: not validated." }, "suppressed": { "type": "boolean", "default": false }, "suppressedReason": { "type": [ "string", "null" ] }, "unsubscribedDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "validationDetails": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "brew" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "provider" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "importId": { "type": [ "string", "null" ] }, "csvFileName": { "type": [ "string", "null" ] }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} }, "openProfile": { "type": [ "object", "null" ], "properties": { "totalOpens": { "type": "integer", "minimum": 0 }, "lastOpenedAt": { "type": "string", "format": "date-time" }, "bestOpenMinuteUtc": { "type": "integer", "minimum": 0, "maximum": 1439 }, "bestSendMinuteUtc": { "type": "integer", "minimum": 0, "maximum": 1439 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "histogram": { "type": "array", "items": { "type": "integer", "minimum": 0 } } }, "required": [ "totalOpens", "lastOpenedAt", "histogram" ], "additionalProperties": false, "description": "With `include` openProfile: the contact's smart-send open-time profile (48 UTC half-hour open counts and the best send time derived from them), or null when they have no opens folded yet. Not bot detection: machine opens cannot be told apart here." } }, "required": [ "email", "createdAt", "updatedAt" ], "additionalProperties": false }, "ContactsSearchSuccessResponse": { "anyOf": [ { "$ref": "#/components/schemas/ContactsListResponse" }, { "$ref": "#/components/schemas/ContactsWithOpenProfileListResponse" }, { "$ref": "#/components/schemas/ContactsCountResponse" } ] }, "ContactsWithOpenProfileListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import", "app", "integration" ], "description": "Who captured it: `api` (an API caller asserted it), `form` (a signup form), `import` (a bulk import), `app` (the in-app CSV wizard checkbox), `integration` (an integration sync such as Stripe created the contact; provenance only, not an opt-in)." }, "capturedAt": { "type": "string", "format": "date-time", "description": "When it was captured." }, "policyVersion": { "type": "string", "description": "The policy or terms version in force when it was captured." }, "evidence": { "type": "string", "description": "Free-text evidence: a form URL, a ticket, a checkbox label." } }, "required": [ "source", "capturedAt" ], "additionalProperties": false }, "validationStatus": { "type": "string", "enum": [ "valid", "risky", "invalid" ], "description": "The latest verdict. `valid` only ever comes from a deliverability check (`validate: true` on ingest, or POST /v1/contacts/validate), which also sets `lastValidatedAt`. Without a check the free format check on ingest stores `risky` (disposable or role address) or `invalid`, and leaves the field unset otherwise: not validated." }, "suppressed": { "type": "boolean", "default": false }, "suppressedReason": { "type": [ "string", "null" ] }, "unsubscribedDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "validationDetails": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "brew" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "provider" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "importId": { "type": [ "string", "null" ] }, "csvFileName": { "type": [ "string", "null" ] }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} }, "openProfile": { "type": [ "object", "null" ], "properties": { "totalOpens": { "type": "integer", "minimum": 0 }, "lastOpenedAt": { "type": "string", "format": "date-time" }, "bestOpenMinuteUtc": { "type": "integer", "minimum": 0, "maximum": 1439 }, "bestSendMinuteUtc": { "type": "integer", "minimum": 0, "maximum": 1439 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "histogram": { "type": "array", "items": { "type": "integer", "minimum": 0 } } }, "required": [ "totalOpens", "lastOpenedAt", "histogram" ], "additionalProperties": false, "description": "With `include` openProfile: the contact's smart-send open-time profile (48 UTC half-hour open counts and the best send time derived from them), or null when they have no opens folded yet. Not bot detection: machine opens cannot be told apart here." } }, "required": [ "email", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "ContactsCountResponse": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "bucket": { "type": [ "string", "null" ] }, "count": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "key", "count" ], "additionalProperties": false }, "description": "With `groupBy` or `bucket`: the largest 200 groups; `key` maps each grouped field to its value, `bucket` is the ISO period start." }, "otherCount": { "type": "integer", "minimum": 0, "description": "Contacts in the groups past the first 200." } }, "required": [ "count" ], "additionalProperties": false }, "ContactsSearchRequest": { "type": "object", "properties": { "search": { "type": "string", "minLength": 1, "description": "A whole email address matches only that contact. Other text matches the contacts whose email, first or last name contains any of its words, in `sort` order." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "The contact column or custom-field name to filter on (e.g. `email`, `firstName`, or a key from GET /v1/fields)." }, "operator": { "type": "string", "minLength": 1, "description": "Allowed operators depend on the field's type — string: equals, not_equals, contains, not_contains, contains_any, not_contains_any, starts_with, ends_with, is_empty, is_not_empty, in, not_in, exists, not_exists; number: equals, not_equals, gt, gte, lt, lte, between, is_empty, is_not_empty; date: on_date, before, after, between, is_empty, is_not_empty; bool: is_true, is_false (`equals` with true/false/1/0 is accepted as an alias). Any other operator, or an operator on a field type that does not support it, is rejected with 400 INVALID_REQUEST (`param: \"filter\"`) — nothing is silently ignored. E.g. use `equals`, not `eq`." }, "value": { "type": "string", "description": "The comparison value, as a string. `in`, `not_in`, `contains_any` and `not_contains_any` take a comma-separated list; `between` takes exactly two comma-separated bounds (e.g. \"10,30\"). Unary operators (`is_empty`, `is_not_empty`, `exists`, `not_exists`, `is_true`, `is_false`) ignore it — pass \"\"." } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "default": [] }, "audienceId": { "type": "string", "minLength": 1, "description": "Scope to a saved audience's members. The audience's stored filter set is evaluated as one unit with its own `logicalOperator` (an OR audience stays an OR), then ANDed with `filters`. Unknown / cross-brand id, or an audience a send would refuse (unusable filters, a cohort still building) → 400." }, "logic": { "type": "string", "enum": [ "and", "or", "none" ], "default": "and" }, "sort": { "type": "string", "minLength": 1, "default": "createdAt" }, "order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "count": { "type": "boolean", "default": false }, "groupBy": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 2, "description": "With `count: true`: also count per value of up to two fields (a contact field, a custom field, or `emailDomain`), largest group first." }, "bucket": { "type": "string", "enum": [ "day", "week", "month" ], "description": "With `count: true`: also count per UTC `createdAt` day, week (Monday start) or month." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": "string", "minLength": 1 }, "include": { "type": "array", "items": { "type": "string", "enum": [ "openProfile" ] }, "minItems": 1, "maxItems": 1, "description": "`openProfile` attaches each returned contact's smart-send open-time profile (needs the `emails` permission as well). A page then holds at most 10 contacts; not with `count: true`." } }, "additionalProperties": false }, "ContactsValidateResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "email": { "type": "string" }, "valid": { "type": "boolean" }, "status": { "type": "string", "enum": [ "valid", "risky", "invalid" ] }, "checkOutcome": { "type": "string", "enum": [ "completed" ] }, "reason": { "type": "string" }, "didYouMean": { "type": "string" }, "risk": { "type": "string" }, "isDisposable": { "type": "boolean" }, "isRole": { "type": "boolean" } }, "required": [ "email", "valid", "status", "checkOutcome" ], "additionalProperties": false }, { "type": "object", "properties": { "email": { "type": "string" }, "valid": { "type": "boolean", "enum": [ false ] }, "status": { "type": "string", "enum": [ "risky" ] }, "checkOutcome": { "type": "string", "enum": [ "unavailable" ] }, "reason": { "type": "string", "enum": [ "validation_unavailable" ] } }, "required": [ "email", "valid", "status", "checkOutcome", "reason" ], "additionalProperties": false } ] } }, "persistence": { "type": "object", "properties": { "matched": { "type": "integer", "minimum": 0 }, "modified": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "matched", "modified", "failed" ], "additionalProperties": false } }, "required": [ "data", "persistence" ], "additionalProperties": false }, "ContactsValidateRequest": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 } }, "required": [ "emails" ], "additionalProperties": false }, "ContactsImportResponse": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "inserted": { "type": "integer", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0, "description": "Rows not written and not failed: existing contacts left alone by `onConflict: \"skip\"` (one `CONTACT_EXISTS_SKIPPED` warning each), and CSV rows omitted for a missing/invalid email or merged into a later duplicate (up to 100 `CSV_ROW_SKIPPED` warnings name each `row`; a final warning counts further skipped rows)." }, "total": { "type": "integer", "minimum": 0, "description": "Rows submitted (JSON contacts, or CSV data rows). Always `inserted + updated + failed + skipped`." } }, "required": [ "inserted", "updated", "failed", "skipped", "total" ], "additionalProperties": false }, "fieldsCreated": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "row": { "type": "integer", "exclusiveMinimum": 0, "description": "The 1-based row that failed: `contacts[row - 1]`, or the CSV data row (header and blank lines not counted)." }, "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "email", "code", "message" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "row": { "type": "integer", "exclusiveMinimum": 0, "description": "The 1-based row it is about (CSV: data row; header and blank lines not counted)." }, "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "original": { "type": "string", "minLength": 1 }, "normalized": { "type": "string", "minLength": 1 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "valid": { "type": "integer", "minimum": 0 }, "risky": { "type": "integer", "minimum": 0 }, "invalid": { "type": "integer", "minimum": 0 }, "unscored": { "type": "integer", "minimum": 0 }, "persistence": { "type": "object", "properties": { "matched": { "type": "integer", "minimum": 0 }, "modified": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "matched", "modified", "failed" ], "additionalProperties": false } }, "required": [ "valid", "risky", "invalid", "unscored" ], "additionalProperties": false }, "validationJobId": { "type": "string" }, "importId": { "type": "string", "description": "This batch's Import History id. Each contact it wrote carries it as `importId` until a later import touches that contact, so a contact filter on `importId` lists them. Absent on a dry run." }, "dryRun": { "type": "boolean", "enum": [ true ], "description": "Present on a dry run: the counts say what the import would do, and nothing was written." } }, "required": [ "summary", "fieldsCreated", "errors", "warnings" ], "additionalProperties": false }, "ContactsImportCsvRequest": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 5000000 }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "validate": { "type": "boolean", "description": "Optional deliverability check on ingestion. When true, each imported address is validated with the provider and the verdict is saved to the contact’s `validationStatus`. Imports of at most 100 submitted CSV data rows validate inline, metered at 2 credits per submitted row on a successful response, including skipped rows and repeated addresses. Larger imports write first and use a background validation workflow billed per address as it runs; `validationJobId` is returned when a job is queued. The job skips unsubscribed, suppressed and recently validated addresses, and a `VALIDATION_SKIPPED` warning gives the counts; when every address is skipped no job is queued and `validationJobId` is absent." }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Consent record stamped on every imported row (typically `{ \"source\": \"import\" }`)." }, "dateOrder": { "type": "string", "enum": [ "month_first", "day_first" ], "description": "Order for a date column whose dates read either way (`03/04/2026`): `day_first` is 3 April, `month_first` 4 March. A day over 12 in the column overrides it. Default month-first, with a DATE_ORDER_ASSUMED warning." }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name this batch is listed under in Import History (usually the source file name, e.g. `customers.csv`), also stamped on every contact it writes as `csvFileName`. A path keeps only its last segment." }, "dryRun": { "type": "boolean", "description": "When true, returns what this import would return and writes nothing: no contacts, fields, Import History entry or `importId`; `validate` is skipped and nothing is charged." }, "onConflict": { "type": "string", "enum": [ "upsert", "skip" ], "description": "`upsert` (default) updates existing contacts; `skip` only creates missing ones, leaving each existing contact unchanged (counted in `summary.skipped`, with a `CONTACT_EXISTS_SKIPPED` warning)." } }, "required": [ "csv" ], "additionalProperties": false }, "ContactsImportRequest": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "subscribed": { "type": "boolean" }, "customFields": { "type": "object", "additionalProperties": {} }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Marketing consent provenance to record on this contact. Optional at creation; an inline marketing send to this address later needs the contact to be subscribed and warns when no record exists." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "validate": { "type": "boolean", "description": "Optional deliverability check on ingestion. When true, each imported address is validated with the provider and the verdict is saved to the contact’s `validationStatus`. Imports of at most 100 submitted contacts validate inline, metered at 2 credits per submitted contact on a successful response, including rows that fail. Larger imports write first and use a background validation workflow billed per address as it runs; `validationJobId` is returned when a job is queued. The job skips unsubscribed, suppressed and recently validated addresses, and a `VALIDATION_SKIPPED` warning gives the counts; when every address is skipped no job is queued and `validationJobId` is absent." }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "form", "import" ], "description": "Who captured it: `api`, `form`, or `import`. (`app` is reserved for the in-app CSV wizard.)" }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601; defaults to now." }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "source" ], "additionalProperties": false, "description": "Default consent record for every row that does not carry its own `consent` (typically `{ \"source\": \"import\" }`)." }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name this batch is listed under in Import History (usually the source file name, e.g. `customers.csv`), also stamped on every contact it writes as `csvFileName`. A path keeps only its last segment." }, "dryRun": { "type": "boolean", "description": "When true, returns what this import would return and writes nothing: no contacts, fields, Import History entry or `importId`; `validate` is skipped and nothing is charged." }, "onConflict": { "type": "string", "enum": [ "upsert", "skip" ], "description": "`upsert` (default) updates existing contacts; `skip` only creates missing ones, leaving each existing contact unchanged (counted in `summary.skipped`, with a `CONTACT_EXISTS_SKIPPED` warning)." } }, "required": [ "contacts" ], "additionalProperties": false }, "ContactsBatchDeleteResponse": { "type": "object", "properties": { "deletedCount": { "type": "integer", "minimum": 0 }, "notFound": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "deletedCount", "notFound" ], "additionalProperties": false }, "ContactsBatchDeleteRequest": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "minItems": 1, "maxItems": 1000 } }, "required": [ "emails" ], "additionalProperties": false }, "FieldsGetResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1 }, "fieldType": { "type": "string", "enum": [ "string", "number", "date", "bool" ] }, "label": { "type": "string" }, "isCore": { "type": "boolean" }, "isFilterable": { "type": "boolean" }, "isSortable": { "type": "boolean" }, "isSearchable": { "type": "boolean" }, "coverage": { "type": "object", "properties": { "percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "approximate": { "type": "boolean" }, "topValues": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "percent": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "value", "count", "percent" ], "additionalProperties": false } }, "dominantValue": { "type": "string" } }, "required": [ "percent", "approximate", "topValues" ], "additionalProperties": false } }, "required": [ "fieldName", "fieldType" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "FieldsPostRequest": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1 }, "fieldType": { "type": "string", "enum": [ "string", "number", "date", "bool" ] } }, "required": [ "fieldName", "fieldType" ], "additionalProperties": false }, "FieldsDeleteResponse": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1 }, "deleted": { "type": "boolean" } }, "required": [ "fieldName", "deleted" ], "additionalProperties": false }, "AudiencesListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "audienceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "audienceName": { "type": "string", "minLength": 1, "maxLength": 200 }, "filters": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "contains_any", "not_contains_any", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "between", "is_true", "is_false", "in", "not_in", "is_empty", "not_exists", "is_not_empty", "exists", "is_set", "before", "after", "on_date" ] }, "value": {}, "type": { "type": "string", "description": "Saved audiences infer omitted types from the field registry. Unknown fields compare as strings. Date ranges require type: \"date\"." } }, "required": [ "field", "operator" ], "additionalProperties": false } }, "logicalOperator": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "filters", "logicalOperator" ], "additionalProperties": false }, "count": { "type": "integer", "minimum": 0 }, "materializationStatus": { "type": "string", "enum": [ "pending", "running", "ready", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "build": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "cohort": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "skipped", "unsubscribed" ] }, "minItems": 1, "maxItems": 10 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Scope to one send (a `sendId` from a send or send-analytics row). With `sendId` the window may be omitted." }, "emailId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "Scope to events from sends that targeted these audiences." }, "recipient": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 10, "description": "Recipient rule tokens using the Events-page grammar." }, "includeMachineClicks": { "type": "boolean" }, "exclude": { "type": "object", "properties": { "baseAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "baseAudienceId" ], "additionalProperties": false } }, "required": [ "eventTypes", "from", "to" ], "additionalProperties": false }, "field": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "date" ] } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "eventsScanned": { "type": "integer", "minimum": 0 }, "stampedContacts": { "type": "integer", "minimum": 0 } }, "required": [ "eventsScanned" ], "additionalProperties": false }, "error": { "type": "string" }, "enqueuedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "jobId", "status", "cohort", "field", "counts", "enqueuedAt" ], "additionalProperties": false } }, "required": [ "audienceId", "audienceName", "filters", "count", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "AudienceWriteResponse": { "type": "object", "properties": { "audienceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "audienceName": { "type": "string", "minLength": 1, "maxLength": 200 }, "filters": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "contains_any", "not_contains_any", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "between", "is_true", "is_false", "in", "not_in", "is_empty", "not_exists", "is_not_empty", "exists", "is_set", "before", "after", "on_date" ] }, "value": {}, "type": { "type": "string", "description": "Saved audiences infer omitted types from the field registry. Unknown fields compare as strings. Date ranges require type: \"date\"." } }, "required": [ "field", "operator" ], "additionalProperties": false } }, "logicalOperator": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "filters", "logicalOperator" ], "additionalProperties": false }, "count": { "type": "integer", "minimum": 0 }, "materializationStatus": { "type": "string", "enum": [ "pending", "running", "ready", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "build": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "cohort": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "skipped", "unsubscribed" ] }, "minItems": 1, "maxItems": 10 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Scope to one send (a `sendId` from a send or send-analytics row). With `sendId` the window may be omitted." }, "emailId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "Scope to events from sends that targeted these audiences." }, "recipient": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 10, "description": "Recipient rule tokens using the Events-page grammar." }, "includeMachineClicks": { "type": "boolean" }, "exclude": { "type": "object", "properties": { "baseAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "baseAudienceId" ], "additionalProperties": false } }, "required": [ "eventTypes", "from", "to" ], "additionalProperties": false }, "field": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "date" ] } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "eventsScanned": { "type": "integer", "minimum": 0 }, "stampedContacts": { "type": "integer", "minimum": 0 } }, "required": [ "eventsScanned" ], "additionalProperties": false }, "error": { "type": "string" }, "enqueuedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "jobId", "status", "cohort", "field", "counts", "enqueuedAt" ], "additionalProperties": false }, "emailListMaterializations": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "Custom-field key the address list was stamped onto." }, "providedEmails": { "type": "integer", "description": "Distinct addresses supplied after normalization." }, "matchedContacts": { "type": "integer", "description": "Addresses that matched an EXISTING contact and were stamped — a gap vs `providedEmails` means those addresses have no contact record (import them first)." } }, "required": [ "fieldName", "providedEmails", "matchedContacts" ], "additionalProperties": false }, "description": "Present when an `email in [...]` clause with more than 100 addresses was auto-converted into a stamped custom-field snapshot." }, "membership": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "alreadyPresent": { "type": "array", "items": { "type": "string" } }, "unExcluded": { "type": "array", "items": { "type": "string" }, "description": "Were excluded by an `email not_in` clause, now lifted." }, "removedFromList": { "type": "array", "items": { "type": "string" } }, "excludedByFilter": { "type": "array", "items": { "type": "string" }, "description": "Removed through an `email not_in` exclusion." }, "notAMember": { "type": "array", "items": { "type": "string" } }, "noContactYet": { "type": "array", "items": { "type": "string" }, "description": "Added addresses with no contact: they match nobody until the contact exists." } }, "required": [ "added", "alreadyPresent", "unExcluded", "removedFromList", "excludedByFilter", "notAMember", "noContactYet" ], "additionalProperties": false, "description": "With `addEmails`/`removeEmails`: what happened to each address." } }, "required": [ "audienceId", "audienceName", "filters", "count", "createdAt", "updatedAt" ], "additionalProperties": false }, "AudiencesPostRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "filters": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "contains_any", "not_contains_any", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "between", "is_true", "is_false", "in", "not_in", "is_empty", "not_exists", "is_not_empty", "exists", "is_set", "before", "after", "on_date" ] }, "value": { "description": "Operator-dependent: `between` takes `[min, max]` or `{min, max}`; `in`/`not_in`/`contains_any`/`not_contains_any` take an array, not a comma-separated string; unary operators (`is_empty`, `is_not_empty`, `exists`, `is_true`, …) omit it." }, "type": { "type": "string", "description": "Saved audiences infer omitted types from the field registry. Unknown fields compare as strings. Date ranges require type: \"date\"." } }, "required": [ "field", "operator" ], "additionalProperties": false }, "minItems": 1 }, "logicalOperator": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "filters", "logicalOperator" ], "additionalProperties": false, "description": "Filter clauses combined by `logicalOperator`. For specific addresses use `{ field: \"email\", operator: \"in\", value: [\"a@x.com\", ...] }` — a list over 100 addresses is auto-converted into a stamped custom-field snapshot of the listed EXISTING contacts (addresses without a contact record are skipped; 10,000 max)." } }, "required": [ "name", "filters" ], "additionalProperties": false }, "AudiencesFromEventsResponse": { "type": "object", "properties": { "audienceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "audienceName": { "type": "string", "minLength": 1, "maxLength": 200 }, "filters": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "contains_any", "not_contains_any", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "between", "is_true", "is_false", "in", "not_in", "is_empty", "not_exists", "is_not_empty", "exists", "is_set", "before", "after", "on_date" ] }, "value": {}, "type": { "type": "string", "description": "Saved audiences infer omitted types from the field registry. Unknown fields compare as strings. Date ranges require type: \"date\"." } }, "required": [ "field", "operator" ], "additionalProperties": false } }, "logicalOperator": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "filters", "logicalOperator" ], "additionalProperties": false }, "count": { "type": "integer", "minimum": 0 }, "materializationStatus": { "type": "string", "enum": [ "pending", "running", "ready", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "build": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "cohort": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "skipped", "unsubscribed" ] }, "minItems": 1, "maxItems": 10 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "sendId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Scope to one send (a `sendId` from a send or send-analytics row). With `sendId` the window may be omitted." }, "emailId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "Scope to events from sends that targeted these audiences." }, "recipient": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 10, "description": "Recipient rule tokens using the Events-page grammar." }, "includeMachineClicks": { "type": "boolean" }, "exclude": { "type": "object", "properties": { "baseAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "baseAudienceId" ], "additionalProperties": false } }, "required": [ "eventTypes", "from", "to" ], "additionalProperties": false }, "field": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "date" ] } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "eventsScanned": { "type": "integer", "minimum": 0 }, "stampedContacts": { "type": "integer", "minimum": 0 } }, "required": [ "eventsScanned" ], "additionalProperties": false }, "error": { "type": "string" }, "enqueuedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "jobId", "status", "cohort", "field", "counts", "enqueuedAt" ], "additionalProperties": false } }, "required": [ "audienceId", "audienceName", "filters", "count", "materializationStatus", "createdAt", "updatedAt", "build" ], "additionalProperties": false }, "AudiencesFromEventsRequest": { "type": "object", "properties": { "cohort": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "skipped", "unsubscribed" ] }, "minItems": 1, "maxItems": 10 }, "from": { "type": "string", "format": "date-time", "description": "Window start. Required unless `sendId` is set — then it defaults to one hour before that send was dispatched (its scheduled time for a scheduled send; a completion pass's re-stamped start is never used), and `to` to now." }, "to": { "type": "string", "format": "date-time", "description": "Defaults to now." }, "sendId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Scope to one send (a `sendId` from a send or send-analytics row). With `sendId` the window may be omitted." }, "emailId": { "type": "string", "minLength": 1, "maxLength": 64 }, "automationIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "Scope to events from sends that targeted these audiences." }, "recipient": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 10, "description": "Recipient rule tokens using the Events-page grammar." }, "includeMachineClicks": { "type": "boolean" }, "exclude": { "type": "object", "properties": { "baseAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false, "description": "COMPLEMENT mode: the audience becomes every contact of `baseAudienceId` who did NOT match the cohort — a copy of the base audience's filters (taken when the build starts; later edits to the base do not propagate) AND the cohort field is empty. `baseAudienceId` defaults to the send's audience when `sendId` is set; `\"all\"` means the whole brand. The base must combine its filters with AND (or have one filter) and must not be an event snapshot that is still building." } }, "required": [ "eventTypes" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "cohort" ], "additionalProperties": false }, "AudiencesPatchRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "filters": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "contains_any", "not_contains_any", "starts_with", "ends_with", "gt", "gte", "lt", "lte", "between", "is_true", "is_false", "in", "not_in", "is_empty", "not_exists", "is_not_empty", "exists", "is_set", "before", "after", "on_date" ] }, "value": { "description": "Operator-dependent: `between` takes `[min, max]` or `{min, max}`; `in`/`not_in`/`contains_any`/`not_contains_any` take an array, not a comma-separated string; unary operators (`is_empty`, `is_not_empty`, `exists`, `is_true`, …) omit it." }, "type": { "type": "string", "description": "Saved audiences infer omitted types from the field registry. Unknown fields compare as strings. Date ranges require type: \"date\"." } }, "required": [ "field", "operator" ], "additionalProperties": false }, "minItems": 1 }, "logicalOperator": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "filters", "logicalOperator" ], "additionalProperties": false, "description": "Filter clauses combined by `logicalOperator`. For specific addresses use `{ field: \"email\", operator: \"in\", value: [\"a@x.com\", ...] }` — a list over 100 addresses is auto-converted into a stamped custom-field snapshot of the listed EXISTING contacts (addresses without a contact record are skipped; 10,000 max)." }, "addEmails": { "type": "array", "items": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$" }, "minItems": 1, "maxItems": 1000, "description": "Add these contacts to the audience by email, instead of rewriting `filters`. Refused with 409 AUDIENCE_MEMBERSHIP_NOT_EXPRESSIBLE when the filters cannot express the edit exactly, or when the email list would pass 100 addresses (stored as a snapshot of existing contacts) while a listed address has no contact." }, "removeEmails": { "type": "array", "items": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$" }, "minItems": 1, "maxItems": 1000, "description": "Remove these contacts from the audience by email (same rule as `addEmails`)." }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional optimistic-concurrency precondition from the latest audience read. The update returns 409 if the row changed meanwhile." } }, "additionalProperties": false }, "AudiencesDeleteResponse": { "type": "object", "properties": { "audienceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "deleted": { "type": "boolean" } }, "required": [ "audienceId", "deleted" ], "additionalProperties": false }, "DomainsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainUrl": { "type": "string", "format": "uri" }, "name": { "type": "string", "minLength": 1, "maxLength": 253 }, "region": { "type": "string" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed", "temporary_failure", "partially_verified", "partially_failed" ] }, "sendingEnabled": { "type": "boolean" }, "sendable": { "type": "boolean" }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "marketing (default) or transactional. Transactional domains skip unsubscribe and send via automation sendEmail nodes (or a test send)." }, "records": { "type": "array", "items": { "type": "object", "properties": { "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "ttl": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "number" } }, "required": [ "record", "name", "type", "ttl", "status", "value" ], "additionalProperties": false } }, "openTracking": { "type": "boolean" }, "clickTracking": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "domainId", "domainUrl", "name", "region", "status", "sendingEnabled", "sendable", "sendingPurpose", "records", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "DomainsPostRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 253 }, "region": { "type": "string", "enum": [ "us-east-1" ] }, "customReturnPath": { "type": "string", "minLength": 1, "maxLength": 64 }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "default": "marketing", "description": "marketing (default) for campaigns and audience sends, or transactional for event-triggered automation mail (no unsubscribe requirement)." } }, "required": [ "name" ], "additionalProperties": false }, "DomainsPatchRequest": { "type": "object", "properties": { "defaultSenderName": { "type": "string", "maxLength": 120 }, "defaultFromEmail": { "type": "string", "maxLength": 320 }, "defaultReplyToEmail": { "type": "string", "format": "email" }, "sendingPurpose": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "Change the domain purpose. Live gates fail closed if a campaign still points at a transactional domain; automation sends re-derive their class from the new purpose, so after a flip to transactional, published automations send with no unsubscribe link and to unsubscribed contacts." } }, "additionalProperties": false }, "DomainsDeleteResponse": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "deleted": { "type": "boolean" } }, "required": [ "domainId", "deleted" ], "additionalProperties": false }, "DomainUnsubscribesListResponse": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainHost": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "scope": { "type": "string", "enum": [ "domain", "all", "both" ] }, "unsubscribedAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "link", "one_click", "api", "import", "manual" ] }, "sendId": { "type": "string" } }, "required": [ "email", "scope" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "domainId", "domainHost", "data", "pagination" ], "additionalProperties": false }, "DomainUnsubscribesAddResponse": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainHost": { "type": "string" }, "summary": { "type": "object", "properties": { "received": { "type": "integer" }, "added": { "type": "integer" }, "alreadyUnsubscribed": { "type": "integer" }, "created": { "type": "integer" }, "invalid": { "type": "integer" } }, "required": [ "received", "added", "alreadyUnsubscribed", "created", "invalid" ], "additionalProperties": false }, "invalid": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "code": { "type": "string", "enum": [ "INVALID_EMAIL" ] } }, "required": [ "email", "code" ], "additionalProperties": false } } }, "required": [ "domainId", "domainHost", "summary", "invalid" ], "additionalProperties": false }, "DomainUnsubscribesAddRequest": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "maxLength": 320 }, "minItems": 1, "maxItems": 1000 } }, "required": [ "emails" ], "additionalProperties": false }, "DomainUnsubscribeRemoveResponse": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainHost": { "type": "string" }, "email": { "type": "string" }, "removed": { "type": "boolean" }, "globallyUnsubscribed": { "type": "boolean" } }, "required": [ "domainId", "domainHost", "email", "removed", "globallyUnsubscribed" ], "additionalProperties": false }, "DomainUnsubscribesImportResponse": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainHost": { "type": "string" }, "summary": { "type": "object", "properties": { "rows": { "type": "integer" }, "added": { "type": "integer" }, "alreadyUnsubscribed": { "type": "integer" }, "created": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "rows", "added", "alreadyUnsubscribed", "created", "skipped" ], "additionalProperties": false }, "skippedSample": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" }, "column": { "type": [ "string", "null" ] } }, "required": [ "domainId", "domainHost", "summary", "skippedSample", "truncated", "column" ], "additionalProperties": false }, "DomainUnsubscribesImportRequest": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 2000000 }, "column": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "csv" ], "additionalProperties": false }, "DomainUnsubscribesExportResponse": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "domainHost": { "type": "string" }, "csv": { "type": "string" }, "rowCount": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "domainId", "domainHost", "csv", "rowCount", "truncated" ], "additionalProperties": false }, "DomainHealth": { "type": "object", "properties": { "domainId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 253 }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed", "temporary_failure", "partially_verified", "partially_failed" ] }, "sendable": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "healthy", "at_risk", "critical" ] }, "readiness": { "type": "string", "enum": [ "ready", "ready_with_warnings", "not_ready", "checking", "unknown" ] }, "score": { "type": "object", "properties": { "placementMeasured": { "type": "boolean" }, "value": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor", "critical" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "components": { "type": "object", "properties": { "placement": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" } }, "required": [ "score", "weight", "basis" ], "additionalProperties": false }, "authentication": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" } }, "required": [ "score", "weight", "basis" ], "additionalProperties": false }, "reputation": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" } }, "required": [ "score", "weight", "basis" ], "additionalProperties": false }, "content": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" } }, "required": [ "score", "weight", "basis" ], "additionalProperties": false }, "posture": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" } }, "required": [ "score", "weight", "basis" ], "additionalProperties": false } }, "required": [ "placement", "authentication", "reputation", "content", "posture" ], "additionalProperties": false }, "trend": { "type": [ "object", "null" ], "properties": { "direction": { "type": "string", "enum": [ "up", "down", "flat" ] }, "previousScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "previousComputedAt": { "type": "string", "format": "date-time" } }, "required": [ "direction", "previousScore", "previousComputedAt" ], "additionalProperties": false } }, "required": [ "value", "grade", "confidence", "components", "trend" ], "additionalProperties": false }, "authentication": { "type": "object", "properties": { "spf": { "type": "string", "enum": [ "verified", "pending", "failed", "missing" ] }, "dkim": { "type": "string", "enum": [ "verified", "pending", "failed", "missing" ] }, "dmarc": { "type": "string", "enum": [ "verified", "pending", "missing" ] } }, "required": [ "spf", "dkim", "dmarc" ], "additionalProperties": false }, "tracking": { "type": "object", "properties": { "linksStatus": { "type": "string", "enum": [ "live", "no_cert", "unreachable", "unknown" ] }, "openTracking": { "type": "boolean" }, "clickTracking": { "type": "boolean" } }, "additionalProperties": false }, "warmup": { "type": "array", "items": { "type": "object", "properties": { "sendId": { "type": "string" }, "currentTranche": { "type": "integer" }, "sentSoFar": { "type": "integer" }, "pausedAt": { "type": "string", "format": "date-time" }, "pauseReason": { "type": "string" }, "rampEndsAt": { "type": "string", "format": "date-time" } }, "required": [ "sendId" ], "additionalProperties": false } }, "dailyVolume": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "sent": { "type": "integer", "minimum": 0 } }, "required": [ "day", "sent" ], "additionalProperties": false }, "description": "Deprecated — always empty. Gradual sends no longer share a per-domain daily budget." }, "domainActivity": { "type": [ "object", "null" ], "properties": { "sampled": { "type": "boolean", "enum": [ true ] }, "sampleSendCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "bouncedCount": { "type": "integer", "minimum": 0 }, "complainedCount": { "type": "integer", "minimum": 0 }, "bounceRate": { "type": [ "number", "null" ] }, "complaintRate": { "type": [ "number", "null" ] } }, "required": [ "sampled", "sampleSendCount", "sentCount", "deliveredCount", "bouncedCount", "complainedCount", "bounceRate", "complaintRate" ], "additionalProperties": false, "description": "Campaign and automation activity, excluding placement seeds. A bounded sample, not a time-window total. Null when no sampled recipients were sent." }, "orgReputation": { "type": [ "object", "null" ], "properties": { "scope": { "type": "string", "enum": [ "org" ] }, "totalSent": { "type": "integer", "minimum": 0 }, "bounceRate": { "type": [ "number", "null" ] }, "complaintRate": { "type": [ "number", "null" ] } }, "required": [ "scope", "totalSent", "bounceRate", "complaintRate" ], "additionalProperties": false }, "recentPlacementTests": { "type": "array", "items": { "type": "object", "properties": { "testId": { "type": "string" }, "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "phase": { "type": "string", "enum": [ "sending", "collecting" ] }, "overall": { "type": [ "object", "null" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "inbox": { "type": "integer", "minimum": 0 }, "spam": { "type": "integer", "minimum": 0 }, "missing": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 } }, "required": [ "total", "inbox", "spam", "missing", "pending" ] }, "authentication": { "type": [ "object", "null" ], "properties": { "spf": { "type": "string" }, "dkim": { "type": "string" }, "dmarc": { "type": "string" } }, "additionalProperties": false }, "spamFilterFlagged": { "type": "boolean" }, "source": { "type": "string" }, "variant": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "testId", "emailId", "status", "overall", "authentication", "spamFilterFlagged", "createdAt" ], "additionalProperties": false } }, "signals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "domain_not_verified", "dns_record_failed", "dmarc_missing", "dmarc_invalid", "sending_disabled", "tracking_links_broken", "high_bounce_rate", "high_complaint_rate", "placement_spam_heavy", "content_spam_filter_flagged", "auth_failing_in_tests", "placement_baseline_spam", "content_image_weight_penalty", "content_promotional_penalty", "content_promotions_tab_shift", "warmup_paused", "org_reputation_restricted" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "summary": { "type": "string" }, "suggestion": { "type": "string" }, "action": { "type": "object", "properties": { "tool": { "type": "string" }, "note": { "type": "string" } }, "required": [ "tool" ], "additionalProperties": false } }, "required": [ "id", "severity", "summary", "suggestion" ], "additionalProperties": false } }, "checkedAt": { "type": "string", "format": "date-time" }, "scoreHistory": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor", "critical" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "trigger": { "type": "string", "enum": [ "placement_test", "domain_verified", "domain_score_run", "health_read" ] }, "computedAt": { "type": "string", "format": "date-time" }, "components": { "type": "object", "properties": { "placement": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "score", "weight" ], "additionalProperties": false }, "authentication": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "score", "weight" ], "additionalProperties": false }, "reputation": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "score", "weight" ], "additionalProperties": false }, "content": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "score", "weight" ], "additionalProperties": false }, "posture": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "score", "weight" ], "additionalProperties": false } }, "required": [ "placement", "authentication", "reputation", "content", "posture" ], "additionalProperties": false } }, "required": [ "score", "grade", "confidence", "trigger", "computedAt", "components" ], "additionalProperties": false }, "maxItems": 50, "description": "With `include=scoreHistory`: up to 50 saved score snapshots, newest first. Snapshots are saved when a placement test completes, the domain is verified, or a score run finishes. Only snapshots saved under this brand count, searched among the domain's newest 500, so a domain that moved between brands can show fewer." }, "scoreRuns": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string" }, "trigger": { "type": "string", "enum": [ "domain_verified", "manual" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "collecting" ] }, "scoreAfter": { "type": [ "object", "null" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor", "critical" ] } }, "required": [ "score", "grade" ], "additionalProperties": false }, "creditsCharged": { "type": "number", "minimum": 0 }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variant": { "type": "string", "enum": [ "plain_text", "text_forward", "balanced", "image_heavy", "promotional" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ] }, "phase": { "type": "string", "enum": [ "sending", "collecting" ] }, "testId": { "type": "string" }, "emailId": { "type": "string" }, "overall": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "inbox": { "type": "integer", "minimum": 0 }, "spam": { "type": "integer", "minimum": 0 }, "missing": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 } }, "required": [ "total", "inbox", "spam", "missing", "pending" ], "additionalProperties": false } }, "required": [ "variant" ], "additionalProperties": false } }, "errorMessage": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "runId", "trigger", "status", "scoreAfter", "creditsCharged", "variants", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 5, "description": "With `include=scoreRuns`: the last 5 automated domain score runs (the 5-variant seed check), newest first." } }, "required": [ "domainId", "name", "status", "sendable", "verdict", "readiness", "score", "authentication", "tracking", "warmup", "dailyVolume", "domainActivity", "orgReputation", "recentPlacementTests", "signals", "checkedAt" ], "additionalProperties": false }, "TemplatesListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "brand": { "type": "string", "minLength": 1 }, "html": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "minLength": 1, "format": "date-time" } }, "required": [ "emailId", "title", "html", "previewImage", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "FlowsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "brand": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "logo": { "type": "string", "format": "uri" } }, "required": [ "name" ], "additionalProperties": false }, "title": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "newsletter", "signup" ] }, "kind": { "type": "string", "enum": [ "onboarding", "trial", "events", "product_updates", "promotions" ] }, "category": { "type": "string", "minLength": 1 }, "categoryLabel": { "type": "string", "minLength": 1 }, "emailCount": { "type": "integer", "minimum": 1 }, "spanDays": { "type": "number", "minimum": 0 }, "remixCount": { "type": "integer", "minimum": 0 }, "previewImages": { "type": "array", "items": { "type": "string", "format": "uri" } }, "publishedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "anchor": { "type": "string", "enum": [ "submittedAt", "signedUpAt", "verifiedAt", "firstEmail" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer", "minimum": 1 }, "dayOffset": { "type": "number", "minimum": 0 }, "delayDays": { "type": "number", "minimum": 0 }, "subject": { "type": "string", "minLength": 1 }, "previewText": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "categoryLabel": { "type": "string", "minLength": 1 }, "emailId": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "html": { "type": "string", "minLength": 1 } }, "required": [ "order", "dayOffset", "delayDays", "subject", "category", "categoryLabel", "emailId" ], "additionalProperties": false } } }, "required": [ "slug", "brand", "title", "type", "category", "categoryLabel", "emailCount", "spanDays", "remixCount", "previewImages", "publishedAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false }, "total": { "type": "integer", "minimum": 0, "description": "Flows this query matches across every page (filters narrow, `semantic` only orders); a floor when `isTotalExact` is false." }, "isTotalExact": { "type": "boolean", "description": "False when the read was cut at 500 flows (the newest, or the 500 nearest a `semantic` query), so `total` is a floor." } }, "required": [ "data", "pagination", "total", "isTotalExact" ], "additionalProperties": false }, "BrandGetResponse": { "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "extracting", "completed", "failed", "deleting" ] }, "ready": { "type": "boolean" }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "phase": { "type": "string" }, "error": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "identity": { "type": "object", "properties": { "brandName": { "type": "string" }, "description": { "type": "string" }, "tagline": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "address": { "type": "string" }, "socialLinks": { "type": "array", "items": {} }, "contentLinks": { "type": "array", "items": {} } }, "additionalProperties": {} }, "emailDesign": { "type": "string" }, "imageStyle": { "type": "string" }, "logos": { "type": "array", "items": { "type": "object", "properties": { "src": { "type": "string" }, "type": { "type": "string" }, "theme": { "type": "string" }, "format": { "type": "string" }, "background": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "size": { "type": "number" } }, "required": [ "src" ] } } }, "required": [ "brandId", "domain", "status", "ready", "identity" ], "additionalProperties": false }, "BrandPatchRequest": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "brandName": { "type": "string", "minLength": 1, "description": "The brand name as emails write it." }, "description": { "type": "string", "description": "A short summary of what the brand does and for whom." }, "tagline": { "type": "string", "description": "The brand’s slogan." }, "contactEmail": { "type": "string", "description": "The brand’s public contact email address." }, "contactPhone": { "type": "string", "description": "The brand’s public contact phone number." }, "address": { "type": "string", "description": "The brand’s postal address, for email footers." } }, "additionalProperties": false, "description": "Saved identity fields to change; fields left out keep their value." }, "emailDesign": { "type": "string", "maxLength": 200000 }, "imageStyle": { "type": "string", "maxLength": 200000 } }, "additionalProperties": false }, "BrandImagesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string" }, "kind": { "type": "string", "enum": [ "logo", "brand", "generated" ] }, "url": { "type": "string" }, "description": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "category": { "type": "string" }, "pageUrl": { "type": "string" }, "addedAt": { "type": "string", "format": "date-time" }, "logo": { "type": "object", "properties": { "type": { "type": "string" }, "theme": { "type": "string" }, "background": { "type": "string" }, "format": { "type": "string" } } } }, "required": [ "assetId", "kind", "url" ] } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "BrandImageDeleteResponse": { "type": "object", "properties": { "assetId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "assetId", "deleted" ], "additionalProperties": false }, "BrandsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "extracting", "completed", "failed", "deleting" ] }, "ready": { "type": "boolean" }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "phase": { "type": "string" }, "error": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "brandId", "domain", "status", "ready" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "BrandsCreateResponse": { "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "extracting", "completed", "failed", "deleting" ] }, "ready": { "type": "boolean" }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "phase": { "type": "string" }, "error": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "extraction": { "type": "object", "properties": { "chatId": { "type": "string", "minLength": 1 }, "statusUrl": { "type": "string", "minLength": 1 } }, "required": [ "chatId", "statusUrl" ] } }, "required": [ "brandId", "domain", "status", "ready", "extraction" ], "additionalProperties": false }, "BrandsCreateRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Website URL or bare domain to extract the brand from." }, "instructions": { "type": "string", "maxLength": 4000, "description": "Brand guidance the extraction treats as authoritative: brand name, colors, fonts, voice, which pages matter most." }, "includePaths": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "maxItems": 50, "description": "Extra page URLs to read beyond the automatic crawl." }, "excludePaths": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "maxItems": 50, "description": "Path prefixes the crawl skips, e.g. `/blog` or `/careers` (case-insensitive)." }, "excludeSubdomains": { "type": "array", "items": { "type": "string", "maxLength": 253 }, "maxItems": 50, "description": "Subdomains the crawl skips: a full host such as `shop.example.com`, or a leftmost label such as `blog`." } }, "required": [ "url" ], "additionalProperties": false }, "BrandGetByIdResponse": { "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "extracting", "completed", "failed", "deleting" ] }, "ready": { "type": "boolean" }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "phase": { "type": "string" }, "error": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "brandId", "domain", "status", "ready" ], "additionalProperties": false }, "ContentImageResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "prompt": { "type": "string" }, "description": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "prompt" ], "additionalProperties": false }, "ContentGenerateImageRequest": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "mode": { "type": "string", "enum": [ "text-to-image", "image-editing" ] }, "aspectRatio": { "type": "string", "enum": [ "16:9", "3:2", "4:3", "1:1", "4:5", "2:3", "3:4", "9:16" ] }, "image1": { "type": "string", "format": "uri" }, "image2": { "type": "string", "format": "uri" }, "adCreative": { "type": "object", "properties": { "brandName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": "string", "minLength": 1, "maxLength": 200 }, "cta": { "type": "string", "minLength": 1, "maxLength": 100 }, "format": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9" ] }, "archetype": { "type": "string", "enum": [ "product-ui-card", "mascot", "flat-illustration", "abstract-brand", "type-led", "photo-ui-overlay", "conceptual-3d", "gradient-field", "editorial-photo", "collage", "isometric-blueprint", "data-viz" ] }, "layout": { "type": "string", "enum": [ "split-right", "split-left", "stacked-center", "visual-first", "type-poster", "immersive-field", "layered-collage", "badge-offer", "diagonal-stage", "editorial-grid" ] }, "eyebrow": { "type": "string", "minLength": 1, "maxLength": 80 }, "subjectImageUrl": { "type": "string", "format": "uri" }, "emailCanvasColor": { "type": "string", "minLength": 1, "maxLength": 40 }, "typeface": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 60 }, "register": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "family" ], "additionalProperties": false }, "palette": { "type": "object", "properties": { "background": { "type": "string", "minLength": 1 }, "accent": { "type": "string", "minLength": 1 }, "headlineColor": { "type": "string", "minLength": 1 } }, "required": [ "background", "accent", "headlineColor" ], "additionalProperties": false }, "supportingVisual": { "type": "string", "maxLength": 600 }, "subhead": { "type": "string", "maxLength": 200 } }, "required": [ "brandName", "headline", "cta", "format", "archetype", "palette" ], "additionalProperties": false } }, "additionalProperties": false }, "ContentGifResponse": { "type": "object", "properties": { "gifUrl": { "type": "string", "format": "uri" }, "videoUrl": { "type": "string", "format": "uri" }, "generatedImageUrl": { "type": "string", "format": "uri" }, "altText": { "type": "string" }, "duration": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "height": { "type": "integer", "exclusiveMinimum": 0 }, "loop": { "type": "boolean" } }, "required": [ "gifUrl" ], "additionalProperties": false }, "ContentGifRequest": { "oneOf": [ { "type": "object", "properties": { "from": { "type": "string", "enum": [ "prompt" ] }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "fps": { "type": "integer", "minimum": 1, "maximum": 24 }, "aspectRatio": { "type": "string", "enum": [ "16:9", "9:16", "1:1" ] }, "loop": { "type": "boolean" } }, "required": [ "from", "prompt" ], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "enum": [ "image" ] }, "imageUrl": { "type": "string", "format": "uri" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "fps": { "type": "integer", "minimum": 1, "maximum": 24 }, "aspectRatio": { "type": "string", "enum": [ "16:9", "9:16", "1:1" ] }, "loop": { "type": "boolean" } }, "required": [ "from", "imageUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "enum": [ "video" ] }, "videoUrl": { "type": "string", "format": "uri" }, "fps": { "type": "integer", "minimum": 1, "maximum": 24 }, "width": { "type": "integer", "minimum": 16, "maximum": 2000 } }, "required": [ "from", "videoUrl" ], "additionalProperties": false } ] }, "ContentTransformResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 }, "aspectRatio": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "fallbackUsed": { "type": "boolean" } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "ContentTransformRequest": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "optimize" ] }, "imageUrl": { "type": "string", "format": "uri" } }, "required": [ "operation", "imageUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "resize" ] }, "imageUrl": { "type": "string", "format": "uri" }, "width": { "type": "integer", "minimum": 1, "maximum": 4096 }, "height": { "type": "integer", "minimum": 1, "maximum": 4096 }, "prompt": { "type": "string", "maxLength": 2000 }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ] }, "outputFormat": { "type": "string", "enum": [ "png", "jpeg", "webp" ] } }, "required": [ "operation", "imageUrl", "width", "height" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "remove_background" ] }, "imageUrl": { "type": "string", "format": "uri" } }, "required": [ "operation", "imageUrl" ], "additionalProperties": false } ] }, "ContentPngResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "width": { "type": "integer", "minimum": 0 } }, "required": [ "url", "width" ], "additionalProperties": false }, "ContentHtmlToPngRequest": { "type": "object", "properties": { "html": { "type": "string", "minLength": 1, "maxLength": 2000000 }, "width": { "type": "integer", "minimum": 50, "maximum": 2000 }, "maxHeight": { "type": "integer", "minimum": 50, "maximum": 20000 } }, "required": [ "html" ], "additionalProperties": false }, "ContentAddImageResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 }, "aspectRatio": { "type": "string" }, "assetId": { "type": "string" } }, "required": [ "url", "width", "height", "aspectRatio", "assetId" ], "additionalProperties": false }, "ContentAddImageBatchResponse": { "type": "object", "properties": { "accepted": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "runId": { "type": "string" } }, "required": [ "accepted", "skipped" ], "additionalProperties": false }, "ContentAddImageRequest": { "oneOf": [ { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri" } }, "required": [ "imageUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 100 } }, "required": [ "imageUrls" ], "additionalProperties": false }, { "type": "object", "properties": { "uploadId": { "type": "string", "pattern": "^imgup_[A-Za-z0-9_-]{21}$" } }, "required": [ "uploadId" ], "additionalProperties": false } ] }, "ContentImageUploadCreateResponse": { "type": "object", "properties": { "uploadId": { "type": "string" }, "uploadUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "maxBytes": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "uploadId", "uploadUrl", "expiresAt", "maxBytes" ], "additionalProperties": false }, "ContentImageUploadCreateRequest": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file name, for example logo.png. It names the converted file; the library description comes from the image caption." }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp", "image/avif", "image/tiff", "image/svg+xml" ], "description": "The file type: image/png, image/jpeg, image/gif, image/webp, image/avif, image/tiff or image/svg+xml. It sets the size cap (2 MB for SVG). The bytes decide what is converted: a declared type that differs is ignored, and bytes that are none of these formats are refused when the image is added." }, "size": { "type": "integer", "minimum": 1, "maximum": 20000000, "description": "The file size in bytes: at most 20,000,000 (2,097,152 for SVG)." } }, "required": [ "fileName", "contentType", "size" ], "additionalProperties": false }, "UsageGetResponse": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "key", "name" ], "additionalProperties": false }, "credits": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": [ "integer", "null" ] }, "reserved": { "type": "integer", "minimum": 0 } }, "required": [ "limit", "used", "remaining" ], "additionalProperties": false }, "emailSends": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": [ "integer", "null" ] }, "reserved": { "type": "integer", "minimum": 0 } }, "required": [ "limit", "used", "remaining" ], "additionalProperties": false }, "period": { "type": "object", "properties": { "start": { "type": [ "string", "null" ], "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "start", "end" ], "additionalProperties": false } }, "required": [ "plan", "credits", "emailSends", "period" ], "additionalProperties": false }, "IntegrationsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "braze", "brevo", "clerk", "customerio", "figma", "framer", "slack", "hubspot", "typeform", "klaviyo", "iterable", "postmark", "onesignal", "mailgun", "sendgrid", "mailjet", "mailchimp", "loops", "stripe", "stytch", "supabase", "workos", "shopify", "revenuecat", "notion" ] }, "name": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "data_in", "data_out" ] }, "connected": { "type": "boolean" }, "comingSoon": { "type": "boolean", "enum": [ true ] }, "inviteOnly": { "type": "boolean", "enum": [ true ] }, "paused": { "type": "boolean", "enum": [ true ] }, "installationCount": { "type": "integer", "minimum": 0 }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "capabilityId": { "type": "string", "minLength": 1 }, "isReady": { "type": "boolean" } }, "required": [ "capabilityId", "isReady" ], "additionalProperties": false } } }, "required": [ "provider", "name", "category", "connected" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "ApiKeysListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "keyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "keyPreview": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "brandId": { "type": "string", "minLength": 1 }, "permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "keyId", "name", "keyPreview", "createdAt", "status", "permissions" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "ApiKeysCreateResponse": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "key", "keyId", "message" ], "additionalProperties": false }, "ApiKeysCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "all", "contacts", "emails", "automations", "transactional", "domains", "sends", "audiences", "brands" ] }, "minItems": 1 }, "brandId": { "type": "string", "minLength": 1, "maxLength": 64 }, "replacesKeyId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "ApiKeysDeleteResponse": { "type": "object", "properties": { "keyId": { "type": "string", "minLength": 1 }, "deleted": { "type": "boolean" }, "revokedAt": { "type": "string", "format": "date-time" } }, "required": [ "keyId", "deleted" ], "additionalProperties": false }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" } }, "required": [ "status", "version" ], "additionalProperties": false }, "HelpResponse": { "type": "object", "additionalProperties": {} }, "ChatList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "Resume the chat with the chat-context read." }, "title": { "type": [ "string", "null" ] }, "firstUserPrompt": { "type": [ "string", "null" ], "description": "The opening prompt, cut at 80 characters." }, "lastAssistantPreview": { "type": [ "string", "null" ], "description": "Brew's latest reply, cut at 140 characters." }, "status": { "type": [ "string", "null" ], "enum": [ "idle", "streaming", "background_finalizing", "completed", "failed", "interrupted", "stopped", "persistence_failed", null ], "description": "`streaming` or `background_finalizing` while a run is still going; null before the first run." }, "origin": { "type": [ "string", "null" ], "enum": [ "slack", null ], "description": "The chat app the conversation started in; null for the Brew web app." }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "Opens the chat in the Brew app." } }, "required": [ "chatId", "title", "firstUserPrompt", "lastAssistantPreview", "status", "origin", "updatedAt", "url" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "NotificationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "notificationId": { "type": "string", "pattern": "^ntf_[0-9a-f]{20}$", "description": "`ntf_` + 20 hex characters: a one-way hash, stable for the row’s life." }, "type": { "type": "string", "enum": [ "chat_stream", "import_job", "brand_image_import", "validation_job", "email_sent", "email_scheduled", "preview_email", "brand_extracted", "domain_status", "domain_score_run", "api_key_created", "email_send_failed", "gradual_send_paused", "gradual_send_completed", "send_limit_reached", "automation_pause_window_closed", "send_review_rejected", "comment_mention", "comment_reply", "integration_attention" ] }, "status": { "type": "string", "enum": [ "uploading", "preparing", "processing", "finalizing", "streaming", "background_finalizing", "completed", "partial", "failed", "interrupted", "stopped", "persistence_failed" ] }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "progressPercent": { "type": "number", "description": "0-100 while work is running, where it reports progress." }, "url": { "type": "string", "description": "Where the bell opens it in the Brew app." }, "chatId": { "type": "string" }, "emailId": { "type": "string" }, "domainId": { "type": "string" }, "domainName": { "type": "string" }, "isPersonal": { "type": "boolean", "description": "Addressed to the caller alone: a comment mention or reply, shown only on a personal connection." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } }, "required": [ "notificationId", "type", "status", "title", "subtitle", "isPersonal", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "EmailCommentThreadList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "commentId": { "type": "string", "description": "`cmt_…`; the app opens it with `?commentId=`." }, "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "open" ] }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "element" ] }, "elementId": { "type": "string", "description": "The element the thread is pinned to (`elm_…`)." }, "nodeType": { "type": "string", "description": "What the element is: `button`, `image`, `heading`, …" } }, "required": [ "kind" ], "additionalProperties": false } ], "description": "Whether the thread is on the whole design or one element of it." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "userId", "name" ], "additionalProperties": false }, "description": "Who started, replied to, or was mentioned in the thread: the 12 most recent." }, "participantCount": { "type": "integer", "minimum": 0, "description": "How many people are in the thread; `participants` lists at most 12." }, "messageCount": { "type": "integer", "minimum": 0 }, "lastMessageAt": { "type": "string", "format": "date-time" }, "lastMessagePreview": { "type": "string", "description": "The latest message, shortened to 140 characters; mentions read as in `body`." }, "url": { "type": "string", "description": "Opens the thread on the design in the Brew app." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "description": "`cmm_…`" }, "author": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "userId", "name" ], "additionalProperties": false }, "body": { "type": "string", "description": "The message text. Each mention reads `@` + the name `mentions` gives; other `@` text is as typed." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "userId", "name" ], "additionalProperties": false } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "messageId", "author", "body", "mentions", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Only with messages: the thread's newest messages (or, after a `messagesCursor`, the next older ones) that fit the page's size budget, oldest first." }, "messagesCursor": { "type": [ "string", "null" ], "description": "Only with messages: pass it back with this thread's `commentId` to read its older messages; null when none remain." } }, "required": [ "commentId", "emailId", "status", "target", "participants", "participantCount", "messageCount", "lastMessageAt", "lastMessagePreview", "url" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } }, "parameters": {} }, "paths": { "/v1/emails": { "get": { "operationId": "listEmails", "tags": [ "Emails" ], "summary": "List email designs", "description": "Lists the brand’s designs, newest first on the `sortBy` timestamp, as `{ data, pagination }`. Each row carries `emailId`, the latest `emailVersionId`, `title`, `status`, `previewImage` (when captured), `updatedAt`, `group` (`{ groupId, groupName }` or `null` when Ungrouped) and its creator.\n\n**Use when** browsing designs or finding the `emailId` to send, edit or inspect. One design with its HTML or version history is `getEmail`.\n\n**Input** `status` (`generating`, `ready`, `failed`), `groupId` (`grp_…` or `ungrouped`), `sortBy` (`updatedAt` default, or `createdAt`) with an inclusive `from`/`to` ISO 8601 window on that timestamp, `limit` and `cursor`.\n\n**Returns** `200` with a page of `EmailSummary` rows and a `pagination` envelope (`cursor` is `null` on the last page). `createdBy` is the creator exactly as the Brew emails list shows it: a person’s name (`Former member` once they leave the brand), `API` or `MCP` for a credential with no person, or the two joined (`Name · MCP`); `createdByUserId` is that person’s stable user id. `createdBy` is absent when the creator cannot be named, with `createdByUserId` still present.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key, an invalid status or a reversed window.\n\n**See also** `getEmail`, `listEmailGroups`, `listTemplates` (the public gallery).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Only designs whose title contains this text (case-insensitive), or whose title, subject line, preview or visible text matches its words (full-text over each design’s first 16,384 characters; the other filters apply to the 1,024 best matches)." }, "required": false, "description": "Only designs whose title contains this text (case-insensitive), or whose title, subject line, preview or visible text matches its words (full-text over each design’s first 16,384 characters; the other filters apply to the 1,024 best matches).", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "generating", "ready", "failed" ], "description": "Only designs in this status (`generating`, `ready`, `failed`)." }, "required": false, "description": "Only designs in this status (`generating`, `ready`, `failed`).", "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Only designs in one group (`grp_…`, or `ungrouped`)." }, "required": false, "description": "Only designs in one group (`grp_…`, or `ungrouped`).", "name": "groupId", "in": "query" }, { "schema": { "type": "string", "enum": [ "updatedAt", "createdAt" ], "default": "updatedAt", "description": "The timestamp the page is ordered by, newest first, and that `from`/`to` bound. Defaults to `updatedAt`." }, "required": false, "description": "The timestamp the page is ordered by, newest first, and that `from`/`to` bound. Defaults to `updatedAt`.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on the `sortBy` timestamp (ISO 8601)." }, "required": false, "description": "Inclusive lower bound on the `sortBy` timestamp (ISO 8601).", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound on the `sortBy` timestamp (ISO 8601)." }, "required": false, "description": "Inclusive upper bound on the `sortBy` timestamp (ISO 8601).", "name": "to", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of email designs.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailsListResponse" }, "example": { "data": [ { "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Yc5Kz8Sq2Wn7Lp4Tm1RvX", "title": "Welcome Email", "status": "ready", "previewImage": "https://cdn.brew.new/p/V1StGXR8_Z5jdHi6B-myT.png", "updatedAt": "2026-04-08T12:34:56.789Z", "group": { "groupId": "grp_welcome", "groupName": "Welcome" } }, { "emailId": "H7sQm2Lx9cT4vBn1KpWzE", "emailVersionId": "Lw9Rn1Vc5KzSGm2Tq7Xp4", "title": "May product digest", "status": "ready", "updatedAt": "2026-04-07T09:00:00.000Z", "group": null } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" }, "post": { "operationId": "generateEmail", "tags": [ "Emails" ], "summary": "Generate an email design", "description": "Generates a new design through the Brew email agent. Designs are pure: no send state, no type. Sending happens later with `createSend`, or a `sendEmail` node in an automation references the returned `emailId` and `emailVersionId`. Usage-metered: the agent's actual token usage is billed.\n\n**Use when** you have a brief and want Brew to author on brand. For existing markup use `importEmail`; for a Figma frame use `importFigmaDesign`.\n\n**Input** `prompt`; optional `category` (steers the design treatment only: transactional categories get receipt or reset conventions, while delivery for those flows is a triggered automation on a transactional-purpose domain), `contentUrls`, `referenceEmailId`, `subjectLine` (the design-default inbox subject; `createSend` still takes a per-send `subject`), `lang` (the language of the copy, ISO 639-1; omit and Brew detects it from the finished body), and `groupId` (`grp_…` or `ungrouped`) or `groupName` (resolve or create), not both; omit to land Ungrouped. Supports `Idempotency-Key`.\n\n**Returns** `201 { emailId, emailVersionId, html, previewImage?, group, subjectLine? }` when a design was persisted, or `200 { response }` when the agent answered in prose without writing a design.\n\n**Errors** `404 REFERENCE_EMAIL_NOT_FOUND` for an unknown `referenceEmailId`; `404 EMAIL_GROUP_NOT_FOUND` for an unknown `groupId`; `422 BRAND_NOT_READY` while the brand is still extracting; `502 EMAIL_GENERATION_FAILED` when the agent could not produce a design; `409 EMAIL_RESULT_UNAVAILABLE` when the design was saved but its completed result could not be returned (read the saved `emailVersionId` from `error.details`; do not repeat generation); `402 INSUFFICIENT_CREDITS` on an empty balance.\n\n**See also** `editEmail`, `importEmail`, `createSend`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "Generation prompt plus optional source URLs / reference design. The brand comes from the credential (or the `X-Brand-Id` header on an organization-scoped one) and must not be passed in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGenerateRequest" }, "examples": { "basic": { "summary": "Generate a design from a prompt", "value": { "prompt": "Create a welcome email for new customers who joined Brew today." } }, "fromContent": { "summary": "Synthesize one email from up to 8 source URLs", "value": { "prompt": "Summarize this month’s product updates into a newsletter.", "contentUrls": [ "https://example.com/blog/product-launch" ] } } } } } }, "responses": { "200": { "description": "The agent answered in prose without writing a design (`{ response }`).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGenerateTextResponse" }, "example": { "response": "No email was generated." } } } }, "201": { "description": "A design was persisted. Usage-metered: the actual token usage of the email agent is charged (no fixed price, so no `X-Credit-Cost` header). `emailVersionId` pins the exact version for sends + automation `sendEmail` nodes; a step pinned to the latest version follows later edits and restores (see `restoreEmailVersion`).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGenerateGeneratedResponse" }, "example": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x", "html": "Welcome to Brew.", "previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png", "group": null } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`REFERENCE_EMAIL_NOT_FOUND`: The referenceEmailId names no design in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "referenceEmailNotFound": { "summary": "REFERENCE_EMAIL_NOT_FOUND", "value": { "error": { "code": "REFERENCE_EMAIL_NOT_FOUND", "type": "not_found", "message": "The referenceEmailId names no design in the brand.", "suggestion": "Check the referenceEmailId and retry with a valid email id.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`EMAIL_RESULT_UNAVAILABLE`: The email was saved, but its completed result could not be read for this response.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailResultUnavailable": { "summary": "EMAIL_RESULT_UNAVAILABLE", "value": { "error": { "code": "EMAIL_RESULT_UNAVAILABLE", "type": "conflict", "message": "The email was saved, but its completed result could not be read for this response.", "suggestion": "Read GET /v1/emails/{emailId}?include=html with emailVersionId set to the saved value from error.details. Do not repeat the generation or edit: it already committed.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "committed": true, "emailId": "K7mV9aL2qW4xP6tR8yU0n", "emailVersionId": "N8cX2mV5pL7qR9tW1yZ3a", "runId": "R6bN8kM2pV4xZ7qW9tY1s" } } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`BRAND_NOT_READY`: The brand is still extracting and cannot generate email yet.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotReady": { "summary": "BRAND_NOT_READY", "value": { "error": { "code": "BRAND_NOT_READY", "type": "invalid_request", "message": "The brand is still extracting and cannot generate email yet.", "suggestion": "Poll GET /v1/brands/{brandId} until it reports status: completed, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "502": { "description": "`EMAIL_GENERATION_FAILED`: The email agent could not produce a design for the prompt.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailGenerationFailed": { "summary": "EMAIL_GENERATION_FAILED", "value": { "error": { "code": "EMAIL_GENERATION_FAILED", "type": "internal_error", "message": "The email agent could not produce a design for the prompt.", "suggestion": "Retry the request. If it keeps failing, simplify or rephrase the prompt.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true } }, "/v1/emails/{emailId}": { "get": { "operationId": "getEmail", "tags": [ "Emails" ], "summary": "Get an email design", "description": "Reads one design as the bare `EmailDetail` row: `emailId`, the `emailVersionId` (the pin for `POST /v1/sends` and sendEmail nodes), `title`, `status`, `previewStatus`, `subjectLine`, `previewText`, `lang`, `previewImage`, `updatedAt`, `group` and `createdBy` / `createdByUserId` (the design’s creator, shared by every version), plus `errorMessage` when a generation failed.\n\n**Use when** inspecting a design before sending it, pinning a version, polling a generation you started, or pulling rendered HTML or version history.\n\n**Input** `emailId` in the path. By default the row is the current head; `emailVersionId` reads a saved version and `runId` (returned by a create or edit) reads the version that run produced; pass one or neither, never both. `include=html` adds the selected version’s rendered HTML once it is `ready`, `include=versions` the lean `{ version, emailVersionId }` history, `include=text` the visible body text a reader sees (merge tags kept; `textTruncated` past 20,000 characters), and `include=links` each link destination once with its first visible text and `count` (`linksTruncated` past 200); comma-separate any of them.\n\n**Returns** `200` with the row; the `include` fields are present only when requested. A run that never saved a version reads as `failed` with the reason, and the design keeps its last saved version.\n\n**Errors** `404 EMAIL_NOT_FOUND` for an unknown or cross-brand id; `404 EMAIL_VERSION_NOT_FOUND` for a version or run this design does not have; `409 EMAIL_RUN_AMBIGUOUS` when a legacy run matches more than one version (read it by `emailVersionId`); `503 SERVICE_UNAVAILABLE` when storage is briefly unreachable (retry the same read); `400 INVALID_REQUEST` for an unknown `include` token or both selectors.\n\n**See also** `listEmails`, `editEmail`, `createSend`, `restoreEmailVersion`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "schema": { "type": "string", "description": "Comma-separated expansions: `html` (rendered HTML of the selected version, once it is `ready`), `versions` (lean `{ version, emailVersionId }` history), `text` (the visible body text a reader sees), `links` (each link destination once, with its visible text and count).", "x-brew-include-tokens": [ "html", "versions", "text", "links" ] }, "required": false, "description": "Comma-separated expansions: `html` (rendered HTML of the selected version, once it is `ready`), `versions` (lean `{ version, emailVersionId }` history), `text` (the visible body text a reader sees), `links` (each link destination once, with its visible text and count).", "name": "include", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Read this saved version instead of the current head. Mutually exclusive with `runId`." }, "required": false, "description": "Read this saved version instead of the current head. Mutually exclusive with `runId`.", "name": "emailVersionId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Read the version one generation run produced — the `runId` a create or edit returned. Mutually exclusive with `emailVersionId`." }, "required": false, "description": "Read the version one generation run produced — the `runId` a create or edit returned. Mutually exclusive with `emailVersionId`.", "name": "runId", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The design row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDetail" }, "example": { "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Yc5Kz8Sq2Wn7Lp4Tm1RvX", "version": "latest", "title": "Welcome Email", "status": "ready", "previewStatus": "available", "subjectLine": "Welcome to Acme", "previewText": "Your first week, planned.", "previewImage": "https://cdn.brew.new/p/V1StGXR8_Z5jdHi6B-myT.png", "updatedAt": "2026-04-08T12:34:56.789Z", "group": { "groupId": "grp_welcome", "groupName": "Welcome" }, "versions": [ { "version": "latest", "emailVersionId": "Yc5Kz8Sq2Wn7Lp4Tm1RvX" }, { "version": 1, "emailVersionId": "Lw9Rn1Vc5KzSGm2Tq7Xp4" } ] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).\n\n`EMAIL_VERSION_NOT_FOUND`: The design has no version with that id.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailVersionNotFound": { "summary": "EMAIL_VERSION_NOT_FOUND", "value": { "error": { "code": "EMAIL_VERSION_NOT_FOUND", "type": "not_found", "message": "The design has no version with that id.", "suggestion": "List versions with GET /v1/emails/{emailId}?include=versions and retry with a valid emailVersionId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`EMAIL_RUN_AMBIGUOUS`: A legacy generation run matches more than one saved version of the design.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailRunAmbiguous": { "summary": "EMAIL_RUN_AMBIGUOUS", "value": { "error": { "code": "EMAIL_RUN_AMBIGUOUS", "type": "conflict", "message": "A legacy generation run matches more than one saved version of the design.", "suggestion": "List versions with GET /v1/emails/{emailId}?include=versions and read the one you want by emailVersionId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" }, "patch": { "operationId": "editEmail", "tags": [ "Emails" ], "summary": "Edit an email design", "description": "Updates a design: an AI edit (`prompt`), its envelope (`title`, `subjectLine`, `lang`, `groupId`), or both in one call. At least one of the five is required. A design renames and moves between groups here exactly like an audience, trigger, automation or group renames through its own PATCH.\n\n**Use when** changing an existing design: rewording or restyling it with a prompt, renaming it (a clone starts as `Copy of …`), setting the inbox subject the design carries by default, or filing it in another group.\n\n**Input** `prompt` runs the Brew email agent against the current latest version (or the `emailVersionId` pin, optionally grounded by `contentUrls`) and writes a new `version: \"latest\"` row on the same `emailId` (the previous head becomes a numeric historical version); usage-metered by actual token spend. `title` renames the design (its canvas name, 1 to 200 characters), `subjectLine` sets the default inbox subject, `lang` sets the language of the copy (kept from then on; Brew stops re-detecting it) and `groupId` moves it into an existing group (`null` = Ungrouped); any of them without `prompt` is ONE atomic in-place patch (no AI run, no new version, free). With `prompt`, the rename and move land first so the new version inherits them and the subject is applied to the new head. `emailVersionId` requires `prompt`.\n\n**Returns** `200` with the generated-email shape: the NEW head after a prompt edit, or the CURRENT head after an envelope patch (with its `title`, `subjectLine` and `group` after the patch); a text response when the agent answered in prose.\n\n**Automations** a prompt edit moves every automation `sendEmail` step pinned to the previous latest version onto the new one, in a new unpublished automation version (while a Brew agent is still building that automation, its in-progress draft is updated in place instead); the published version keeps its pin until the next publish. Steps pinned to an older version do not move. An envelope patch writes no version and moves nothing.\n\n**Errors** `404 EMAIL_NOT_FOUND`, `EMAIL_VERSION_NOT_FOUND` (a pin that is not one of this design's versions), `EMAIL_GROUP_NOT_FOUND` (a `groupId` that is not one of this brand's groups); `409 EMAIL_IN_PROGRESS` while the design is still generating (or a concurrent edit moved the head between read and patch); `409 EMAIL_RESULT_UNAVAILABLE` when the edit was saved but its completed result could not be returned (read the saved `emailVersionId` from `error.details`; do not repeat the edit); `422 BRAND_NOT_READY` until the brand has finished extracting; `502 EMAIL_GENERATION_FAILED` when the agent run fails (retry later); `400 INVALID_REQUEST` for a body with none of the four fields, or `emailVersionId` without `prompt`.\n\n**See also** `cloneEmail` (name the copy with `title`), `restoreEmailVersion`, `listEmails`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "A natural-language `prompt` edit (optional `emailVersionId` source pin, optional `contentUrls`) and/or the envelope fields `title`, `subjectLine`, `lang` and `groupId` — at least one of the five. Identity lives on the path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEditRequest" }, "examples": { "aiEdit": { "summary": "AI prompt edit", "value": { "prompt": "Tighten the headline and replace the CTA copy with \"Get started today\"." } }, "subjectOnly": { "summary": "Set the subject line (no AI run, free)", "value": { "subjectLine": "Your September product roundup" } }, "rename": { "summary": "Rename the design (no AI run, free)", "value": { "title": "September product roundup" } }, "move": { "summary": "Move the design to Ungrouped (no AI run, free)", "value": { "groupId": null } }, "editWithSubject": { "summary": "AI edit + set the subject line", "value": { "prompt": "Swap the hero image for the fall campaign shot.", "subjectLine": "Fall arrivals are here" } } } } } }, "responses": { "200": { "description": "The edited design (a `prompt` edit writes a new `latest` version row and is USAGE-metered), the current head (a `title` / `subjectLine` envelope patch — no new version, free), or a text response if the agent returned prose instead of a design.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGenerateResponse" }, "examples": { "generated": { "summary": "Generated design", "value": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x", "html": "Welcome to Brew.", "previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png", "group": null } }, "textOnly": { "summary": "Text response", "value": { "response": "No email was generated." } } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).\n\n`EMAIL_VERSION_NOT_FOUND`: The design has no version with that id.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailVersionNotFound": { "summary": "EMAIL_VERSION_NOT_FOUND", "value": { "error": { "code": "EMAIL_VERSION_NOT_FOUND", "type": "not_found", "message": "The design has no version with that id.", "suggestion": "List versions with GET /v1/emails/{emailId}?include=versions and retry with a valid emailVersionId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`EMAIL_IN_PROGRESS`: The design is being generated and cannot be edited or cloned yet.\n\n`EMAIL_RESULT_UNAVAILABLE`: The email was saved, but its completed result could not be read for this response.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailInProgress": { "summary": "EMAIL_IN_PROGRESS", "value": { "error": { "code": "EMAIL_IN_PROGRESS", "type": "conflict", "message": "The design is being generated and cannot be edited or cloned yet.", "suggestion": "Poll GET /v1/emails/{emailId} until `status` is `ready`, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailResultUnavailable": { "summary": "EMAIL_RESULT_UNAVAILABLE", "value": { "error": { "code": "EMAIL_RESULT_UNAVAILABLE", "type": "conflict", "message": "The email was saved, but its completed result could not be read for this response.", "suggestion": "Read GET /v1/emails/{emailId}?include=html with emailVersionId set to the saved value from error.details. Do not repeat the generation or edit: it already committed.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "committed": true, "emailId": "K7mV9aL2qW4xP6tR8yU0n", "emailVersionId": "N8cX2mV5pL7qR9tW1yZ3a", "runId": "R6bN8kM2pV4xZ7qW9tY1s" } } } } } } } }, "422": { "description": "`BRAND_NOT_READY`: The brand is still extracting and cannot generate email yet.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotReady": { "summary": "BRAND_NOT_READY", "value": { "error": { "code": "BRAND_NOT_READY", "type": "invalid_request", "message": "The brand is still extracting and cannot generate email yet.", "suggestion": "Poll GET /v1/brands/{brandId} until it reports status: completed, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "502": { "description": "`EMAIL_GENERATION_FAILED`: The email agent could not produce a design for the prompt.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailGenerationFailed": { "summary": "EMAIL_GENERATION_FAILED", "value": { "error": { "code": "EMAIL_GENERATION_FAILED", "type": "internal_error", "message": "The email agent could not produce a design for the prompt.", "suggestion": "Retry the request. If it keeps failing, simplify or rephrase the prompt.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": true, "x-brew-rate-policy": "emails.edit" }, "delete": { "operationId": "deleteEmail", "tags": [ "Emails" ], "summary": "Delete an email design", "description": "Hard-deletes every version of the design. Idempotent — a miss resolves with `deleted: false` plus a `reason` instead of a 404: `already_deleted` (this id was hard-deleted earlier; `deletedAt` carries when) or `not_found` (no such design on this brand, including cross-brand ids). An `already_deleted` response means the design is gone — do not retry.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone — see `reason`).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailsDeleteResponse" }, "example": { "emailId": "V1StGXR8_Z5jdHi6B-myT", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`EMAIL_IN_USE_BY_AUTOMATION`: A published automation sends this design, so it cannot be deleted.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailInUseByAutomation": { "summary": "EMAIL_IN_USE_BY_AUTOMATION", "value": { "error": { "code": "EMAIL_IN_USE_BY_AUTOMATION", "type": "conflict", "message": "A published automation sends this design, so it cannot be deleted.", "suggestion": "Unpublish the automation (or swap the design on its send step), then retry the delete.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/emails/import": { "post": { "operationId": "importEmail", "tags": [ "Emails" ], "summary": "Import an email", "description": "Converts existing markup into a new, fully editable Brew design. Source structure is preserved and every discoverable safe public resource is rehosted; when rehosting fails a validated public URL is kept with a warning, and private, malformed and blocked references are stripped. Free: a deterministic compiler with no model and no credits.\n\n**Use when** you already have HTML, MJML, React Email JSX or a saved `.eml` message. To author from a brief use `generateEmail`; for a Figma frame use `importFigmaDesign`.\n\n**Input** `content` (the raw source as a string) and `format`: `html` (a document or fragment), `mjml`, `jsx` (a module with a default-exported component or a bare `` element; static values, `PreviewProps` and local sub-components fold, anything executable is rejected with the offending line) or `eml` (the HTML body is imported, inline `cid:` images are rehosted, other attachments are dropped, and the Subject becomes the title). HTML, MJML and EML land as source-preserved designs with an editable projection; JSX lands as a native React Email design. Optional `baseUrl` resolves relative image paths; optional `title` and `subjectLine` (the design-default inbox subject; an EML Subject is the default); optional `groupId` (`grp_…` or `ungrouped`) or `groupName` (resolve or create), not both; omit to land Ungrouped. Limits: 5,000,000 UTF-8 bytes, 256 remote resources, 8 concurrent fetches, 10 MB per resource and 50 MB aggregate downloads.\n\n**Returns** `201 { emailId, emailVersionId, html, previewImage?, assetReport, group, subjectLine? }`. Each source element with content that a design could not keep is listed once in `assetReport.warnings` as `{ code: \"element_dropped\", location: \"markup\", host: \"\" }`: inline `svg`, `math` and `canvas`, and `button`, `select`, `textarea` or table `caption` holding text are left out of the editable projection (the original source keeps them); `audio`, `video`, `iframe`, `object` and `embed` are removed from both, with `audio`/`video` fallback content kept.\n\n**Errors** `422 EMAIL_IMPORT_FAILED` when the markup cannot be compiled into a design or its editable model is over the size budget (nothing is persisted); `404 EMAIL_GROUP_NOT_FOUND` for an unknown `groupId`; `413 PAYLOAD_TOO_LARGE` over the byte cap; `422 BRAND_NOT_READY` while the brand is still extracting.\n\n**See also** `generateEmail`, `importFigmaDesign`, `auditEmail`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailImportRequest" }, "examples": { "html": { "summary": "Import an HTML email", "value": { "format": "html", "title": "Spring sale", "content": "

Spring sale

20% off everything.

\"banner\"" } }, "mjml": { "summary": "Import MJML markup", "value": { "format": "mjml", "content": "Spring sale — 20% off" } }, "jsx": { "summary": "Import React-Email JSX", "value": { "format": "jsx", "content": "WelcomeThanks for joining." } }, "eml": { "summary": "Import a saved .eml message", "value": { "format": "eml", "content": "From: Brew \r\nTo: you@example.com\r\nSubject: Spring sale\r\nMIME-Version: 1.0\r\nContent-Type: text/html; charset=\"utf-8\"\r\n\r\n

Spring sale

20% off everything.

" } } } } } }, "responses": { "201": { "description": "The design was imported + persisted. Free — no model runs. `emailVersionId` pins the exact version for sends + automation nodes; a step pinned to the latest version follows later edits and restores.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailImportResponse" }, "example": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x", "html": "Welcome to Brew.", "previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png", "assetReport": { "discovered": 1, "rehosted": 1, "retained": 0, "stripped": 0, "warnings": [] }, "group": null } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE`: The request body exceeds the route cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadTooLarge": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "type": "invalid_request", "message": "The request body exceeds the route cap.", "suggestion": "Reduce the payload size and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`BRAND_NOT_READY`: The brand is still extracting and cannot generate email yet.\n\n`EMAIL_IMPORT_FAILED`: The supplied markup could not be imported as an email.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotReady": { "summary": "BRAND_NOT_READY", "value": { "error": { "code": "BRAND_NOT_READY", "type": "invalid_request", "message": "The brand is still extracting and cannot generate email yet.", "suggestion": "Poll GET /v1/brands/{brandId} until it reports status: completed, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailImportFailed": { "summary": "EMAIL_IMPORT_FAILED", "value": { "error": { "code": "EMAIL_IMPORT_FAILED", "type": "invalid_request", "message": "The supplied markup could not be imported as an email.", "suggestion": "Check that `content` is valid for the declared `format` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "content.transform" } }, "/v1/emails/figma": { "post": { "operationId": "importFigmaDesign", "tags": [ "Emails" ], "summary": "Import a Figma frame", "description": "Deterministically converts one selected Figma frame into a new editable Brew email design. No model runs and no credits are charged.\n\n`figmaUrl` must be a Figma frame link containing `node-id`. The API-key brand must already have Figma connected in Brew Integrations, and that connected account must be able to read the file.\n\nSet `format` to `jsx` (default) for React Email JSX or `html` for rendered email HTML. The requested representation is returned in `content`; the persisted design is identified by `emailId` and `emailVersionId`. Optional `groupId` (`grp_…` or `ungrouped`) or `groupName` (resolve-or-create) — not both; omit to land Ungrouped. Unknown `groupId` → `404 EMAIL_GROUP_NOT_FOUND`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FigmaToEmailRequest" }, "examples": { "jsx": { "summary": "Return React Email JSX", "value": { "figmaUrl": "https://www.figma.com/design/abc123/Launch-email?node-id=1-2", "title": "Launch email", "format": "jsx" } }, "html": { "summary": "Return rendered HTML", "value": { "figmaUrl": "https://www.figma.com/design/abc123/Launch-email?node-id=1-2", "format": "html" } } } } } }, "responses": { "201": { "description": "The converted design was persisted and the requested source representation is returned in `content`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FigmaToEmailResponse" }, "example": { "emailId": "dP4xLm9Nq2Rs7Tv1WbYzK", "emailVersionId": "Tv1WbYzKdP4xLm9Nq2Rs7", "title": "Launch email", "format": "jsx", "content": "Launch day", "warningCount": 0, "exportedNodeCount": 2, "previewImage": "https://cdn.brew.new/p/dP4xLm9Nq2Rs7Tv1WbYzK.png", "group": null } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`FIGMA_URL_INVALID`: The Figma link is not a frame link with a node-id.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "figmaUrlInvalid": { "summary": "FIGMA_URL_INVALID", "value": { "error": { "code": "FIGMA_URL_INVALID", "type": "invalid_request", "message": "The Figma link is not a frame link with a node-id.", "suggestion": "In Figma, select the email frame and copy its link. The URL must include a node-id.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`FIGMA_ACCESS_DENIED`: The connected Figma account cannot read the file or frame.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "figmaAccessDenied": { "summary": "FIGMA_ACCESS_DENIED", "value": { "error": { "code": "FIGMA_ACCESS_DENIED", "type": "authorization_error", "message": "The connected Figma account cannot read the file or frame.", "suggestion": "Grant the connected Figma account access to the file and selected frame, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).\n\n`FIGMA_FRAME_NOT_FOUND`: The file or frame no longer exists.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "figmaFrameNotFound": { "summary": "FIGMA_FRAME_NOT_FOUND", "value": { "error": { "code": "FIGMA_FRAME_NOT_FOUND", "type": "not_found", "message": "The file or frame no longer exists.", "suggestion": "Confirm the file and frame still exist, then copy a fresh frame link from Figma.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE`: The request body exceeds the route cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadTooLarge": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "type": "invalid_request", "message": "The request body exceeds the route cap.", "suggestion": "Reduce the payload size and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`BRAND_NOT_READY`: The brand is still extracting and cannot generate email yet.\n\n`FIGMA_CONVERSION_FAILED`: The frame could not be converted into an email design; `details.emailId` references the partial design.\n\n`FIGMA_NOT_CONNECTED`: No Figma account is connected to the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotReady": { "summary": "BRAND_NOT_READY", "value": { "error": { "code": "BRAND_NOT_READY", "type": "invalid_request", "message": "The brand is still extracting and cannot generate email yet.", "suggestion": "Poll GET /v1/brands/{brandId} until it reports status: completed, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "figmaConversionFailed": { "summary": "FIGMA_CONVERSION_FAILED", "value": { "error": { "code": "FIGMA_CONVERSION_FAILED", "type": "invalid_request", "message": "The frame could not be converted into an email design; `details.emailId` references the partial design.", "suggestion": "Confirm the frame is a self-contained email design, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "emailId": "V1StGXR8_Z5jdHi6B-myT" } } } }, "figmaNotConnected": { "summary": "FIGMA_NOT_CONNECTED", "value": { "error": { "code": "FIGMA_NOT_CONNECTED", "type": "invalid_request", "message": "No Figma account is connected to the brand.", "suggestion": "Connect Figma on the Integrations page, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`FIGMA_UNAVAILABLE`: Figma did not answer in time.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "figmaUnavailable": { "summary": "FIGMA_UNAVAILABLE", "value": { "error": { "code": "FIGMA_UNAVAILABLE", "type": "service_unavailable", "message": "Figma did not answer in time.", "suggestion": "Retry after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "content.transform" } }, "/v1/emails/{emailId}/clone": { "post": { "operationId": "cloneEmail", "tags": [ "Emails" ], "summary": "Clone an email design", "description": "Creates a NEW design by copying the persisted source snapshot exactly. This is a deterministic database fork: it does not invoke an AI agent, reinterpret markup, re-host assets, or regenerate the preview.\n\nOmit `emailVersionId` to clone the current latest row, or pass a version id from `GET /v1/emails/{emailId}?include=versions` to clone that exact historical snapshot. Optional `groupId` (`grp_…` or `ungrouped`) or `groupName` (resolve-or-create) — not both; omit to inherit the source group. Unknown `groupId` → `404 EMAIL_GROUP_NOT_FOUND`. The clone receives fresh design/version ids and the `title` you pass (else `Copy of …`) while JSX, rendered HTML, and the preview image remain identical; rename it any time with `PATCH /v1/emails/{emailId} { title }`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": false, "description": "Optional exact source-version pin. Omit the body or send an empty object to clone latest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCloneRequest" }, "examples": { "latest": { "summary": "Clone latest", "value": {} }, "named": { "summary": "Clone latest under a name", "value": { "title": "Welcome series: variant B" } }, "pinned": { "summary": "Clone an exact version", "value": { "emailVersionId": "Bp1Rv6Tk9Yc3Wn2Lm7QxZ" } } } } } }, "responses": { "201": { "description": "Exact clone created. The response carries the clone’s new ids plus the unchanged rendered HTML and preview.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGenerateGeneratedResponse" }, "example": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x", "html": "Welcome to Brew.", "previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png", "group": null } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).\n\n`EMAIL_VERSION_NOT_FOUND`: The design has no version with that id.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailVersionNotFound": { "summary": "EMAIL_VERSION_NOT_FOUND", "value": { "error": { "code": "EMAIL_VERSION_NOT_FOUND", "type": "not_found", "message": "The design has no version with that id.", "suggestion": "List versions with GET /v1/emails/{emailId}?include=versions and retry with a valid emailVersionId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`EMAIL_IN_PROGRESS`: The design is being generated and cannot be edited or cloned yet.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailInProgress": { "summary": "EMAIL_IN_PROGRESS", "value": { "error": { "code": "EMAIL_IN_PROGRESS", "type": "conflict", "message": "The design is being generated and cannot be edited or cloned yet.", "suggestion": "Poll GET /v1/emails/{emailId} until `status` is `ready`, then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`EMAIL_NOT_READY`: The design is still generating or failed to generate, so it cannot be sent or cloned.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailNotReady": { "summary": "EMAIL_NOT_READY", "value": { "error": { "code": "EMAIL_NOT_READY", "type": "invalid_request", "message": "The design is still generating or failed to generate, so it cannot be sent or cloned.", "suggestion": "Use a completed design, or wait for generation to finish.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/emails/{emailId}/restore": { "post": { "operationId": "restoreEmailVersion", "tags": [ "Emails" ], "summary": "Restore a historical version", "description": "Non-destructive restore: clones the numbered version into a NEW `latest` row (demoting the current head) and returns the same generated-email shape as an edit, including the fresh `emailVersionId`. Like a prompt edit, it moves every automation `sendEmail` step pinned to the previous latest version onto the new one, in a new unpublished automation version; the published version keeps its pin until the next publish, and steps pinned to an older version do not move. To keep a step on a design that will change, clone the email and pin the clone, and leave the clone unedited: a prompt edit or restore of the clone moves the step the same way, and a manual canvas edit changes the content of the pinned version in place, published automations included.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRestoreRequest" }, "example": { "emailVersionId": "Tv1WbYzKdP4xLm9Nq2Rs7" } } } }, "responses": { "200": { "description": "Restored — a new `latest` version row was written.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGenerateGeneratedResponse" }, "example": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "emailVersionId": "8g3m4pA2SmZOWV3ZQ7W5x", "html": "Welcome to Brew.", "previewImage": "https://storage.example.com/emails/2SmZOWV3ZQ7W5x6g3m4pA.png", "group": null } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).\n\n`EMAIL_VERSION_NOT_FOUND`: The design has no version with that id.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailVersionNotFound": { "summary": "EMAIL_VERSION_NOT_FOUND", "value": { "error": { "code": "EMAIL_VERSION_NOT_FOUND", "type": "not_found", "message": "The design has no version with that id.", "suggestion": "List versions with GET /v1/emails/{emailId}?include=versions and retry with a valid emailVersionId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/emails/{emailId}/export": { "post": { "operationId": "exportEmailDesign", "tags": [ "Emails" ], "summary": "Export a design to an ESP", "description": "Export a finished email DESIGN to a connected third-party ESP (Braze, Brevo, HubSpot, Klaviyo, Loops, Mailchimp, Mailjet, Iterable, Postmark, OneSignal, Mailgun, SendGrid) as a reusable TEMPLATE. This is NOT a Brew send — it creates a template in the destination platform and does NOT deliver to recipients, and is unrelated to Brew sending domains or audiences. The `provider` must already be connected for the brand (connect ESPs in the Brew app). The exported HTML is automatically made ESP-portable; Loops converts supported content to LMX and creates an editable campaign draft to review before sending. Brevo and Mailjet need `senderEmail` when the account has more than one active sender (with exactly one, it is selected automatically). Pass `dryRun: true` to validate the design, brand ownership, and ESP connection without creating a template. Free (no credits).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailExportRequest" }, "example": { "provider": "klaviyo", "templateName": "Welcome — Brew export" } } } }, "responses": { "200": { "description": "Dry run — the design + ESP connection were validated without creating a template.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailExportResponse" }, "example": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "provider": "klaviyo", "providerName": "Klaviyo", "templateName": "Welcome — Brew export", "dryRun": true } } } }, "201": { "description": "The design was exported to the ESP as a new template.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailExportResponse" }, "example": { "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "provider": "klaviyo", "providerName": "Klaviyo", "templateName": "Welcome — Brew export", "templateId": "Ab3Kd9", "dryRun": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INTEGRATION_NOT_CONNECTED`: The export target is not connected to this brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "integrationNotConnected": { "summary": "INTEGRATION_NOT_CONNECTED", "value": { "error": { "code": "INTEGRATION_NOT_CONNECTED", "type": "invalid_request", "message": "The export target is not connected to this brand.", "suggestion": "Connect the provider on the Integrations page, then retry the export.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`EXPORT_UNSUPPORTED`: The export target rejected a field value it does not support.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "exportUnsupported": { "summary": "EXPORT_UNSUPPORTED", "value": { "error": { "code": "EXPORT_UNSUPPORTED", "type": "invalid_request", "message": "The export target rejected a field value it does not support.", "suggestion": "Review the provider export fields and retry with a supported value.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "502": { "description": "`EXPORT_PROVIDER_ERROR`: The connected provider refused or failed the template export; the status mirrors the provider reply.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "exportProviderError": { "summary": "EXPORT_PROVIDER_ERROR", "value": { "error": { "code": "EXPORT_PROVIDER_ERROR", "type": "service_unavailable", "message": "The connected provider refused or failed the template export; the status mirrors the provider reply.", "suggestion": "Check the connection to the provider and retry the export.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/emails/audit": { "post": { "operationId": "auditEmail", "tags": [ "Emails" ], "summary": "Audit an email", "description": "Audits an email for production readiness in parallel: links, images, compliance, loaded size, client support, accessibility and judged copy, plus markup checks.\n\n**Use when** a design is about to ship, or to score imported HTML or JSX before a send. A saved design is addressed by `emailId` and rendered exactly as a send renders it.\n\n**Input** exactly one of `emailHtml`, `emailJsx` (React Email, rendered by Brew) or `emailId` (+ optional `emailVersionId`), each up to 5,000,000 UTF-8 bytes (the JSON body up to 6 MiB); optional `subject` and `previewText` (each up to 1,000 characters; an omitted subject is not judged, an omitted preview is extracted from the authored preheader, an explicit empty string stays empty); optional `sendingPurpose` (when omitted, the audit infers it from the content and reports it as `inferred`, or as defaulted to marketing when unsure).\n\n**Returns** `200` with a stable versioned `{ findings, checks, metrics, summary, completion }`: every check, up to 100 normalized findings (each with optional `evidence`: an HTTP status, the clients that drop a feature, or a judgment probability), exact totals. `completion.status: 'complete'` carries a 0 to 100 score and costs 5 credits (`X-Credit-Cost: 5`); `'partial'` (a required lane was unavailable) has `score: null`, never establishes readiness, costs 0 credits (`X-Credit-Cost: 0`) and releases the idempotency key so the same key can retry.\n\n**Errors** `429 RATE_LIMITED` with `Retry-After` when admission is exhausted: 6 requests per minute per credential or session and 20 per minute across the organization (shared by public API, MCP and agent calls), and at most 4 audits concurrently per organization and 16 globally; a capacity rejection never runs or charges the audit. `404 EMAIL_NOT_FOUND` or `EMAIL_VERSION_NOT_FOUND` when a stored design is named and does not exist; `422 CONTENT_OPERATION_FAILED` when the HTML cannot be processed.\n\n**See also** `previewEmailAcrossClients`, `createInboxPlacementTest`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAuditRequest" }, "example": { "emailHtml": "View accountUnsubscribe", "subject": "Your August account update", "previewText": "A quick look at what changed this month.", "sendingPurpose": "marketing" } } } }, "responses": { "200": { "description": "A complete or partial audit. Branch on `completion.status`; only `complete` carries a numeric score. A partial response is not cached under its idempotency key and may be retried with the same key.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "X-Credit-Cost": { "schema": { "type": "integer", "minimum": 0, "description": "Credits charged for this completed operation.", "example": 5 }, "required": true, "description": "Credits charged for this completed operation." }, "X-Credits-Remaining": { "schema": { "type": "integer", "minimum": 0, "description": "Credits remaining after this operation.", "example": 95 }, "required": true, "description": "Credits remaining after this operation." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAuditResponse" }, "example": { "schemaVersion": 1, "rulesetVersion": "2026-10-09.1", "auditId": "00000000-0000-4000-8000-000000000001", "contentHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "auditedAt": "2026-08-23T00:00:00.000Z", "expiresAt": "2026-08-23T00:15:00.000Z", "policy": { "purpose": "marketing", "source": "provided", "unsubscribe": "required" }, "summary": { "blockers": 0, "errors": 0, "warnings": 1, "info": 0, "total": 1 }, "checks": [ { "id": "preflight", "status": "issues", "durationMs": 0, "findingCount": 1 } ], "metrics": { "htmlBytes": 2134, "linkCount": 2, "imageCount": 0, "gifCount": 0, "loadedSize": { "status": "exact", "htmlBytes": 2134, "remoteAssetBytes": 0, "totalBytes": 2134, "assetCount": 0 } }, "findings": [ { "id": "copy.subject.long:subject", "ruleId": "copy.subject.long", "category": "copy", "severity": "warning", "impact": "advisory", "message": "The subject may truncate on smaller inboxes.", "remediation": "Shorten it while keeping the main benefit clear.", "sources": [ "preflight" ], "target": { "kind": "subject" } } ], "totalFindings": 1, "findingsTruncated": false, "completion": { "status": "complete", "readiness": "needs_review", "score": 97 } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).\n\n`EMAIL_VERSION_NOT_FOUND`: The design has no version with that id.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailVersionNotFound": { "summary": "EMAIL_VERSION_NOT_FOUND", "value": { "error": { "code": "EMAIL_VERSION_NOT_FOUND", "type": "not_found", "message": "The design has no version with that id.", "suggestion": "List versions with GET /v1/emails/{emailId}?include=versions and retry with a valid emailVersionId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE`: The request body exceeds the route cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadTooLarge": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "type": "invalid_request", "message": "The request body exceeds the route cap.", "suggestion": "Reduce the payload size and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 6 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 6, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "fail_closed", "x-brew-credited": true, "x-brew-rate-policy": "email.audit" } }, "/v1/emails/{emailId}/client-previews": { "post": { "operationId": "previewEmailAcrossClients", "tags": [ "Emails" ], "summary": "Preview across clients & devices", "description": "Starts a durable rendering job for the selected email version across real email clients, including Gmail, Outlook, Apple Mail, iOS, and dark-mode variants. Omit emailVersionId to pin the current version at admission.\n\nPass supported client IDs or send {} for the default spread. Returns previewId and per-client progress immediately. Read GET /v1/emails/client-previews/{previewId} to resume; polling never creates another provider test.\n\nReserves 10 credits at admission and settles once when useful output exists. If the job produces no usable image, the reservation is released. Failed clients include individual reasons and retryability; a partial result retains all successful full-size links.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailClientPreviewRequest" }, "examples": { "default": { "summary": "Popular default spread", "value": {} }, "specific": { "summary": "Target specific inboxes/devices", "value": { "clients": [ "gmailcom-lm_chrcurrent_win10", "outlook2021_win11_lm_dt", "iphone16_18" ] } } } } } }, "responses": { "200": { "description": "An existing matching rendering job, including terminal results when already complete.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewId": { "type": "string" }, "emailId": { "type": "string" }, "emailVersionId": { "type": "string", "description": "Portable version ID when present. previewId pins the saved snapshot." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ], "description": "The job: `queued` or `running` until every client settles, then `completed`, `partially_completed` (some screenshots failed) or `failed`." }, "previews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string", "enum": [ "gmail", "outlook", "apple", "yahoo", "other" ] }, "os": { "type": "string" }, "dark": { "type": "boolean" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "reason": { "type": "string", "enum": [ "pending", "upstream_unavailable", "unsupported_client", "render_failed", "rehost_failed", "expired", "submission_unknown", "authorization_changed", "snapshot_unavailable" ] }, "retryable": { "type": "boolean" } }, "required": [ "id", "label", "category", "os", "dark", "status", "imageUrl", "retryable" ], "additionalProperties": false } }, "pending": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "nextPollAfterMs": { "type": "integer", "minimum": 0 }, "credits": { "type": "object", "properties": { "cost": { "type": "number" }, "status": { "type": "string", "enum": [ "reserved", "settled", "released" ] } }, "required": [ "cost", "status" ], "additionalProperties": false } }, "required": [ "previewId", "emailId", "status", "previews", "pending", "createdAt", "expiresAt", "nextPollAfterMs", "credits" ], "additionalProperties": false } } } }, "202": { "description": "Accepted rendering job; poll the returned previewId after nextPollAfterMs.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailClientPreviewResponse" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "content.transform" } }, "/v1/emails/{emailId}/inbox-placement-tests": { "post": { "operationId": "createInboxPlacementTest", "tags": [ "Emails" ], "summary": "Run an inbox placement test", "description": "Test where the design’s latest version LANDS — inbox vs spam vs missing — across real mailbox providers (Gmail, Outlook, Yahoo, Apple, …). Brew provisions a Mailgun seed list and sends the email to the seed addresses through your REAL send pipeline on a VERIFIED sending `domainId`, so the result reflects that domain’s true deliverability plus SPF/DKIM/DMARC.\n\nReturns immediately with a `testId`, `status: \"running\"` and `phase: \"sending\"`. Results accrue over a few minutes — poll `GET /v1/emails/{emailId}/inbox-placement-tests/{testId}` until `status` is `completed`, `partially_completed` or `failed`.\n\nThis performs a real (small) send to the seeds IN ADDITION to the FIXED 10-credit test fee (`X-Credit-Cost: 10`), charged only on a 2xx. Requires a verified sending domain.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInboxPlacementRequest" }, "examples": { "default": { "summary": "Test a verified domain across all providers", "value": { "domainId": "k57e9m3q1w8r" } }, "targeted": { "summary": "Restrict to specific providers + a custom subject", "value": { "domainId": "k57e9m3q1w8r", "subject": "March newsletter", "providers": [ "gmail.com", "outlook.com", "yahoo.com" ] } } } } } }, "responses": { "202": { "description": "The test was created and the seed send is in flight. Poll the GET endpoint for results.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInboxPlacementTest" }, "example": { "testId": "ibp_2f1c9d8a-4e77-4b0e-9a1c-6d5e2f0b7c31", "emailId": "V1StGXR8_Z5jdHi6B-myT", "status": "running", "phase": "sending", "domainId": "k57e9m3q1w8r", "seedCount": 42, "results": null, "createdAt": "2026-07-13T17:00:06.675Z", "updatedAt": "2026-07-13T17:00:06.675Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.\n\n`SEND_QUOTA_EXCEEDED`: The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } }, "sendQuotaExceeded": { "summary": "SEND_QUOTA_EXCEEDED", "value": { "error": { "code": "SEND_QUOTA_EXCEEDED", "type": "payment_required", "message": "The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "suggestion": "Upgrade your plan for a higher monthly send volume, send to fewer recipients, or wait for the billing period to reset.", "docs": "https://docs.brew.new/api-reference/api/credits" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`DOMAIN_NOT_READY`: The domain is not verified for sending.\n\n`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).\n\n`EMAIL_NOT_READY`: The design is still generating or failed to generate, so it cannot be sent or cloned.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainNotReady": { "summary": "DOMAIN_NOT_READY", "value": { "error": { "code": "DOMAIN_NOT_READY", "type": "invalid_request", "message": "The domain is not verified for sending.", "suggestion": "Use a verified domain, or finish domain verification before sending.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotReady": { "summary": "EMAIL_NOT_READY", "value": { "error": { "code": "EMAIL_NOT_READY", "type": "invalid_request", "message": "The design is still generating or failed to generate, so it cannot be sent or cloned.", "suggestion": "Use a completed design, or wait for generation to finish.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "fail_closed", "x-brew-credited": true, "x-brew-rate-policy": "content.transform" }, "get": { "operationId": "listInboxPlacementTests", "tags": [ "Emails" ], "summary": "List inbox placement tests", "description": "Lists a design's recent inbox-placement (seed) tests, newest first, under `{ data, pagination }` as lean persisted snapshots: `testId`, `status`, subject and preview, `seedCount` and the `overall` placement bucket. Free; no provider poll.\n\n**Use when** comparing subject, preview and version variants side by side, or finding the `testId` to poll.\n\n**Input** `emailId` in the path; `limit` and `cursor`.\n\n**Returns** `200` with a page of lean test rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key.\n\n**See also** `getInboxPlacementTest`, `createInboxPlacementTest`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of the design's recent tests.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInboxPlacementTestList" }, "example": { "data": [ { "testId": "ibp_2f1c9d8a-4e77-4b0e-9a1c-6d5e2f0b7c31", "status": "completed", "domainId": "dom_7bq2x9k4m1p8c3z6", "subject": "Your first week, planned", "seedCount": 42, "overall": { "provider": "all", "total": 42, "inbox": 38, "spam": 3, "missing": 1, "pending": 0, "categories": { "inbox": 34, "promotions": 4, "spam": 3 } }, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:41:10.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } }, "/v1/emails/{emailId}/inbox-placement-tests/{testId}": { "get": { "operationId": "getInboxPlacementTest", "tags": [ "Emails" ], "summary": "Get inbox placement test results", "description": "Reads one inbox-placement (seed) test as the bare test resource. Free.\n\n**Use when** polling a test started with `createInboxPlacementTest`.\n\n**Input** `emailId` and `testId` in the path. While `status` is `running` (`phase` `sending`, then `collecting`) the read refreshes from the provider (re-poll about every 30 seconds until `status` is `completed`, `partially_completed` or `failed`).\n\n**Returns** `200` with, per provider, inbox, spam and missing tallies with folder or tab `categories` and actual `folders` (Gmail Promotions, Yahoo bulk, gmx spamverdacht), each provider's own SPF, DKIM and DMARC verdicts (`byProvider[].authentication`), Microsoft filter telemetry (`microsoftFilter`; an SCL of 5 or higher lands in Junk), `spoofingDetected`, `headers` (one-click unsubscribe, plain-text part), a `spamFilter` content verdict with the triggered rules, and `diagnosis[]` per-provider findings with concrete remediation.\n\n**Errors** `404 EMAIL_NOT_FOUND` when the design, or the test under it, is not in the brand.\n\n**See also** `listInboxPlacementTests`, `createInboxPlacementTest`, `getDomainHealth`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": true, "name": "testId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The test resource with its current placement.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInboxPlacementTest" }, "example": { "testId": "ibp_2f1c9d8a-4e77-4b0e-9a1c-6d5e2f0b7c31", "emailId": "V1StGXR8_Z5jdHi6B-myT", "status": "completed", "domainId": "k57e9m3q1w8r", "seedCount": 42, "results": { "overall": { "provider": "all", "total": 42, "inbox": 38, "spam": 3, "missing": 1, "pending": 0, "categories": { "inbox": 34, "promotions": 4, "spam": 3 } }, "byProvider": [ { "provider": "gmail.com", "total": 4, "inbox": 4, "spam": 0, "missing": 0, "pending": 0, "categories": { "inbox": 3, "promotions": 1 } } ], "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" }, "spamFilter": { "flagged": false, "score": -0.2, "threshold": 5, "rules": [ { "name": "DKIM_SIGNED", "score": 0.1, "description": "Message has a DKIM signature" } ] } }, "createdAt": "2026-07-13T17:00:06.675Z", "updatedAt": "2026-07-13T17:00:06.675Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } }, "/v1/emails/audits/{auditId}": { "get": { "operationId": "getEmailAudit", "tags": [ "Emails" ], "summary": "Read a saved email audit", "description": "Returns a bounded page of the normalized audit findings, including finding IDs, rule IDs, targets, remediation, and the audited content hash. Reading pages is free and never reruns the audit. Continue using pagination.cursor. Reports are retained for seven days; the report’s expiresAt is the separate audit-attestation expiry. Completion and coverage fields identify incomplete analysis or representative-only findings.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "auditId", "in": "path" }, { "schema": { "type": "string", "maxLength": 100 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Findings per page (1-50). Defaults to 10.", "example": 10 }, "required": false, "description": "Findings per page (1-50). Defaults to 10.", "name": "limit", "in": "query", "example": 10 }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "One page of saved findings.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "rulesetVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "auditId": { "type": "string", "format": "uuid" }, "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "auditedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "policy": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "marketing", "transactional", "unknown" ] }, "source": { "type": "string", "enum": [ "provided", "defaulted", "trusted_adapter", "inferred" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "unsubscribe": { "type": "string", "enum": [ "required", "not_required", "not_evaluated" ] } }, "required": [ "purpose", "source", "unsubscribe" ], "additionalProperties": false }, "summary": { "type": "object", "properties": { "blockers": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 }, "warnings": { "type": "integer", "minimum": 0 }, "info": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "blockers", "errors", "warnings", "info", "total" ], "additionalProperties": false }, "checks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "passed" ] }, "durationMs": { "type": "integer", "minimum": 0 }, "findingCount": { "type": "number", "enum": [ 0 ] } }, "required": [ "id", "status", "durationMs", "findingCount" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "issues" ] }, "durationMs": { "type": "integer", "minimum": 0 }, "findingCount": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "status", "durationMs", "findingCount" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "not_applicable" ] }, "reason": { "type": "string", "enum": [ "no_remote_links", "no_remote_images", "no_remote_assets", "missing_copy", "requires_sending_domain", "send_transport_owned", "requires_audience_context", "separate_deliverability_test", "transactional_purpose", "unknown_purpose" ] } }, "required": [ "id", "status", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "unavailable" ] }, "reason": { "type": "string", "enum": [ "timeout", "upstream", "invalid_response" ] }, "retryable": { "type": "boolean" }, "durationMs": { "type": "integer", "minimum": 0 } }, "required": [ "id", "status", "reason", "retryable", "durationMs" ], "additionalProperties": false } ] }, "maxItems": 32 }, "metrics": { "type": "object", "properties": { "htmlBytes": { "type": "integer", "minimum": 0 }, "linkCount": { "type": "integer", "minimum": 0 }, "imageCount": { "type": "integer", "minimum": 0 }, "gifCount": { "type": "integer", "minimum": 0 }, "loadedSize": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "exact" ] }, "htmlBytes": { "type": "integer", "minimum": 0 }, "remoteAssetBytes": { "type": "integer", "minimum": 0 }, "totalBytes": { "type": "integer", "minimum": 0 }, "assetCount": { "type": "integer", "minimum": 0 } }, "required": [ "status", "htmlBytes", "remoteAssetBytes", "totalBytes", "assetCount" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "lower_bound" ] }, "htmlBytes": { "type": "integer", "minimum": 0 }, "knownRemoteAssetBytes": { "type": "integer", "minimum": 0 }, "knownTotalBytes": { "type": "integer", "minimum": 0 }, "unknownAssetCount": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "status", "htmlBytes", "knownRemoteAssetBytes", "knownTotalBytes", "unknownAssetCount" ], "additionalProperties": false } ] } }, "required": [ "htmlBytes", "linkCount", "imageCount", "gifCount", "loadedSize" ], "additionalProperties": false }, "findings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "ruleId": { "type": "string", "minLength": 1, "maxLength": 128 }, "category": { "type": "string", "enum": [ "compliance", "links", "images", "accessibility", "compatibility", "copy", "size", "markup" ] }, "severity": { "type": "string", "enum": [ "blocker", "error", "warning", "info" ] }, "impact": { "type": "string", "enum": [ "block", "confirm", "advisory" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "remediation": { "type": "string", "minLength": 1, "maxLength": 1000 }, "occurrenceCount": { "type": "integer", "exclusiveMinimum": 0, "description": "Total occurrences of this RULE across the email, stamped on every representative finding of the rule so the total survives representative truncation. Reconcile by max per rule — summing across findings overcounts." }, "sources": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 16 }, "standards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "url": { "type": "string", "maxLength": 2048, "pattern": "^https?:\\/\\/" } }, "required": [ "id" ], "additionalProperties": false }, "maxItems": 8 }, "evidence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "http" ] }, "status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "failure": { "type": "string", "enum": [ "dns", "tls", "connect", "timeout", "private_host", "redirects" ] } }, "required": [ "kind", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "clients" ] }, "unsupported": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 24 } }, "required": [ "kind", "unsupported" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "judgment" ] }, "question": { "type": "string", "minLength": 1, "maxLength": 64 }, "probability": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "kind", "question", "probability" ], "additionalProperties": false } ] }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "subject" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "preview_text" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "index": { "type": "integer", "minimum": 0 }, "displayUrl": { "type": "string", "maxLength": 300 } }, "required": [ "kind", "index", "displayUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ] }, "index": { "type": "integer", "minimum": 0 }, "displayUrl": { "type": "string", "maxLength": 300 } }, "required": [ "kind", "index", "displayUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "element" ] }, "selector": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "kind", "selector" ], "additionalProperties": false } ] } }, "required": [ "id", "ruleId", "category", "severity", "impact", "message", "remediation", "sources", "target" ], "additionalProperties": false }, "maxItems": 100 }, "totalFindings": { "type": "integer", "minimum": 0 }, "findingsTruncated": { "type": "boolean" }, "completion": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete" ] }, "readiness": { "type": "string", "enum": [ "ready", "needs_review", "not_ready" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "status", "readiness", "score" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "partial" ] }, "readiness": { "type": "string", "enum": [ "unknown", "not_ready" ] }, "score": { "type": "null" } }, "required": [ "status", "readiness", "score" ], "additionalProperties": false } ] }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "returned": { "type": "number" }, "storedFindings": { "type": "number" } }, "required": [ "cursor", "hasMore", "returned", "storedFindings" ], "additionalProperties": false } }, "required": [ "schemaVersion", "rulesetVersion", "auditId", "contentHash", "auditedAt", "expiresAt", "policy", "summary", "checks", "metrics", "findings", "totalFindings", "findingsTruncated", "completion", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIT_NOT_FOUND`: No saved audit matches that id in this brand, or its seven day retention has expired.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "auditNotFound": { "summary": "AUDIT_NOT_FOUND", "value": { "error": { "code": "AUDIT_NOT_FOUND", "type": "not_found", "message": "No saved audit matches that id in this brand, or its seven day retention has expired.", "suggestion": "Use an auditId returned by POST /v1/emails/audit for this brand, or run a new audit.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } }, "/v1/emails/client-previews/{previewId}": { "get": { "operationId": "getEmailRendering", "tags": [ "Emails" ], "summary": "Read email rendering progress", "description": "Reads the existing rendering job and per-client results without submitting another provider test or charging again. Returns successful full-size image links, pending or failed clients with reasons and retryability, expiry, and credit reservation status. Poll the same previewId after nextPollAfterMs while the job is `queued` or `running`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": true, "name": "previewId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Rendering progress for the pinned email version and requested clients.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewId": { "type": "string" }, "emailId": { "type": "string" }, "emailVersionId": { "type": "string", "description": "Portable version ID when present. previewId pins the saved snapshot." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "failed" ], "description": "The job: `queued` or `running` until every client settles, then `completed`, `partially_completed` (some screenshots failed) or `failed`." }, "previews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string", "enum": [ "gmail", "outlook", "apple", "yahoo", "other" ] }, "os": { "type": "string" }, "dark": { "type": "boolean" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "reason": { "type": "string", "enum": [ "pending", "upstream_unavailable", "unsupported_client", "render_failed", "rehost_failed", "expired", "submission_unknown", "authorization_changed", "snapshot_unavailable" ] }, "retryable": { "type": "boolean" } }, "required": [ "id", "label", "category", "os", "dark", "status", "imageUrl", "retryable" ], "additionalProperties": false } }, "pending": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "nextPollAfterMs": { "type": "integer", "minimum": 0 }, "credits": { "type": "object", "properties": { "cost": { "type": "number" }, "status": { "type": "string", "enum": [ "reserved", "settled", "released" ] } }, "required": [ "cost", "status" ], "additionalProperties": false } }, "required": [ "previewId", "emailId", "status", "previews", "pending", "createdAt", "expiresAt", "nextPollAfterMs", "credits" ], "additionalProperties": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`PREVIEW_NOT_FOUND`: No rendering job matches that id in this brand, or its results have expired.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "previewNotFound": { "summary": "PREVIEW_NOT_FOUND", "value": { "error": { "code": "PREVIEW_NOT_FOUND", "type": "not_found", "message": "No rendering job matches that id in this brand, or its results have expired.", "suggestion": "Use the previewId returned by POST /v1/emails/{emailId}/client-previews, or start a new job.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } }, "/v1/canvas/sessions": { "post": { "operationId": "createCanvasSession", "tags": [ "Emails" ], "summary": "Create an authenticated email canvas embed session", "description": "Create a short-lived grant for exactly one group or email. Call from your backend after authenticating your user and authorizing the target. Credentials are returned once; response replay is disabled. API keys remain server-side.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "group" ] }, "groupId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type", "groupId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "emailId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type", "emailId" ] } ] }, "user": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "externalId", "name" ] }, "parentOrigin": { "type": "string", "maxLength": 2000 }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "read", "edit", "presence" ] }, "minItems": 1, "maxItems": 3, "default": [ "read", "edit", "presence" ] } }, "required": [ "target", "user", "parentOrigin" ] } } } }, "responses": { "201": { "description": "A scoped session and single-use bootstrap credential.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanvasSession" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "disabled", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/canvas/sessions/{sessionId}/refresh": { "post": { "operationId": "refreshCanvasSession", "tags": [ "Emails" ], "summary": "Refresh a canvas session", "description": "Issue a new bootstrap credential without changing the target or external user. Requires the original issuing authority. Response replay is disabled.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "sessionId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The same scoped session with a new bootstrap credential.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanvasSession" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "disabled", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/canvas/sessions/{sessionId}": { "delete": { "operationId": "revokeCanvasSession", "tags": [ "Emails" ], "summary": "Revoke a canvas session", "description": "Stop reads and writes through an existing session, including active subscriptions.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "sessionId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The session is revoked.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "enum": [ true ] } }, "required": [ "revoked" ] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/email-groups": { "get": { "operationId": "listEmailGroups", "tags": [ "Emails" ], "summary": "List email groups", "description": "Lists the brand’s email folders under `{ data, pagination }`. Named groups use `grp_*` ids; Ungrouped is always included as `{ groupId: \"ungrouped\", groupName: \"Ungrouped\" }`. `emailCount` is capped at 100. A named group a person created carries `createdByUserId` and, when they can be named, `createdBy` (their name or \"Former member\"); older and org-key groups have neither.\n\n**Use when** picking the `groupId` to file a design under or to filter `listEmails` by.\n\n**Input** `limit` and `cursor`.\n\n**Returns** `200` with a page of `EmailGroupSummary` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key.\n\n**See also** `getEmailGroup`, `createEmailGroup`, `listEmails` (`?groupId=`).", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of email groups.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupsListResponse" }, "example": { "data": [ { "groupId": "grp_welcome", "groupName": "Welcome", "emailCount": 3, "createdBy": "Sam Rivera", "createdByUserId": "user_2xK9mPq4Rt7Vw1Yb" }, { "groupId": "ungrouped", "groupName": "Ungrouped", "emailCount": 12 } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" }, "post": { "operationId": "createEmailGroup", "tags": [ "Emails" ], "summary": "Create an email group", "description": "Creates a named email folder. Returns `201` with `{ groupId, groupName, emailCount }`. Pass `emailIds` (up to 50) to move existing designs in, in the same transaction as the create; the response then adds `moved` and `notMoved` (`not_found`, `generating`, `not_movable`, `folder_full` or `retry`; resend `retry` ids in a follow-up `PATCH`). Reserved names (`Ungrouped` / `ungrouped` / `__ungrouped__`) are `400`. Duplicate names are `409 EMAIL_GROUP_NAME_CONFLICT`. Pass the returned `groupId` as `groupId` on create/import/clone.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupCreateRequest" }, "example": { "name": "Welcome", "emailIds": [ "V1StGXR8_Z5jdHi6B-myT", "qkE3pWv2xN9dLmR4tYbZ7" ] } } } }, "responses": { "201": { "description": "Created, with any designs moved in.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupWriteResponse" }, "example": { "groupId": "grp_welcome", "groupName": "Welcome", "emailCount": 2, "moved": 2, "notMoved": [] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "409": { "description": "`EMAIL_GROUP_NAME_CONFLICT`: A group with that name already exists in the brand.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailGroupNameConflict": { "summary": "EMAIL_GROUP_NAME_CONFLICT", "value": { "error": { "code": "EMAIL_GROUP_NAME_CONFLICT", "type": "conflict", "message": "A group with that name already exists in the brand.", "suggestion": "Pick a different name, or rename the existing group.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/email-groups/{groupId}": { "get": { "operationId": "getEmailGroup", "tags": [ "Emails" ], "summary": "Get an email group", "description": "Reads one email folder as the bare `EmailGroupSummary` (`groupId`, `groupName`, `emailCount`, plus `createdByUserId` when a person created it, and `createdBy` when they can be named).\n\n**Use when** confirming a group before filing designs under it, or reading the `ungrouped` catalog row.\n\n**Input** `groupId` in the path: a `grp_*` id or the literal `ungrouped`.\n\n**Returns** `200` with the row.\n\n**Errors** `404 EMAIL_GROUP_NOT_FOUND` for an unknown or cross-brand id; `400 INVALID_REQUEST` for a non-public Ungrouped sentinel.\n\n**See also** `listEmailGroups`, `updateEmailGroup`, `deleteEmailGroup`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Named group id (`grp_*`) returned by `POST /v1/email-groups` and listed by `GET /v1/email-groups`. Ungrouped is not a writable id.", "example": "grp_welcome" }, "required": true, "description": "Named group id (`grp_*`) returned by `POST /v1/email-groups` and listed by `GET /v1/email-groups`. Ungrouped is not a writable id.", "name": "groupId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The group row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupSummary" }, "example": { "groupId": "grp_welcome", "groupName": "Welcome", "emailCount": 3, "createdBy": "Sam Rivera", "createdByUserId": "user_2xK9mPq4Rt7Vw1Yb" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" }, "patch": { "operationId": "updateEmailGroup", "tags": [ "Emails" ], "summary": "Update an email group", "description": "Renames a named folder (`name`), moves existing designs into it (`emailIds`, up to 50, one request against the rate limit), or both, in one transaction. A move adds `moved` and `notMoved` (`not_found`, `generating`, `not_movable`, `folder_full` or `retry`; resend `retry` ids) to the response. Ungrouped is not a target (`400`). Unknown / cross-brand ids are `404`. Duplicate names are `409 EMAIL_GROUP_NAME_CONFLICT`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Named group id (`grp_*`) returned by `POST /v1/email-groups` and listed by `GET /v1/email-groups`. Ungrouped is not a writable id.", "example": "grp_welcome" }, "required": true, "description": "Named group id (`grp_*`) returned by `POST /v1/email-groups` and listed by `GET /v1/email-groups`. Ungrouped is not a writable id.", "name": "groupId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupPatchRequest" }, "example": { "name": "Welcome series" } } } }, "responses": { "200": { "description": "Updated.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupWriteResponse" }, "example": { "groupId": "grp_welcome", "groupName": "Welcome series", "emailCount": 3 } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "409": { "description": "`EMAIL_GROUP_NAME_CONFLICT`: A group with that name already exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailGroupNameConflict": { "summary": "EMAIL_GROUP_NAME_CONFLICT", "value": { "error": { "code": "EMAIL_GROUP_NAME_CONFLICT", "type": "conflict", "message": "A group with that name already exists in the brand.", "suggestion": "Pick a different name, or rename the existing group.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" }, "delete": { "operationId": "deleteEmailGroup", "tags": [ "Emails" ], "summary": "Delete an email group", "description": "Deletes a named folder. Member emails move to Ungrouped. Ungrouped cannot be deleted (`400`). Idempotent — an unknown / cross-brand id resolves with `{ deleted: false }`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Named group id (`grp_*`) returned by `POST /v1/email-groups` and listed by `GET /v1/email-groups`. Ungrouped is not a writable id.", "example": "grp_welcome" }, "required": true, "description": "Named group id (`grp_*`) returned by `POST /v1/email-groups` and listed by `GET /v1/email-groups`. Ungrouped is not a writable id.", "name": "groupId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupDeleteResponse" }, "example": { "groupId": "grp_welcome", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`EMAIL_GROUP_NOT_FOUND`: No email group with that id exists in the brand.\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailGroupNotFound": { "summary": "EMAIL_GROUP_NOT_FOUND", "value": { "error": { "code": "EMAIL_GROUP_NOT_FOUND", "type": "not_found", "message": "No email group with that id exists in the brand.", "suggestion": "List groups with GET /v1/email-groups.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "409": { "description": "`EMAIL_GROUP_NAME_CONFLICT`: A group with that name already exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailGroupNameConflict": { "summary": "EMAIL_GROUP_NAME_CONFLICT", "value": { "error": { "code": "EMAIL_GROUP_NAME_CONFLICT", "type": "conflict", "message": "A group with that name already exists in the brand.", "suggestion": "Pick a different name, or rename the existing group.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.edit" } }, "/v1/sends": { "get": { "operationId": "listSends", "tags": [ "Sends" ], "summary": "List sends", "description": "Lists sends, newest first, under `{ data, pagination }`. A send is the unit of delivery and analytics: one design delivered to a target through one domain. Rows carry the sender and subject snapshot, `status`, delivery accounting and, once delivered, lifetime `stats`.\n\n**Use when** auditing what a design was sent to, reading campaign performance, or joining an automation run to its deliveries (`listAutomationRuns`, then `?automationRunId=` here, then `getEventsAnalytics` with the same id).\n\n**Input** the default list is campaign sends: `emailId` narrows to one design; `status`, `messageClass` (`marketing` or `transactional`) and an inclusive `from`/`to` window on `updatedAt` filter it. A join filter (`automationId`, `automationRunId`, `audienceRunId` or `triggerInstanceId`) switches to the automation grain, one row per recipient; `kind=automation` is implied and per-recipient rows are never listed brand-wide. `limit` and `cursor` page (an opaque native cursor; a `triggerInstanceId` read merges the runs of one fire into a single bounded page).\n\n**Returns** `200` with a page of `Send` rows.\n\n**Errors** `404 AUTOMATION_RUN_NOT_FOUND` or `AUDIENCE_RUN_NOT_FOUND` when a join filter names a run outside the brand; `400 INVALID_REQUEST` for `kind=campaign` with a join filter, `emailId` with a join filter, `kind=automation` without one, or a malformed cursor.\n\n**See also** `getSend` (`?include=events`), `createSend`, `getEventsAnalytics`, `getAnalyticsOverview`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Campaign grain: only sends of this design." }, "required": false, "description": "Campaign grain: only sends of this design.", "name": "emailId", "in": "query" }, { "schema": { "type": "string", "enum": [ "campaign", "automation" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "automationId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "automationRunId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": false, "name": "audienceRunId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "triggerInstanceId", "in": "query" }, { "schema": { "type": "string", "enum": [ "scheduled", "queued", "running", "paused", "completed", "partially_completed", "failed", "canceled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "marketing", "transactional" ] }, "required": false, "name": "messageClass", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on `updatedAt` (ISO 8601)." }, "required": false, "description": "Inclusive lower bound on `updatedAt` (ISO 8601).", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound on `updatedAt` (ISO 8601)." }, "required": false, "description": "Inclusive upper bound on `updatedAt` (ISO 8601).", "name": "to", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of sends.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendsListResponse" }, "example": { "data": [ { "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc", "kind": "campaign", "messageClass": "marketing", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Yc5Kz8Sq2Wn7Lp4Tm1RvX", "status": "completed", "audienceId": "jn79k2x4apqz8mjm12ekz1kxdx87yceg", "audienceName": "Subscribers", "startedAt": "2026-04-08T12:00:05.000Z", "completedAt": "2026-04-08T12:34:56.000Z", "stats": { "sent": 1200, "delivered": 1180, "opened": 540, "clicked": 96, "bounced": 20, "complained": 1, "unsubscribed": 4 }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:34:56.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_RUN_NOT_FOUND`: No manual-audience run with that id exists in the brand.\n\n`AUTOMATION_RUN_NOT_FOUND`: No automation run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceRunNotFound": { "summary": "AUDIENCE_RUN_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_RUN_NOT_FOUND", "type": "not_found", "message": "No manual-audience run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/audience-runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "automationRunNotFound": { "summary": "AUTOMATION_RUN_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_RUN_NOT_FOUND", "type": "not_found", "message": "No automation run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "sends", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "sends.read" }, "post": { "operationId": "createSend", "tags": [ "Emails" ], "summary": "Send an email", "description": "Sends an email design. Polymorphic on `test`: a campaign send mints a new `Send` (the unit of delivery and analytics) and delivers to a saved audience or an inline list through a verified domain; `test: true` delivers one synchronous QA copy to a single address and writes no send row.\n\n**Use when** a design is ready to go out. For per-recipient event-driven delivery, publish an automation and fire its trigger (`fireTrigger`).\n\n**Input** Campaign (`test` omitted or `false`): `emailId` (optionally pinned to `emailVersionId`), a verified `domainId`, `subject`, and exactly one of `audienceId` (a saved audience, or `\"all\"` for every contact in the brand) or `to` (one address or an array of up to 50). Optional `from` (`{ email, name? }`, an address on the send domain), `previewText`, `replyTo`, `scheduledAt`, one delivery mode (`gradualSend`, or `smartSend: true` for Intelligent Send: each recipient with past opens or clicks gets it at the upcoming hour, within 24 hours, their own history makes them most likely to open, and the rest right away; it composes with `scheduledAt`), and `consent` provenance (`source`, optional `capturedAt`, `policyVersion`, `evidence`) for inline recipients that are not yet contacts: each is created as a subscribed contact carrying that record. An existing opt-out is never re-subscribed. Inline recipients face the same unsubscribe and suppression gate and per-recipient quota as audience sends.\n\nTest (`test: true`): `emailId`, `subject`, one `to` address, optional `emailVersionId`, `previewText`, `replyTo`, `domainId` (a verified org-owned domain; otherwise the Brew default sender, and an unverified or foreign domain is rejected, never downgraded), `from` (`{ email, name? }`, an address on that domain), `variables` (example values for `{{ var | fallback }}` merge tags; a value wins over the fallback) and `payload` (template data; nested JSON renders via Liquid as `trigger.*`); the subject carries a `[TEST]` prefix. A test reaches only the requester, a teammate with access to the brand, or an address on the requester’s own company domain or a verified sending domain of the brand; anyone else is `422 TEST_RECIPIENT_NOT_ALLOWED` (`details.recipients`). The same design can be sent unlimited times; every campaign call mints a new send.\n\n**Returns** campaign `202 { status: 'queued' | 'scheduled', sendId, scheduledAt?, warnings? }` (poll `getSend`; `warnings[]` carries one `CONSENT_RECORD_MISSING` per inline recipient that is a subscribed contact with no consent record, and one `RECIPIENTS_EXCLUDED` with the counts when unsubscribed, suppressed, undeliverable or permission-less recipients will be skipped); test `200 { status: 'completed', recipient }`.\n\n**Errors** `400 INVALID_REQUEST` (`param: subject`) when `subject` has a line break or runs over 1000 characters (993 on a test send, for the `[TEST]` prefix), judged on the text every recipient receives; `404 EMAIL_NOT_FOUND`, `DOMAIN_NOT_FOUND`, `AUDIENCE_NOT_FOUND` (a resource in another brand also surfaces as `404`); `422 EMAIL_NOT_READY`, `DOMAIN_NOT_READY`, `DOMAIN_PURPOSE_NOT_ALLOWED`, `LIQUID_RENDER_ERROR`, `TEST_RECIPIENT_NOT_ALLOWED`; `422 CONSENT_REQUIRED` when an inline marketing recipient has no contact record with marketing consent and no `consent` was supplied (`details.recipients`); `422 RECIPIENT_UNSUBSCRIBED` when an inline recipient is an existing contact who opted out (`details.recipients`, never re-subscribed); `422 NO_ELIGIBLE_RECIPIENTS` when an immediate send would reach nobody because every contact it targets is excluded (`details.eligibility` = `{ total, eligible, excluded: { unsubscribed, suppressed, invalidEmail, consentRequired? } }`, each address counted once; no send is created, while a scheduled send is accepted instead); `422 EMAIL_IMAGES_MISSING` when the email shows a cdn.brew.new image that does not exist (`details.missingImages[]`; a dead icon whose real file sits elsewhere in its pack is moved there instead when the key has `emails` access); `402 SEND_QUOTA_EXCEEDED` when the plan's monthly volume would be exceeded (no `Retry-After`).\n\n**See also** `listSends`, `cancelSend`, `fireTrigger`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" }, "examples": { "test": { "summary": "One-off test to a single address (sync 200)", "value": { "test": true, "emailId": "V1StGXR8_Z5jdHi6B-myT", "subject": "Welcome to Brew", "to": "qa@acme.com" } }, "testVerifiedDomain": { "summary": "Test from your verified domain with example merge-tag values", "value": { "test": true, "emailId": "V1StGXR8_Z5jdHi6B-myT", "subject": "Welcome {{ firstName | there }}", "to": "qa@acme.com", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "from": { "email": "vanessa@acme.com", "name": "Vanessa" }, "variables": { "firstName": "Sarah" } } }, "now": { "summary": "Send the latest version to an audience now", "value": { "emailId": "V1StGXR8_Z5jdHi6B-myT", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew", "audienceId": "jn79k2x4apqz8mjm12ekz1kxdx87yceg" } }, "scheduledPinned": { "summary": "Schedule a pinned version for later", "value": { "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Gm2Tq7Xp4Lw9Rn1Vc5KzS", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew", "previewText": "Get started in 2 minutes.", "audienceId": "jn79k2x4apqz8mjm12ekz1kxdx87yceg", "scheduledAt": "2099-01-01T00:00:00.000Z" } }, "intelligent": { "summary": "Intelligent Send: each contact at their likeliest hour within 24 hours", "value": { "emailId": "V1StGXR8_Z5jdHi6B-myT", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew", "audienceId": "jn79k2x4apqz8mjm12ekz1kxdx87yceg", "smartSend": true } }, "inline": { "summary": "Send to inline recipients", "value": { "emailId": "V1StGXR8_Z5jdHi6B-myT", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew", "to": [ "founder@acme.com", "design@acme.com" ] } } } } } }, "responses": { "200": { "description": "The TEST send (`test: true`) was delivered synchronously to the single recipient.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailTestResponse" }, "example": { "status": "completed", "recipient": "qa@acme.com" } } } }, "202": { "description": "The campaign send was accepted, queued or scheduled.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendsPostResponse" }, "example": { "status": "queued", "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`SEND_QUOTA_EXCEEDED`: The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "sendQuotaExceeded": { "summary": "SEND_QUOTA_EXCEEDED", "value": { "error": { "code": "SEND_QUOTA_EXCEEDED", "type": "payment_required", "message": "The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "suggestion": "Upgrade your plan for a higher monthly send volume, send to fewer recipients, or wait for the billing period to reset.", "docs": "https://docs.brew.new/api-reference/api/credits" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_NOT_FOUND`: No audience with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceNotFound": { "summary": "AUDIENCE_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_NOT_FOUND", "type": "not_found", "message": "No audience with that id exists in the brand.", "suggestion": "Use GET /v1/audiences to choose a saved audience, or send to explicit addresses.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE`: The request body exceeds the route cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadTooLarge": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "type": "invalid_request", "message": "The request body exceeds the route cap.", "suggestion": "Reduce the payload size and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`CONSENT_REQUIRED`: An inline marketing recipient has no contact record with marketing consent and the send carried no consent provenance; details.recipients lists the addresses.\n\n`DOMAIN_NOT_READY`: The domain is not verified for sending.\n\n`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).\n\n`EMAIL_IMAGES_MISSING`: The email shows an image on cdn.brew.new that does not exist, so it was not sent; `details.missingImages[]` lists each URL and the email it is in.\n\n`EMAIL_NOT_READY`: The design is still generating or failed to generate, so it cannot be sent or cloned.\n\n`LIQUID_RENDER_ERROR`: A Liquid template failed to parse or render.\n\n`NO_ELIGIBLE_RECIPIENTS`: Every contact the send targets is unsubscribed, suppressed or undeliverable (or there are none), so an immediate send would deliver nothing; `details.eligibility` carries the counts.\n\n`RECIPIENT_UNSUBSCRIBED`: An inline recipient is an existing contact who unsubscribed from marketing email; details.recipients lists the addresses and Brew never re-subscribes an opt-out.\n\n`TEST_RECIPIENT_NOT_ALLOWED`: A test email can reach only the requester, teammates with access to the brand, or addresses on the requester’s company domain or a verified sending domain of the brand; details.recipients lists the refused addresses.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "consentRequired": { "summary": "CONSENT_REQUIRED", "value": { "error": { "code": "CONSENT_REQUIRED", "type": "invalid_request", "message": "An inline marketing recipient has no contact record with marketing consent and the send carried no consent provenance; details.recipients lists the addresses.", "suggestion": "Create the contacts first with POST /v1/contacts carrying a consent record, or include consent provenance on the send to create them as subscribed contacts.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotReady": { "summary": "DOMAIN_NOT_READY", "value": { "error": { "code": "DOMAIN_NOT_READY", "type": "invalid_request", "message": "The domain is not verified for sending.", "suggestion": "Use a verified domain, or finish domain verification before sending.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailImagesMissing": { "summary": "EMAIL_IMAGES_MISSING", "value": { "error": { "code": "EMAIL_IMAGES_MISSING", "type": "invalid_request", "message": "The email shows an image on cdn.brew.new that does not exist, so it was not sent; `details.missingImages[]` lists each URL and the email it is in.", "suggestion": "Replace or remove each image listed in `details.missingImages` in the email, then send again.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "missingImages": [ { "emailId": "em_8b1f0c2a", "url": "https://cdn.brew.new/generated/b1/hero-16x9.png" } ] } } } }, "emailNotReady": { "summary": "EMAIL_NOT_READY", "value": { "error": { "code": "EMAIL_NOT_READY", "type": "invalid_request", "message": "The design is still generating or failed to generate, so it cannot be sent or cloned.", "suggestion": "Use a completed design, or wait for generation to finish.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "liquidRenderError": { "summary": "LIQUID_RENDER_ERROR", "value": { "error": { "code": "LIQUID_RENDER_ERROR", "type": "invalid_request", "message": "A Liquid template failed to parse or render.", "suggestion": "Fix the template syntax, or supply the payload data the template references. Strict-mode fires fail on any unresolved variable; | default: is the sanctioned fallback.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "noEligibleRecipients": { "summary": "NO_ELIGIBLE_RECIPIENTS", "value": { "error": { "code": "NO_ELIGIBLE_RECIPIENTS", "type": "invalid_request", "message": "Every contact the send targets is unsubscribed, suppressed or undeliverable (or there are none), so an immediate send would deliver nothing; `details.eligibility` carries the counts.", "suggestion": "Target an audience with subscribed, deliverable contacts, or schedule the send for a time when the audience will have them.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "recipientUnsubscribed": { "summary": "RECIPIENT_UNSUBSCRIBED", "value": { "error": { "code": "RECIPIENT_UNSUBSCRIBED", "type": "invalid_request", "message": "An inline recipient is an existing contact who unsubscribed from marketing email; details.recipients lists the addresses and Brew never re-subscribes an opt-out.", "suggestion": "Remove the unsubscribed addresses from the recipients; a contact re-subscribes only through their own action.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "testRecipientNotAllowed": { "summary": "TEST_RECIPIENT_NOT_ALLOWED", "value": { "error": { "code": "TEST_RECIPIENT_NOT_ALLOWED", "type": "invalid_request", "message": "A test email can reach only the requester, teammates with access to the brand, or addresses on the requester’s company domain or a verified sending domain of the brand; details.recipients lists the refused addresses.", "suggestion": "Send the test to yourself or a teammate, or verify your company domain under Domains. Use a campaign send for anyone else.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "sends", "x-brew-brand-scope": "brand", "x-brew-idempotency": "fail_closed", "x-brew-credited": false, "x-brew-rate-policy": "sends.write" } }, "/v1/sends/{sendId}": { "get": { "operationId": "getSend", "tags": [ "Sends" ], "summary": "Get a send", "description": "Reads one send (campaign or automation) as the bare `Send` row: identity and join keys, the sender and subject snapshot, `status`, `approvalState`, delivery accounting, gradual-send progress and lifetime `stats`.\n\n**Use when** polling a send accepted by `createSend`, or inspecting one automation delivery.\n\n**Input** `sendId` in the path; `include=events` attaches a bounded first page of the send’s analytics events (recipient, type, click URL).\n\n**Returns** `200` with the row; `events` is present only when requested.\n\n**Errors** `404 SEND_NOT_FOUND` for an unknown or cross-brand id; `400 INVALID_REQUEST` for an unknown `include` token.\n\n**See also** `listSends`, `cancelSend`, `pauseSend`, `resumeSend`, `getEventsAnalytics` (`?sendId=`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Send id returned by `POST /v1/sends`.", "example": "r4Kq8ZxL2mW7nT1vPb9Yc" }, "required": true, "description": "Send id returned by `POST /v1/sends`.", "name": "sendId", "in": "path" }, { "schema": { "type": "string", "description": "Expansions: `events` attaches a bounded first page of the send’s analytics events.", "x-brew-include-tokens": [ "events" ] }, "required": false, "description": "Expansions: `events` attaches a bounded first page of the send’s analytics events.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The send row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" }, "example": { "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc", "kind": "campaign", "messageClass": "marketing", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Yc5Kz8Sq2Wn7Lp4Tm1RvX", "status": "completed", "audienceId": "jn79k2x4apqz8mjm12ekz1kxdx87yceg", "audienceName": "Subscribers", "startedAt": "2026-04-08T12:00:05.000Z", "completedAt": "2026-04-08T12:34:56.000Z", "stats": { "sent": 1200, "delivered": 1180, "opened": 540, "clicked": 96, "bounced": 20, "complained": 1, "unsubscribed": 4 }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:34:56.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`SEND_NOT_FOUND`: No send with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "sendNotFound": { "summary": "SEND_NOT_FOUND", "value": { "error": { "code": "SEND_NOT_FOUND", "type": "not_found", "message": "No send with that id exists in the brand.", "suggestion": "Use the sendId returned by POST /v1/sends, or list sends with GET /v1/sends.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "sends", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "sends.read" } }, "/v1/sends/{sendId}/cancel": { "post": { "operationId": "cancelSend", "tags": [ "Emails" ], "summary": "Cancel a send", "description": "Cancels a scheduled or queued send before it goes out, or STOPS any in-flight campaign send. A campaign that is `running` or `paused` is canceled the same way the in-app Stop button does it: the remaining recipients are never delivered while already-sent ones stay sent (every shape re-checks liveness at regular points mid-flight — smart per time bucket, gradual and plain blast at bounded chunk intervals — so a small tail may still deliver after the cancel lands). Idempotent — a send already `canceled` returns `200`. A send already `completed`, `partially_completed` or `failed`, or a non-campaign (automation) send, returns `409 SEND_NOT_CANCELLABLE`. Brand-scoped: an unknown / cross-brand `sendId` is `404`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Send id returned by `POST /v1/sends`.", "example": "r4Kq8ZxL2mW7nT1vPb9Yc" }, "required": true, "description": "Send id returned by `POST /v1/sends`.", "name": "sendId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The send is canceled (or was already canceled).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCancelResponse" }, "example": { "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc", "status": "canceled" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`SEND_NOT_FOUND`: No send with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "sendNotFound": { "summary": "SEND_NOT_FOUND", "value": { "error": { "code": "SEND_NOT_FOUND", "type": "not_found", "message": "No send with that id exists in the brand.", "suggestion": "Use the sendId returned by POST /v1/sends, or list sends with GET /v1/sends.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`SEND_NOT_CANCELLABLE`: The send already finished, so there is nothing left to cancel.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "sendNotCancellable": { "summary": "SEND_NOT_CANCELLABLE", "value": { "error": { "code": "SEND_NOT_CANCELLABLE", "type": "conflict", "message": "The send already finished, so there is nothing left to cancel.", "suggestion": "Check the send status with GET /v1/sends/{sendId} before canceling.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "sends", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "sends.write" } }, "/v1/sends/{sendId}/pause": { "post": { "operationId": "pauseSend", "tags": [ "Emails" ], "summary": "Pause a gradual send", "description": "Manually pauses an in-flight GRADUAL (domain-warmup) send. The ramp stops before its next chunk and holds its current batch until `POST /v1/sends/{sendId}/resume` (or a cancel). A send its operator already paused returns the same 200 and changes nothing; any other send that is not a `running` gradual send (including one held at the plan limit or for its domain) returns `409 SEND_NOT_PAUSABLE`. Brand-scoped: an unknown / cross-brand `sendId` is `404`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Send id returned by `POST /v1/sends`.", "example": "r4Kq8ZxL2mW7nT1vPb9Yc" }, "required": true, "description": "Send id returned by `POST /v1/sends`.", "name": "sendId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The send is paused.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPauseResponse" }, "example": { "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc", "status": "paused" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`SEND_NOT_FOUND`: No send with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "sendNotFound": { "summary": "SEND_NOT_FOUND", "value": { "error": { "code": "SEND_NOT_FOUND", "type": "not_found", "message": "No send with that id exists in the brand.", "suggestion": "Use the sendId returned by POST /v1/sends, or list sends with GET /v1/sends.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`SEND_NOT_PAUSABLE`: Only a delivering gradual send can be paused.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "sendNotPausable": { "summary": "SEND_NOT_PAUSABLE", "value": { "error": { "code": "SEND_NOT_PAUSABLE", "type": "conflict", "message": "Only a delivering gradual send can be paused.", "suggestion": "Check the send status with GET /v1/sends/{sendId}.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "sends", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "sends.write" } }, "/v1/sends/{sendId}/resume": { "post": { "operationId": "resumeSend", "tags": [ "Emails" ], "summary": "Resume a paused gradual send", "description": "Resumes a manually paused GRADUAL send. The ramp picks the resume up at its next hold check (seconds after a short pause, up to an hour after a long one); the unsent tail is re-spread and later batches shift so missed intervals do not compress into a burst. A send held at the plan limit resumes on its own once the plan allowance is available; any other send returns `409 SEND_NOT_RESUMABLE`. Brand-scoped: an unknown / cross-brand `sendId` is `404`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Send id returned by `POST /v1/sends`.", "example": "r4Kq8ZxL2mW7nT1vPb9Yc" }, "required": true, "description": "Send id returned by `POST /v1/sends`.", "name": "sendId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The send is delivering again.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResumeResponse" }, "example": { "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc", "status": "running" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`SEND_NOT_FOUND`: No send with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "sendNotFound": { "summary": "SEND_NOT_FOUND", "value": { "error": { "code": "SEND_NOT_FOUND", "type": "not_found", "message": "No send with that id exists in the brand.", "suggestion": "Use the sendId returned by POST /v1/sends, or list sends with GET /v1/sends.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`SEND_NOT_RESUMABLE`: Only a manually paused gradual send can be resumed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "sendNotResumable": { "summary": "SEND_NOT_RESUMABLE", "value": { "error": { "code": "SEND_NOT_RESUMABLE", "type": "conflict", "message": "Only a manually paused gradual send can be resumed.", "suggestion": "Check the send status with GET /v1/sends/{sendId}.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "sends", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "sends.write" } }, "/v1/analytics/overview": { "get": { "operationId": "getAnalyticsOverview", "tags": [ "Analytics" ], "summary": "Brand overview (totals, rates, timeseries)", "description": "Windowed brand overview: the exact read behind the app's Analytics metric cards and chart (same per-recipient dedup and machine open and click exclusion), so API, MCP and page numbers always agree. Defaults to the last 7 days.\n\n**Use when** you need totals, rates and a time series for the brand or for one automation, design, audience, source, domain or recipient set. For individual rows use `getEventsAnalytics`.\n\n**Input** Filters compose freely: `source` (csv of send sources), `automationId`, `emailId`, `audienceId` (csv, max 20), `triggerEventId` (csv, max 10, resolved to the automations they wire), `domain` (sending domain) and `recipient` (csv of recipient rules, same grammar as `getEventsAnalytics`). A single filter is answered from pre-aggregated rollups; any combination, and anything with `domain` or `recipient`, aggregates raw events instead: exact but capped, so watch `truncated` on wide windows.\n\n**Returns** `200 { totals, rates, buckets, granularity, timeZone, range, truncated }`; `truncated: true` means the window exceeded the scan budget, so narrow the range. Requires the `emails` scope.\n\n**Errors** `400 INVALID_REQUEST` for an inverted window or too many csv values.\n\n**See also** `getEventsAnalytics`, `getAutomationAnalytics`, `listSends` (campaign rows carry their own `stats`).", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "source", "in": "query", "required": false, "description": "CSV of send sources to include (e.g. `audience,api`; valid values: audience, api, automation_manual, automation_integration, automation_custom). Composes with every other filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "automationId", "in": "query", "required": false, "description": "CSV of automation ids (max 20) — a single id is still valid. Composes with every other filter; one id reads a pre-aggregated rollup partition, several take the raw-event path.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "emailId", "in": "query", "required": false, "description": "Scope to one email design. Composes with every other filter — a design used by several automations can be narrowed with `automationId`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "audienceId", "in": "query", "required": false, "description": "CSV of audience ids (max 20). Composes with every other filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "triggerEventId", "in": "query", "required": false, "description": "CSV of integration trigger-event ids (max 10), resolved to their wired automations. Composes with every other filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "domain", "in": "query", "required": false, "description": "Sending domain (`fromEmail` match). Has no rollup dimension, so requests carrying it are answered from raw events — check `truncated` on wide windows.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "recipient", "in": "query", "required": false, "description": "CSV of recipient rules (max 10) matching who RECEIVED the email — the SAME grammar and the same parameter name as `GET /v1/analytics/events`, so one filter string moves between the two and the totals here describe exactly the rows that feed lists. A full address matches exactly, `@domain` matches the domain, any other text matches as a substring; prefix `!` to exclude (e.g. `@clay.com,!ceo@clay.com`). Includes OR together; excludes always apply. Like `domain` this has no rollup dimension (stored rows aggregate ACROSS recipients), so requests carrying it are answered from raw events — check `truncated` on wide windows.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Brand-wide totals, rates, and a zero-filled timeseries for the window.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverviewResponse" }, "example": { "totals": { "sent": 5000, "delivered": 4920, "opened": 2110, "clicked": 540, "bounced": 80, "complained": 3, "unsubscribed": 12, "failed": 0, "suppressed": 14, "deliveryDelayed": 2 }, "rates": { "deliveryRate": 0.984, "openRate": 0.4289, "clickRate": 0.1098, "bounceRate": 0.016, "complaintRate": 0.0006, "unsubscribeRate": 0.0024 }, "buckets": [ { "at": "2026-04-08T00:00:00.000Z", "sent": 5000, "delivered": 4920, "deliveryDelayed": 2, "opened": 2110, "clicked": 540, "bounced": 80, "complained": 3, "failed": 0, "suppressed": 14, "unsubscribed": 12 } ], "granularity": "1d", "timeZone": "America/New_York", "range": { "from": "2026-04-01T12:34:56.789Z", "to": "2026-04-08T12:34:56.789Z" }, "truncated": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false } }, "/v1/analytics/automations": { "get": { "operationId": "getAutomationAnalytics", "tags": [ "Analytics" ], "summary": "Automation performance", "description": "Windowed per-automation performance + scoped `totals` + the resolved `range`. Defaults to the last 30 days. Reflects LIVE runs only (test runs never contribute). Totals include every matching automation independently from the displayed row `limit`. Narrow with the `automationId` filter; bound the window with `from` / `to`. Check `truncated`: when true, scan budgets clipped the requested window and the metrics are partial. Requires the `automations` scope.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "automationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Per-automation performance + totals for the window.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationAnalyticsResponse" }, "example": { "data": [ { "automationId": "Zq7Lm2Nx8Rt4Vw1KyPb6H", "name": "Welcome flow", "published": true, "triggerEventId": "user_signed_up", "runs": 1200, "completed": 1180, "failed": 5, "sent": 1180, "delivered": 1150, "opened": 690, "clicked": 210, "bounced": 18, "successRate": 0.983, "openRate": 0.6, "clickRate": 0.182, "clickThroughRate": 0.304, "lastRunAt": "2026-04-08T12:34:56.789Z", "lastRunStatus": "completed" } ], "totals": { "runs": 1200, "completed": 1180, "failed": 5, "sent": 1180, "delivered": 1150, "opened": 690, "clicked": 210, "bounced": 18 }, "range": { "from": "2026-03-09T12:34:56.789Z", "to": "2026-04-08T12:34:56.789Z" }, "truncated": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false } }, "/v1/analytics/events": { "get": { "operationId": "getEventsAnalytics", "tags": [ "Analytics" ], "summary": "Unified events feed", "description": "Read-only feed of the brand's analytics events (email, automation, trigger, inbound), newest first, over a `from`/`to` window that defaults to the last 7 days. Email rows carry the send behind them (`sendId`, `emailId`), so a page joins back to `GET /v1/sends/{sendId}`.\n\n**Use when** you need per-event or per-recipient detail. For windowed totals and rates use `getAnalyticsOverview`; for one send's events in one bounded page use `GET /v1/sends/{sendId}?include=events` (`getSend`).\n\n**Input** Equality filters: `eventType`, `sendId`, `emailId`, `automationId`, `messageClass` (`marketing` or `transactional`; absent stamps count as marketing). Run scope: `automationRunId` returns one run’s events across every domain (its lifecycle rows and the deliveries it produced), newest first and not windowed unless `from`/`to` are given; only `eventType` combines with it. Recipient rules `recipient` (csv, max 10): a full address matches exactly, `@domain` matches everyone on the domain, other text matches as a substring, a `!` prefix excludes (`recipient=@clay.com,!ceo@clay.com`); includes OR together, excludes always apply. Send facets `source` (csv), `audienceId` (csv, max 20), `domain` (sending domain), `triggerEventId` (csv, max 10, resolved to the automations they wire). Any facet or recipient rule narrows the feed to email events and adds `sendSource`, `sendContext` and `messageClass` to each row (plus `triggerProvider` and `triggerTitle` on triggered rows). Machine-classified opens and clicks (scanner detonation, Apple proxy prefetch) are excluded unless `includeMachineOpens=true` or `includeMachineClicks=true` (audit only).\n\n**Grouped counts** `groupBy` (one or two csv fields: `eventType`, `emailId`, `automationId`, `sendId`, `source`, `link`, `recipientDomain`, `unsubscribeReason`) and/or `bucket` (`day`, `week` or `month`, UTC, Monday weeks) count the email events the same filters list instead of returning them: `link` with `eventType=clicked` is clicks per link, `unsubscribeReason` counts an unsubscribe once per reason it gave. The count reads the newest 20,000 events; a busier window answers `truncated: true` with `coveredFrom` (narrow `from`/`to` or add `eventType`). Events, not unique recipients: `getAnalyticsOverview` `opened`/`clicked` count unique human recipients.\n\n**Returns** `200 { data: Event[], pagination: { limit, cursor, hasMore }, range }`; page with `cursor` until it is `null`. Rows carry the run join keys when stamped: `automationRunId`, `triggerInstanceId`, `audienceRunId` (plus `sendId`, `nodeId`). With `groupBy`/`bucket`: `200 { count, groups: [{ key, bucket?, count }], otherCount, range, truncated, coveredFrom? }`, the largest 200 groups first. Requires the `emails` scope.\n\n**Errors** `400 INVALID_REQUEST` for an inverted window, an unknown `eventType`, or more than 10 recipient rules or 20 audience ids; with `groupBy`/`bucket`, for an unknown or repeated field, more than two fields, a non-email `eventType`, `cursor` or `automationRunId` (`limit` is ignored).\n\n**See also** `getAnalyticsOverview`, `listSends`, `listAutomationRuns`.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "recipient", "in": "query", "required": false, "description": "CSV of recipient rules (max 10) matching who RECEIVED the email: a full address matches exactly, `@domain` matches the domain, any other text matches as a substring; prefix `!` to exclude (e.g. `@clay.com,!ceo@clay.com`). Includes OR together; excludes always apply. Narrows the feed to email events.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "automationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "sendId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "automationRunId", "in": "query", "required": false, "description": "One automation run’s events across every domain, newest first. Not windowed unless `from`/`to` are given; only `eventType` combines with it.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "messageClass", "in": "query", "required": false, "description": "Admission snapshot on the send behind the event (`marketing` | `transactional`). Same event object for both classes; absent stamps match as marketing. Narrows the feed to email events.", "schema": { "type": "string", "enum": [ "marketing", "transactional" ] } }, { "name": "source", "in": "query", "required": false, "description": "Send-object facet: CSV of send sources (valid values: audience, api, automation_manual, automation_integration, automation_custom). Narrows the feed to email events.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "audienceId", "in": "query", "required": false, "description": "Send-object facet: CSV of audience ids (max 20) — events from the audiences' sends. Narrows the feed to email events.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "emailId", "in": "query", "required": false, "description": "Send-object facet: one email design id. Narrows the feed to email events.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "domain", "in": "query", "required": false, "description": "Send-object facet: a sending domain (`fromEmail` match). Narrows the feed to email events.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "triggerEventId", "in": "query", "required": false, "description": "Send-object facet: CSV of integration trigger-event ids (max 10), resolved to their wired automations. Narrows the feed to email events.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "includeMachineClicks", "in": "query", "required": false, "description": "Machine/bot-classified `clicked` rows are excluded by default. Pass `true` to include the raw rows (they carry `machineGenerated: true` + a `clickBotReason`; audit/debug only).", "schema": { "type": "boolean" } }, { "name": "includeMachineOpens", "in": "query", "required": false, "description": "Machine/bot-classified `opened` rows (security-scanner pixel detonation, Apple-proxy prefetch) and still-classifying opens are excluded by default. Pass `true` to include the raw rows (they carry `machineGenerated` + an `openBotReason` and `openFetchSource`; audit/debug only).", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } }, { "name": "groupBy", "in": "query", "required": false, "description": "Count the email events these filters list per value of one or two comma-separated fields instead of returning them: eventType, emailId, automationId, sendId, source, link, recipientDomain, unsubscribeReason.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "x-brew-group-by-tokens": [ "eventType", "emailId", "automationId", "sendId", "source", "link", "recipientDomain", "unsubscribeReason" ] } }, { "name": "bucket", "in": "query", "required": false, "description": "Count the email events these filters list per UTC day, week (Monday start) or month; combines with `groupBy`.", "schema": { "type": "string", "enum": [ "day", "week", "month" ] } }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of unified analytics events, or grouped counts with `groupBy`/`bucket`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsAnalyticsSuccessResponse" }, "examples": { "page": { "summary": "Event page", "value": { "data": [ { "id": "evt_abc", "occurredAt": "2026-04-08T12:34:56.789Z", "domain": "email", "eventType": "opened", "recipientEmail": "jane@example.com", "sendId": "r4Kq8ZxL2mW7nT1vPb9Yc", "emailId": "qkE3pWv2xN9dLmR4tYbZ7", "emailName": "Spring Launch" } ], "pagination": { "limit": 50, "cursor": null, "hasMore": false }, "range": { "from": "2026-04-01T12:34:56.789Z", "to": "2026-04-08T12:34:56.789Z" } } }, "grouped": { "summary": "Clicks per link (groupBy=link, eventType=clicked)", "value": { "count": 412, "groups": [ { "key": { "link": "https://example.com/spring" }, "count": 301 }, { "key": { "link": "https://example.com/pricing" }, "count": 111 } ], "otherCount": 0, "range": { "from": "2026-04-01T12:34:56.789Z", "to": "2026-04-08T12:34:56.789Z" }, "truncated": false } } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false } }, "/v1/automations": { "post": { "operationId": "createAutomation", "tags": [ "Automations" ], "summary": "Create an automation", "description": "Deterministic create: the body carries the full graph (`{ name, triggerEventId?, nodes, connections }`).\n\n**Use when** you have minted every design a `sendEmail` node references (`generateEmail` first). Publish afterwards with `updateAutomation` (`{ \"published\": true }`), or launch a manual-audience automation with `runAutomation`.\n\n**Input** Trigger binding, exactly one: an EVENT automation passes `triggerEventId`; a MANUAL-AUDIENCE automation omits it and gives the trigger node `config: { \"mode\": \"manualAudience\", \"audienceId\": \"…\" }`. Typed conditions: every filter and condition-mode split uses a non-empty `conditions` array; each condition needs `field`, `type` (`string`, `number`, `date` or `bool`) and a canonical snake_case `operator`; unary operators omit `value`, comparisons require a type-correct scalar, a non-empty array, or an exact two-value `between` tuple (see `AutomationNode`). Every `sendEmail` node carries `emailId`, `emailVersionId` and `subject` (`previewText` is optional; the design's `` is the source of truth). `domainId` is optional at create time; publishing or running requires a verified one from `listDomains`. There is no `messageClass` key: the delivery class derives from the sending domain's `sendingPurpose` (a transactional-purpose domain sends with no unsubscribe link and delivers to unsubscribed contacts), so pick the class by picking the domain. Node ids are stored as sent, except the two shapes `NODE_ID_REPLACED` reports. `dryRun: true` validates without persisting.\n\n**Returns** `201` with the bare `AutomationRow`; with `dryRun: true`, `200` with an `AutomationDryRunReport` `{ valid, blockers[], warnings[], blockingIssues[], nodeCounts }` (`blockers[]` fail publish, `warnings[]` are advisory, `blockingIssues[]` lists per-node references the bound trigger or contact catalog cannot provide, each of which also fails publish; `valid` is false when any blocker or blocking issue is present).\n\n**Errors** `400 AUTOMATION_GRAPH_INVALID` with `details.issues[]` (`kind`, `nodeId`, `message` per problem); `404 TRIGGER_EVENT_NOT_FOUND` for an unknown `triggerEventId`.\n\n**See also** `updateAutomation`, `testAutomation`, `runAutomation`, `createTrigger`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationsPostRequest" }, "examples": { "deterministic": { "summary": "Create a trigger → sendEmail flow", "value": { "name": "Welcome flow", "description": "Welcome new signups", "triggerEventId": "user_signed_up", "nodes": [ { "id": "trg", "label": "On signup", "type": "trigger", "config": { "actionType": "trigger" } }, { "id": "send_welcome", "label": "Welcome", "type": "sendEmail", "config": { "actionType": "sendEmail", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Ux8nW3qL1mP9zRv6TkYcB", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew, {{firstName | there}}!", "previewText": "Thanks for signing up — get started in 2 minutes.", "fromName": "Brew", "replyTo": "support@example.com" } } ], "connections": [ { "from": "trg", "to": "send_welcome" } ] } }, "dryRun": { "summary": "Validate without persisting", "value": { "name": "preview", "triggerEventId": "user_signed_up", "nodes": [ { "id": "trg", "label": "On signup", "type": "trigger", "config": { "actionType": "trigger" } } ], "connections": [], "dryRun": true } } } } } }, "responses": { "200": { "description": "Dry-run result (returned only for `dryRun: true`; no writes). `valid` is false when any `blockers[]` entry or any `blockingIssues[]` entry is present. Create and update both return `blockingIssues[]` (possibly empty).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationDryRunReport" }, "example": { "valid": false, "blockers": [ { "severity": "error", "message": "Add at least one Send Email action" } ], "warnings": [], "blockingIssues": [], "nodeCounts": { "sendEmail": 0, "wait": 0, "filter": 0, "split": 0 } } } } }, "201": { "description": "Created. The bare automation row (draft, full graph).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRow" }, "example": { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "automationVersionId": "Rt4Vw1KyPb6HZq7Lm2Nx8", "triggerEventId": "user_signed_up", "name": "Welcome flow", "version": "latest", "published": false, "isLive": false, "nodes": [ { "id": "trg", "label": "On signup", "type": "trigger", "config": { "actionType": "trigger" } }, { "id": "send_welcome", "label": "Welcome", "type": "sendEmail", "config": { "actionType": "sendEmail", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Ux8nW3qL1mP9zRv6TkYcB", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew, {{firstName | there}}!", "previewText": "Thanks for signing up — get started in 2 minutes.", "fromName": "Brew", "replyTo": "support@example.com" } } ], "connections": [ { "from": "trg", "to": "send_welcome" } ], "emailIds": [ "V1StGXR8_Z5jdHi6B-myT" ], "createdBy": "Sam Rivera", "createdByUserId": "user_2xK9mPq4Rt7Vw1Yb", "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } } } }, "400": { "description": "`AUTOMATION_GRAPH_INVALID`: The nodes and connections do not form a valid graph; `details.issues[]` lists each problem with its `nodeId` and `kind`.\n\n`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationGraphInvalid": { "summary": "AUTOMATION_GRAPH_INVALID", "value": { "error": { "code": "AUTOMATION_GRAPH_INVALID", "type": "invalid_request", "message": "The nodes and connections do not form a valid graph; `details.issues[]` lists each problem with its `nodeId` and `kind`.", "suggestion": "Fix every issue reported in `details.issues` then resubmit.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "issues": [ { "kind": "missing_send_email_domain", "nodeId": "send-1", "message": "sendEmail node send-1 names no domainId." } ] } } } }, "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false }, "get": { "operationId": "listAutomations", "tags": [ "Automations" ], "summary": "List automations", "description": "Lists the brand’s automations under `{ data, pagination }` as LEAN rows: identity, `name`, `version`, `published`, `paused` and live-version state, `emailIds`, `updatedAt` and attribution; the graph is omitted.\n\n**Use when** browsing automations or finding the `automationId` to update, run or inspect.\n\n**Input** `limit` and `cursor` (an opaque native cursor).\n\n**Returns** `200` with a page of lean automation rows. `createdBy` / `createdByUserId` name the creator (`createdBy: \"API\"` when an organization API key made it, `Former member` once a person leaves the brand, absent when the creator cannot be named); while live, `publishedBy` / `publishedByUserId` name whoever published the live version.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or a malformed cursor.\n\n**See also** `getAutomation` (with `include=graph,versions`), `createAutomation`, `listAutomationRuns`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Only automations whose name matches these words (full-text), still newest first." }, "required": false, "description": "Only automations whose name matches these words (full-text), still newest first.", "name": "search", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of lean automation rows.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationsListResponse" }, "example": { "data": [ { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "automationVersionId": "Rt4Vw1KyPb6HZq7Lm2Nx8", "triggerEventId": "user_signed_up", "name": "Welcome flow", "version": "latest", "published": true, "emailIds": [ "V1StGXR8_Z5jdHi6B-myT" ], "updatedAt": "2026-04-08T12:00:00.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automations.read" } }, "/v1/automations/{automationId}": { "get": { "operationId": "getAutomation", "tags": [ "Automations" ], "summary": "Get an automation", "description": "Reads one automation as the bare row, LEAN by default (graph omitted), with `published`, `paused`, `pausedAt`, the live version it serves, its creator (`createdBy`, `createdByUserId`) and, while live, the live version’s publisher (`publishedBy`, `publishedByUserId`).\n\n**Use when** reading a flow before editing or publishing it, pinning `liveAutomationVersionId`, or inspecting its graph.\n\n**Input** `automationId` in the path; `include=graph` inlines `nodes` and `connections` and `include=versions` the lean `{ version, automationVersionId }` history (comma-separate both).\n\n**Returns** `200` with the row; the `include` fields are present only when requested.\n\n**Errors** `404 AUTOMATION_NOT_FOUND` for an unknown or cross-brand id; `400 INVALID_REQUEST` for an unknown `include` token.\n\n**See also** `listAutomations`, `updateAutomation`, `testAutomation`, `runAutomation`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "example": "M3nRk8LqW2xT5vBp9YcZd" }, "required": true, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "name": "automationId", "in": "path" }, { "schema": { "type": "string", "description": "Comma-separated expansions: `graph` inlines `nodes`/`connections`; `versions` inlines the lean version history.", "x-brew-include-tokens": [ "versions", "graph" ] }, "required": false, "description": "Comma-separated expansions: `graph` inlines `nodes`/`connections`; `versions` inlines the lean version history.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The automation row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRow" }, "example": { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "automationVersionId": "Rt4Vw1KyPb6HZq7Lm2Nx8", "triggerEventId": "user_signed_up", "name": "Welcome flow", "version": "latest", "published": true, "emailIds": [ "V1StGXR8_Z5jdHi6B-myT" ], "updatedAt": "2026-04-08T12:00:00.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUTOMATION_NOT_FOUND`: No automation with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationNotFound": { "summary": "AUTOMATION_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_NOT_FOUND", "type": "not_found", "message": "No automation with that id exists in the brand.", "suggestion": "List automations with GET /v1/automations.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automations.read" }, "patch": { "operationId": "updateAutomation", "tags": [ "Automations" ], "summary": "Update or publish an automation", "description": "One endpoint, two mutually exclusive modes: update the graph (a new `automationVersionId` on the same `automationId`) or change lifecycle state (`published`, `paused`). The modes cannot be combined: update first, then `PATCH { \"published\": true }`.\n\n**Use when** editing a graph or changing runtime state of an automation created with `createAutomation`. Manual-audience runs are controlled with `pauseAudienceRun`, `resumeAudienceRun` and `cancelAudienceRun`, not here.\n\n**Input** Update: one or more of `name`, `description`, `nodes`, `connections`, `triggerEventId`, under the same typed condition contract as create (explicit `type`, canonical snake_case `operator`, no `value` for unary operators, type-correct values elsewhere); `dryRun: true` validates without persisting. Node ids are stored as sent, so renamed nodes keep their new ids, except the two shapes `NODE_ID_REPLACED` reports. Lifecycle: `published: true` promotes the stored latest version live (optionally pin `automationVersionId`; the graph is validated first), `published: false` unpublishes, `paused: true` or `false` freezes or resumes future send steps (`stopInFlight` also stops runs already in progress).\n\n**Returns** the bare automation row, or with `dryRun: true` a `200 AutomationDryRunReport` `{ valid, blockers[], warnings[], blockingIssues[], nodeCounts }`: `blockingIssues[]` lists per-node references the effective trigger or contact catalog cannot provide, and publish refuses every one of them, fallback or not (`fatal` says what the reference would do: `true` for filter or split conditions and triple-brace `{{{ }}}` body tokens would break the run, `false` for subject, previewText, fromName, replyTo and double-brace body tags would render empty); `valid` is false when any blocker or blocking issue is present. Updating a LIVE automation saves a draft and does not go live: the previously published version keeps serving until you republish, `published` describes the returned row, `isLive`, `liveVersion` and `liveAutomationVersionId` describe the automation, and `warnings[]` carries `DRAFT_SAVED_NOT_LIVE`. Publishing an automation whose integration trigger has not received its event on the current connection (a Shopify topic with no webhook) still succeeds, and `warnings[]` carries `TRIGGER_EVENT_NOT_RECEIVED` saying what to set up.\n\n**Errors** `404 AUTOMATION_NOT_FOUND`, `AUTOMATION_VERSION_NOT_FOUND` (pin `liveAutomationVersionId`, a `versions[]` id, or a run row's `automationVersionId`), `TRIGGER_EVENT_NOT_FOUND`; `400 AUTOMATION_GRAPH_INVALID` (`details.issues[]`); `409 AUTOMATION_VERSION_CONFLICT` (re-read, reapply, retry); `422 PUBLISH_VALIDATION_FAILED` (`details.blockers[]`; a cdn.brew.new image a step would send that does not exist is a blocker, listed in `details.missingImages[]`, and a dead icon whose real file sits elsewhere in its pack is moved there instead when the key has `emails` access), `AUTOMATION_NOT_PUBLISHED` (nothing to unpublish; with `stopInFlight: true` on a draft, also no contacts in flight to stop), `AUTOMATION_NOT_PAUSABLE` (a manual-audience automation pauses through its runs).\n\n**See also** `createAutomation`, `testAutomation`, `runAutomation`, `listAutomationRuns`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "example": "M3nRk8LqW2xT5vBp9YcZd" }, "required": true, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "name": "automationId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationsUpdateRequest" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Welcome flow v2" } }, "graph": { "summary": "Replace the graph", "value": { "nodes": [ { "id": "trg", "label": "On signup", "type": "trigger", "config": { "actionType": "trigger" } }, { "id": "send_welcome", "label": "Welcome", "type": "sendEmail", "config": { "actionType": "sendEmail", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Ux8nW3qL1mP9zRv6TkYcB", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew, {{firstName | there}}!", "previewText": "Thanks for signing up — get started in 2 minutes.", "fromName": "Brew", "replyTo": "support@example.com" } } ], "connections": [ { "from": "trg", "to": "send_welcome" } ] } }, "dryRun": { "summary": "Validate a graph update without persisting", "value": { "nodes": [ { "id": "trg", "label": "On signup", "type": "trigger", "config": { "actionType": "trigger" } }, { "id": "send_welcome", "label": "Welcome", "type": "sendEmail", "config": { "actionType": "sendEmail", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Ux8nW3qL1mP9zRv6TkYcB", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew, {{firstName | there}}!", "previewText": "Thanks for signing up — get started in 2 minutes.", "fromName": "Brew", "replyTo": "support@example.com" } } ], "connections": [ { "from": "trg", "to": "send_welcome" } ], "dryRun": true } }, "publish": { "summary": "Publish (promote live)", "value": { "published": true } }, "publishVersion": { "summary": "Publish a pinned version", "value": { "published": true, "automationVersionId": "Kx9Pb2Nt6Wq4Ym8Lz1Rv3" } }, "unpublish": { "summary": "Unpublish", "value": { "published": false } } } } } }, "responses": { "200": { "description": "Updated / published / unpublished — the bare automation row. For `dryRun: true` update requests, an `AutomationDryRunReport` instead (no writes).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRow" }, { "$ref": "#/components/schemas/AutomationDryRunReport" } ] }, "examples": { "updated": { "summary": "Updated / published — the automation row", "value": { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "automationVersionId": "Rt4Vw1KyPb6HZq7Lm2Nx8", "triggerEventId": "user_signed_up", "name": "Welcome flow", "version": "latest", "published": false, "isLive": true, "liveVersion": 3, "liveAutomationVersionId": "Nt6Wq4Ym8Lz1Rv3Kx9Pb2", "nodes": [ { "id": "trg", "label": "On signup", "type": "trigger", "config": { "actionType": "trigger" } }, { "id": "send_welcome", "label": "Welcome", "type": "sendEmail", "config": { "actionType": "sendEmail", "emailId": "V1StGXR8_Z5jdHi6B-myT", "emailVersionId": "Ux8nW3qL1mP9zRv6TkYcB", "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "subject": "Welcome to Brew, {{firstName | there}}!", "previewText": "Thanks for signing up — get started in 2 minutes.", "fromName": "Brew", "replyTo": "support@example.com" } } ], "connections": [ { "from": "trg", "to": "send_welcome" } ], "emailIds": [ "V1StGXR8_Z5jdHi6B-myT" ], "createdBy": "Sam Rivera", "createdByUserId": "user_2xK9mPq4Rt7Vw1Yb", "publishedBy": "Sam Rivera", "publishedByUserId": "user_2xK9mPq4Rt7Vw1Yb", "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } }, "dryRun": { "summary": "Dry-run validation report (`dryRun: true`)", "value": { "valid": false, "blockers": [], "warnings": [], "blockingIssues": [ { "nodeId": "filter_a1b2", "nodeLabel": "Paid plan", "surface": "filterCondition", "variable": "plan", "reason": "Condition on \"plan\", which the trigger doesn't provide", "fatal": true, "hasFallback": false } ], "nodeCounts": { "sendEmail": 1, "wait": 0, "filter": 1, "split": 0 } } } } } } }, "400": { "description": "`AUTOMATION_GRAPH_INVALID`: The nodes and connections do not form a valid graph; `details.issues[]` lists each problem with its `nodeId` and `kind`.\n\n`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationGraphInvalid": { "summary": "AUTOMATION_GRAPH_INVALID", "value": { "error": { "code": "AUTOMATION_GRAPH_INVALID", "type": "invalid_request", "message": "The nodes and connections do not form a valid graph; `details.issues[]` lists each problem with its `nodeId` and `kind`.", "suggestion": "Fix every issue reported in `details.issues` then resubmit.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "issues": [ { "kind": "missing_send_email_domain", "nodeId": "send-1", "message": "sendEmail node send-1 names no domainId." } ] } } } }, "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUTOMATION_NOT_FOUND`: No automation with that id exists in the brand.\n\n`AUTOMATION_VERSION_NOT_FOUND`: The automation has no version with that id.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationNotFound": { "summary": "AUTOMATION_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_NOT_FOUND", "type": "not_found", "message": "No automation with that id exists in the brand.", "suggestion": "List automations with GET /v1/automations.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "automationVersionNotFound": { "summary": "AUTOMATION_VERSION_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_VERSION_NOT_FOUND", "type": "not_found", "message": "The automation has no version with that id.", "suggestion": "List versions with GET /v1/automations/{automationId}?include=versions.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`AUTOMATION_VERSION_CONFLICT`: The automation changed since the version you edited was read.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationVersionConflict": { "summary": "AUTOMATION_VERSION_CONFLICT", "value": { "error": { "code": "AUTOMATION_VERSION_CONFLICT", "type": "conflict", "message": "The automation changed since the version you edited was read.", "suggestion": "Read the latest automation version, reapply the intended changes, and retry the update.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`AUTOMATION_NOT_PAUSABLE`: The automation runs against a manual audience, so it is paused through its runs, not the automation.\n\n`AUTOMATION_NOT_PUBLISHED`: The automation is not live, so there is nothing to unpublish; with `stopInFlight: true` it also has no contacts in flight to stop.\n\n`PUBLISH_VALIDATION_FAILED`: The saved graph cannot go live; `details.blockers[]` lists what publish requires.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationNotPausable": { "summary": "AUTOMATION_NOT_PAUSABLE", "value": { "error": { "code": "AUTOMATION_NOT_PAUSABLE", "type": "invalid_request", "message": "The automation runs against a manual audience, so it is paused through its runs, not the automation.", "suggestion": "Use the audience-run control operations to pause or cancel an in-flight run.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "automationNotPublished": { "summary": "AUTOMATION_NOT_PUBLISHED", "value": { "error": { "code": "AUTOMATION_NOT_PUBLISHED", "type": "invalid_request", "message": "The automation is not live, so there is nothing to unpublish; with `stopInFlight: true` it also has no contacts in flight to stop.", "suggestion": "Check the live state with GET /v1/automations/{automationId}.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "publishValidationFailed": { "summary": "PUBLISH_VALIDATION_FAILED", "value": { "error": { "code": "PUBLISH_VALIDATION_FAILED", "type": "invalid_request", "message": "The saved graph cannot go live; `details.blockers[]` lists what publish requires.", "suggestion": "Fix every blocker reported in `details.blockers` then PATCH again with { published: true }.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "blockers": [ { "nodeId": "send-1", "nodeLabel": "Welcome email", "code": "domain_not_verified", "message": "The sending domain is not verified." } ] } } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automations.write" }, "delete": { "operationId": "deleteAutomation", "tags": [ "Automations" ], "summary": "Delete an automation", "description": "Cascade-deletes the automation: every version row, runs, and logs. Referenced email DESIGNS are shared resources and always survive. Idempotent — an unknown id resolves with `deleted: false`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "example": "M3nRk8LqW2xT5vBp9YcZd" }, "required": true, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "name": "automationId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationsDeleteResponse" }, "example": { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUTOMATION_NOT_FOUND`: No automation with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationNotFound": { "summary": "AUTOMATION_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_NOT_FOUND", "type": "not_found", "message": "No automation with that id exists in the brand.", "suggestion": "List automations with GET /v1/automations.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automations.write" } }, "/v1/automations/{automationId}/test": { "post": { "operationId": "testAutomation", "tags": [ "Automations" ], "summary": "Test an automation", "description": "Runs the saved automation END-TO-END through the real workflow in TEST mode — works on drafts and for both event and manual-audience automations; every node executes (filters/splits evaluate against `payload`, and `contact.` conditions read the test recipient’s contact unless `payload` supplies that field — a flat `contact.` key or a `contact` object — and the trigger’s contract keeps extra keys; wait nodes fast-forward). Pass `testRecipient` to DELIVER each send-email node’s email for real to that address (real subject/preview/sender name; verified configured sender domains are preserved, otherwise delivery uses the Brew test domain; customer addresses are never hit; the address must be the requester’s, a teammate’s on the brand, or on the requester’s company domain or a verified sending domain, else `422 TEST_RECIPIENT_NOT_ALLOWED`) — omit it for a silent dry-run with no mail. Test runs are excluded from live analytics rollups. Real test deliveries consume send usage; dry runs do not. Test payloads never update real contact records. Returns `202` with the started run id; follow per-node status via `GET /v1/automations/runs/{automationRunId}?include=logs`. Optional `scenario` controls simulate timed opens/clicks at engagement-filter nodes and force left/right percentage-split choices (waits use a virtual clock; controls stay separate from `payload`, and simulated events never enter live analytics or send quotas); the run row’s `testCoverage` reports visited nodes, traversed connections, evaluated or forced decisions, uncovered paths and simulation limitations. On a Brew-event (unsubscribe) trigger, omit payload to use Brew’s sample event; supplied fields replace the sample’s. The run never creates or edits a contact.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "example": "M3nRk8LqW2xT5vBp9YcZd" }, "required": true, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "name": "automationId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationTestRequest" }, "example": { "payload": { "email": "qa@example.com", "plan": "pro" }, "testRecipient": "qa@example.com" } } } }, "responses": { "202": { "description": "Test run started.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunStartedResponse" }, "example": { "automationRunIds": [ "jh7acthhe99pq4448xh83gn54x8eennb" ], "status": "test_started", "receivedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_PAYLOAD`: The test payload does not match the trigger’s payload schema.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidPayload": { "summary": "INVALID_PAYLOAD", "value": { "error": { "code": "INVALID_PAYLOAD", "type": "invalid_request", "message": "The test payload does not match the trigger’s payload schema.", "suggestion": "Send fields and types matching the trigger’s payloadSchema (see GET /v1/automations/triggers/{triggerEventId}).", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUTOMATION_NOT_FOUND`: No automation with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationNotFound": { "summary": "AUTOMATION_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_NOT_FOUND", "type": "not_found", "message": "No automation with that id exists in the brand.", "suggestion": "List automations with GET /v1/automations.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`TEST_RECIPIENT_NOT_ALLOWED`: A test email can reach only the requester, teammates with access to the brand, or addresses on the requester’s company domain or a verified sending domain of the brand; details.recipients lists the refused addresses.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "testRecipientNotAllowed": { "summary": "TEST_RECIPIENT_NOT_ALLOWED", "value": { "error": { "code": "TEST_RECIPIENT_NOT_ALLOWED", "type": "invalid_request", "message": "A test email can reach only the requester, teammates with access to the brand, or addresses on the requester’s company domain or a verified sending domain of the brand; details.recipients lists the refused addresses.", "suggestion": "Send the test to yourself or a teammate, or verify your company domain under Domains. Use a campaign send for anyone else.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "fail_closed", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/{automationId}/run": { "post": { "operationId": "runAutomation", "tags": [ "Automations" ], "summary": "Run a manual-audience automation", "description": "Launches a MANUAL-AUDIENCE automation against the audience bound to its trigger node. `dryRun: true` previews without sending; `scheduledAt` launches later, at most 1 year ahead. Percentage-based `gradualSend` delivers each send step in custom hour or calendar-day batches and supports manual pause/resume/cancel. `400` when `scheduledAt` is more than 1 year ahead, or a `gradualSend` plan exceeds 50,000 recipients, 30 batches, or 30 elapsed days. `422 EMAIL_IMAGES_MISSING` when a step would send a cdn.brew.new image that does not exist (`details.missingImages[]`). Returns `202` with the `audienceRunId`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "example": "M3nRk8LqW2xT5vBp9YcZd" }, "required": true, "description": "Automation id returned by `POST /v1/automations` and listed by `GET /v1/automations`.", "name": "automationId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunRequest" }, "example": { "scheduledAt": "2026-07-01T15:00:00.000Z" } } } }, "responses": { "200": { "description": "Dry-run preview (no run started). recipientCount is who will receive the email. warnings carries RECIPIENTS_EXCLUDED when unsubscribed, suppressed or undeliverable contacts are skipped.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunDryRunResponse" }, "example": { "dryRun": true, "automationId": "M3nRk8LqW2xT5vBp9YcZd", "audienceId": "jn7b3s7fapqz8mjm12ekz1kxdx87yceg", "audienceName": "Active trial users", "recipientCount": 12400, "sendNodeCount": 2 } } } }, "202": { "description": "Run launched (or scheduled). When org-level send approval is enabled the body additionally carries `approvalState: \"pending\"`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceAutomationRunStartedResponse" }, "example": { "audienceRunId": "ajh7acthhe99pq4448xh83gn54x8eennb", "automationId": "M3nRk8LqW2xT5vBp9YcZd", "status": "queued", "totalRecipients": 12400, "receivedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`SEND_QUOTA_EXCEEDED`: The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "sendQuotaExceeded": { "summary": "SEND_QUOTA_EXCEEDED", "value": { "error": { "code": "SEND_QUOTA_EXCEEDED", "type": "payment_required", "message": "The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "suggestion": "Upgrade your plan for a higher monthly send volume, send to fewer recipients, or wait for the billing period to reset.", "docs": "https://docs.brew.new/api-reference/api/credits" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_NOT_FOUND`: No audience with that id exists in the brand.\n\n`AUTOMATION_NOT_FOUND`: No automation with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceNotFound": { "summary": "AUDIENCE_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_NOT_FOUND", "type": "not_found", "message": "No audience with that id exists in the brand.", "suggestion": "Use GET /v1/audiences to choose a saved audience, or send to explicit addresses.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "automationNotFound": { "summary": "AUTOMATION_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_NOT_FOUND", "type": "not_found", "message": "No automation with that id exists in the brand.", "suggestion": "List automations with GET /v1/automations.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`RUN_IN_PROGRESS`: A manual-audience run is already in progress for this automation.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "runInProgress": { "summary": "RUN_IN_PROGRESS", "value": { "error": { "code": "RUN_IN_PROGRESS", "type": "conflict", "message": "A manual-audience run is already in progress for this automation.", "suggestion": "Wait for the in-progress run to finish (or cancel it) before running again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`EMAIL_IMAGES_MISSING`: The email shows an image on cdn.brew.new that does not exist, so it was not sent; `details.missingImages[]` lists each URL and the email it is in.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "emailImagesMissing": { "summary": "EMAIL_IMAGES_MISSING", "value": { "error": { "code": "EMAIL_IMAGES_MISSING", "type": "invalid_request", "message": "The email shows an image on cdn.brew.new that does not exist, so it was not sent; `details.missingImages[]` lists each URL and the email it is in.", "suggestion": "Replace or remove each image listed in `details.missingImages` in the email, then send again.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "missingImages": [ { "emailId": "em_8b1f0c2a", "url": "https://cdn.brew.new/generated/b1/hero-16x9.png" } ] } } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`RUN_START_FAILED`: The workflow engine could not start the run right now.\n\n`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "runStartFailed": { "summary": "RUN_START_FAILED", "value": { "error": { "code": "RUN_START_FAILED", "type": "service_unavailable", "message": "The workflow engine could not start the run right now.", "suggestion": "The workflow engine was momentarily busy; retry the run in a few seconds.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "fail_closed", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/audience-runs": { "get": { "operationId": "listAudienceRuns", "tags": [ "Automations" ], "summary": "List manual-audience runs", "description": "Lists manual-audience launches (each \"Run\" of a manual-audience automation), newest first, under `{ data, pagination }`: status, recipient totals and the per-node funnel.\n\n**Use when** watching launches started with `runAutomation` or auditing an automation’s manual sends.\n\n**Input** `automationId` and `status` to narrow; `limit` and `cursor`. The page is a slice of the newest 200 launches.\n\n**Returns** `200` with a page of `AudienceRun` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or status.\n\n**See also** `getAudienceRun`, `runAutomation`, `pauseAudienceRun`, `listAutomationRuns`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Only runs of this automation." }, "required": false, "description": "Only runs of this automation.", "name": "automationId", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "scheduled", "running", "paused", "completed", "failed", "canceled" ], "description": "Only runs in this status." }, "required": false, "description": "Only runs in this status.", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of manual-audience runs.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRunsListResponse" }, "example": { "data": [ { "audienceRunId": "arun_7acthhe99pq4448xh83gn54x8eennb", "automationId": "M3nRk8LqW2xT5vBp9YcZd", "audienceId": "jn7b3s7fapqz8mjm12ekz1kxdx87yceg", "audienceName": "Active trial users", "status": "completed", "totalRecipients": 12400, "sentCount": 12180, "failedCount": 0, "skippedCount": 220, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:41:10.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/automations/audience-runs/{audienceRunId}": { "get": { "operationId": "getAudienceRun", "tags": [ "Automations" ], "summary": "Get a manual-audience run", "description": "Reads one manual-audience launch as the bare `AudienceRun` row: `status`, `approvalState`, `pauseReason` while paused, recipient totals, per-node `nodeStats`. A gradual run carries its authored ramp; the batch progress of each send step is on its own send (`nodeStats[].sendId`).\n\n**Use when** polling a launch to completion or reading its funnel.\n\n**Input** `audienceRunId` in the path.\n\n**Returns** `200` with the row.\n\n**Errors** `404 AUDIENCE_RUN_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `listAudienceRuns`, `pauseAudienceRun`, `resumeAudienceRun`, `cancelAudienceRun`, `listSends` (`?audienceRunId=`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "example": "arun_7acthhe99pq4448xh83gn54x8eennb" }, "required": true, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "name": "audienceRunId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The manual-audience run.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRun" }, "example": { "audienceRunId": "arun_7acthhe99pq4448xh83gn54x8eennb", "automationId": "M3nRk8LqW2xT5vBp9YcZd", "audienceId": "jn7b3s7fapqz8mjm12ekz1kxdx87yceg", "audienceName": "Active trial users", "status": "completed", "totalRecipients": 12400, "sentCount": 12180, "failedCount": 0, "skippedCount": 220, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:41:10.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_RUN_NOT_FOUND`: No manual-audience run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceRunNotFound": { "summary": "AUDIENCE_RUN_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_RUN_NOT_FOUND", "type": "not_found", "message": "No manual-audience run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/audience-runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/automations/audience-runs/{audienceRunId}/pause": { "post": { "operationId": "pauseAudienceRun", "tags": [ "Automations" ], "summary": "Pause a manual-audience run", "description": "Holds a running manual-audience launch at its next step boundary. Delivery already in flight for the current step completes; nothing further goes out until `resumeAudienceRun`.\n\n**Use when** a launch must stop temporarily, for example to fix a downstream step.\n\n**Input** `audienceRunId` in the path; no body.\n\n**Returns** `200` with the run’s new `status` (`paused`).\n\n**Errors** `409 RUN_NOT_PAUSABLE` unless the run is running; `404 AUDIENCE_RUN_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `resumeAudienceRun`, `cancelAudienceRun`, `getAudienceRun`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "example": "arun_7acthhe99pq4448xh83gn54x8eennb" }, "required": true, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "name": "audienceRunId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The run's new status.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRunActionResponse" }, "example": { "audienceRunId": "arun_7acthhe99pq4448xh83gn54x8eennb", "status": "paused" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_RUN_NOT_FOUND`: No manual-audience run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceRunNotFound": { "summary": "AUDIENCE_RUN_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_RUN_NOT_FOUND", "type": "not_found", "message": "No manual-audience run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/audience-runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`RUN_NOT_PAUSABLE`: Only a running manual-audience run can be paused.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "runNotPausable": { "summary": "RUN_NOT_PAUSABLE", "value": { "error": { "code": "RUN_NOT_PAUSABLE", "type": "conflict", "message": "Only a running manual-audience run can be paused.", "suggestion": "Only a running run can be paused.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/audience-runs/{audienceRunId}/resume": { "post": { "operationId": "resumeAudienceRun", "tags": [ "Automations" ], "summary": "Resume a manual-audience run", "description": "Continues a paused launch, or restarts a FAILED one under a fresh workflow run: it picks up at the first send step that never delivered and skips every step the failed run finished, so nothing is resent. `resumedFrom` reports which case ran. A launch held at the plan limit (`pauseReason: plan_limit`) resumes on its own once the monthly send allowance has room.\n\n**Use when** a paused launch may continue, or a failed launch should finish its remaining steps.\n\n**Input** `audienceRunId` in the path; no body.\n\n**Returns** `200` with the run’s new `status` and `resumedFrom` (`paused` or `failed`).\n\n**Errors** `409 RUN_NOT_PAUSED` when a running run is resumed; `409 RUN_NOT_RESUMABLE` when the run is held at the plan limit, or a failed run has no undelivered send step or a send step delivered to only part of its segment; `409 RUN_IN_PROGRESS` when another run of the automation is active; `402 SEND_QUOTA_EXCEEDED` when resuming would exceed the monthly send limit; `422 INVALID_REQUEST` when a send step is no longer valid; `503 RUN_STOP_FAILED` / `RUN_START_FAILED` when the workflow engine could not stop the previous run or start the new one (retry); `404 AUDIENCE_RUN_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `pauseAudienceRun`, `cancelAudienceRun`, `getAudienceRun`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "example": "arun_7acthhe99pq4448xh83gn54x8eennb" }, "required": true, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "name": "audienceRunId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The run's new status and what it resumed from.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRunActionResponse" }, "example": { "audienceRunId": "arun_7acthhe99pq4448xh83gn54x8eennb", "status": "running", "resumedFrom": "paused" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`SEND_QUOTA_EXCEEDED`: The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "sendQuotaExceeded": { "summary": "SEND_QUOTA_EXCEEDED", "value": { "error": { "code": "SEND_QUOTA_EXCEEDED", "type": "payment_required", "message": "The send or manual-audience run would exceed the plan’s monthly email volume. A send must fit at launch and draws from the allowance chunk by chunk as it delivers; `reserved` is only the batch going out right now (`details` carries `used`, `reserved`, `remaining`, `limit`, `planKey` and `requested`, and `periodEnd` when known). The window resets with the billing period.", "suggestion": "Upgrade your plan for a higher monthly send volume, send to fewer recipients, or wait for the billing period to reset.", "docs": "https://docs.brew.new/api-reference/api/credits" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_RUN_NOT_FOUND`: No manual-audience run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceRunNotFound": { "summary": "AUDIENCE_RUN_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_RUN_NOT_FOUND", "type": "not_found", "message": "No manual-audience run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/audience-runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`RUN_IN_PROGRESS`: A manual-audience run is already in progress for this automation.\n\n`RUN_NOT_PAUSED`: Only a paused manual-audience run can be resumed.\n\n`RUN_NOT_RESUMABLE`: The run cannot be resumed: a failed run needs an undelivered send step, and a run held at the plan limit resumes on its own.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "runInProgress": { "summary": "RUN_IN_PROGRESS", "value": { "error": { "code": "RUN_IN_PROGRESS", "type": "conflict", "message": "A manual-audience run is already in progress for this automation.", "suggestion": "Wait for the in-progress run to finish (or cancel it) before running again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "runNotPaused": { "summary": "RUN_NOT_PAUSED", "value": { "error": { "code": "RUN_NOT_PAUSED", "type": "conflict", "message": "Only a paused manual-audience run can be resumed.", "suggestion": "Only a paused run can be resumed.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "runNotResumable": { "summary": "RUN_NOT_RESUMABLE", "value": { "error": { "code": "RUN_NOT_RESUMABLE", "type": "conflict", "message": "The run cannot be resumed: a failed run needs an undelivered send step, and a run held at the plan limit resumes on its own.", "suggestion": "For a failed run, start a new run for the remaining steps instead. A run held at the plan limit needs no call: it resumes once the monthly send allowance has room, or you can cancel it.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`RUN_START_FAILED`: The workflow engine could not start the run right now.\n\n`RUN_STOP_FAILED`: The previous run of this cohort could not be stopped.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "runStartFailed": { "summary": "RUN_START_FAILED", "value": { "error": { "code": "RUN_START_FAILED", "type": "service_unavailable", "message": "The workflow engine could not start the run right now.", "suggestion": "The workflow engine was momentarily busy; retry the run in a few seconds.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "runStopFailed": { "summary": "RUN_STOP_FAILED", "value": { "error": { "code": "RUN_STOP_FAILED", "type": "service_unavailable", "message": "The previous run of this cohort could not be stopped.", "suggestion": "Retry the resume in a few seconds, or cancel the previous run first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/audience-runs/{audienceRunId}/cancel": { "post": { "operationId": "cancelAudienceRun", "tags": [ "Automations" ], "summary": "Cancel a manual-audience run", "description": "Stops a manual-audience launch for good. Emails already sent are NOT recalled and a canceled run cannot be resumed.\n\n**Use when** a launch must not deliver its remaining steps.\n\n**Input** `audienceRunId` in the path; no body.\n\n**Returns** `200` with the run’s new `status` (`canceled`).\n\n**Errors** `409 RUN_NOT_CANCELLABLE` when the run already finished; `503 RUN_STOP_FAILED` when the workflow could not be stopped (retry); `404 AUDIENCE_RUN_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `pauseAudienceRun`, `resumeAudienceRun`, `cancelAutomationRun` (one event or test run).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "example": "arun_7acthhe99pq4448xh83gn54x8eennb" }, "required": true, "description": "The audience run id (from `POST /v1/automations/{automationId}/run` or `GET /v1/automations/audience-runs`), passed exactly as returned. A launch with an `Idempotency-Key` returns a longer id (`arun_` plus 64 hex characters).", "name": "audienceRunId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The run's new status.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRunActionResponse" }, "example": { "audienceRunId": "arun_7acthhe99pq4448xh83gn54x8eennb", "status": "canceled" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_RUN_NOT_FOUND`: No manual-audience run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceRunNotFound": { "summary": "AUDIENCE_RUN_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_RUN_NOT_FOUND", "type": "not_found", "message": "No manual-audience run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/audience-runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`RUN_NOT_CANCELLABLE`: The run already reached a terminal state.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "runNotCancellable": { "summary": "RUN_NOT_CANCELLABLE", "value": { "error": { "code": "RUN_NOT_CANCELLABLE", "type": "conflict", "message": "The run already reached a terminal state.", "suggestion": "The run has already finished and can no longer be canceled.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`RUN_STOP_FAILED`: The previous run of this cohort could not be stopped.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "runStopFailed": { "summary": "RUN_STOP_FAILED", "value": { "error": { "code": "RUN_STOP_FAILED", "type": "service_unavailable", "message": "The previous run of this cohort could not be stopped.", "suggestion": "Retry the resume in a few seconds, or cancel the previous run first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/runs": { "get": { "operationId": "listAutomationRuns", "tags": [ "Automations" ], "summary": "List automation runs", "description": "Lists recent runs (event executions and test runs), newest first, under `{ data, pagination }`. Rows are lean: identity, `automationVersionId`, `definitionHash`, `triggerInstanceId`, `mode`, `status` and timestamps.\n\n**Use when** auditing what an automation did, following a fire (`triggerInstanceId`) to its runs, or watching a test run.\n\n**Input** `automationId`, `triggerEventId`, `triggerInstanceId`, `recipientEmail` (one contact's run history, matched case-insensitively), `status`, `mode` (`live` | `test`), an inclusive `from`/`to` window on `startedAt`, `limit` and `cursor` (an opaque native cursor).\n\n**Returns** `200` with a page of run rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key, a reversed window or a malformed cursor.\n\n**See also** `getAutomationRun` (with `include=logs`), `cancelAutomationRun`, `listTriggerInstances`, `listSends`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "automationId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": false, "name": "triggerEventId", "in": "query" }, { "schema": { "type": "string", "minLength": 4, "maxLength": 64 }, "required": false, "name": "triggerInstanceId", "in": "query" }, { "schema": { "type": "string", "maxLength": 254, "pattern": "^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$", "description": "Only runs for this recipient, matched case-insensitively. Some older runs show a `recipientEmail` this filter does not match." }, "required": false, "description": "Only runs for this recipient, matched case-insensitively. Some older runs show a `recipientEmail` this filter does not match.", "name": "recipientEmail", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "live", "test" ] }, "required": false, "name": "mode", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" }, { "schema": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query", "description": "Page size (1-100). Defaults to 100.", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of runs.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunsListResponse" }, "example": { "data": [ { "automationRunId": "jh7acthhe99pq4448xh83gn54x8eennb", "automationId": "M3nRk8LqW2xT5vBp9YcZd", "automationVersionId": "Kx9Pb2Nt6Wq4Ym8Lz1Rv3", "definitionHash": "9c1f3a6e2b7d4c8f0a5e1b9d3c7f2a6e4b8d0c1f5a9e3b7d2c6f0a4e8b1d5c9f", "triggerInstanceId": "tin_4fZ2kQ9pLm7xR1tV8wYcD", "mode": "live", "status": "completed", "recipientEmail": "jane@example.com", "startedAt": "2026-04-08T12:34:56.789Z", "completedAt": "2026-04-08T12:35:10.120Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/automations/runs/{automationRunId}": { "get": { "operationId": "getAutomationRun", "tags": [ "Automations" ], "summary": "Get an automation run", "description": "Reads one run as the bare row: the automation and version it executed (`automationVersionId` is a valid publish pin, `definitionHash` the graph fingerprint), the fire behind it (`triggerInstanceId`), `mode`, `status` and timestamps.\n\n**Use when** debugging one contact’s journey or confirming a test run finished.\n\n**Input** `automationRunId` in the path; `include=logs` inlines the newest 100 execution log rows in `orderIndex` order and sets `logsTruncated` when older rows exist. Each node status change is its own row: a node that runs has a `running` row (no `completedAt`), then its terminal `completed` or `failed` row, or `skipped` when the run is canceled while it runs; a node a branch rules out has only a `skipped` row. A node’s outcome is its last row.\n\n**Returns** `200` with the row; `logs` is present only when requested.\n\n**Errors** `404 AUTOMATION_RUN_NOT_FOUND` for an unknown or cross-brand id; `400 INVALID_REQUEST` for an unknown `include` token.\n\n**See also** `listAutomationRuns`, `cancelAutomationRun`, `listSends` (`?automationRunId=`), `getEventsAnalytics` (`?automationRunId=`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "automationRunId", "in": "path" }, { "schema": { "type": "string", "description": "Expansions: `logs` inlines the newest 100 execution log rows, one per node status change (a node's outcome is its last row by `orderIndex`), and reports `logsTruncated`.", "x-brew-include-tokens": [ "logs" ] }, "required": false, "description": "Expansions: `logs` inlines the newest 100 execution log rows, one per node status change (a node's outcome is its last row by `orderIndex`), and reports `logsTruncated`.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The run row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRun" }, "example": { "automationRunId": "jh7acthhe99pq4448xh83gn54x8eennb", "automationId": "M3nRk8LqW2xT5vBp9YcZd", "automationVersionId": "Kx9Pb2Nt6Wq4Ym8Lz1Rv3", "definitionHash": "9c1f3a6e2b7d4c8f0a5e1b9d3c7f2a6e4b8d0c1f5a9e3b7d2c6f0a4e8b1d5c9f", "triggerInstanceId": "tin_4fZ2kQ9pLm7xR1tV8wYcD", "mode": "live", "status": "completed", "recipientEmail": "jane@example.com", "startedAt": "2026-04-08T12:34:56.789Z", "completedAt": "2026-04-08T12:35:10.120Z", "logs": [ { "automationRunId": "jh7acthhe99pq4448xh83gn54x8eennb", "nodeId": "node_send_welcome", "nodeName": "Send welcome", "nodeType": "sendEmail", "status": "completed", "orderIndex": 0, "startedAt": "2026-04-08T12:34:57.000Z", "completedAt": "2026-04-08T12:35:10.000Z" } ], "logsTruncated": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUTOMATION_RUN_NOT_FOUND`: No automation run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationRunNotFound": { "summary": "AUTOMATION_RUN_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_RUN_NOT_FOUND", "type": "not_found", "message": "No automation run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/automations/runs/{automationRunId}/cancel": { "post": { "operationId": "cancelAutomationRun", "tags": [ "Automations" ], "summary": "Cancel an automation run", "description": "Stops ONE run (an event execution or a test run). Marks it `canceled` (first-terminal-wins: a late completion from the dying workflow can never overwrite it), wakes a run parked on a wait node so it observes the cancel now, and terminates the durable workflow run so a step stuck retrying is freed too.\n\n**Use when** a contact must not receive the remaining steps of a journey that already started.\n\n**Input** `automationRunId` in the path; an optional `reason` for the audit trail. Nothing further is sent; emails already delivered are NOT recalled and a canceled run cannot be resumed.\n\n**Returns** `200` with the run’s new `status` and the `previousStatus` it held.\n\n**Errors** `409 RUN_NOT_CANCELLABLE` when the run already finished (`completed`, `failed` or `canceled`); `404 AUTOMATION_RUN_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `getAutomationRun`, `cancelAudienceRun` (manual-audience launches), `updateAutomation` (`paused` / `published`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "automationRunId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunCancelRequest" }, "example": { "reason": "Wrong segment — stopping before the second email." } } } }, "responses": { "200": { "description": "The run's new status plus the status it held before the cancel.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunCancelResponse" }, "example": { "automationRunId": "jh7acthhe99pq4448xh83gn54x8eennb", "status": "canceled", "previousStatus": "running" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUTOMATION_RUN_NOT_FOUND`: No automation run with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "automationRunNotFound": { "summary": "AUTOMATION_RUN_NOT_FOUND", "value": { "error": { "code": "AUTOMATION_RUN_NOT_FOUND", "type": "not_found", "message": "No automation run with that id exists in the brand.", "suggestion": "List runs with GET /v1/automations/runs.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`RUN_NOT_CANCELLABLE`: The run already reached a terminal state.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "runNotCancellable": { "summary": "RUN_NOT_CANCELLABLE", "value": { "error": { "code": "RUN_NOT_CANCELLABLE", "type": "conflict", "message": "The run already reached a terminal state.", "suggestion": "The run has already finished and can no longer be canceled.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/triggers/brew-events": { "post": { "operationId": "ensureBrewEventTrigger", "tags": [ "Automations" ], "summary": "Get or create an unsubscribe trigger", "description": "Returns the brand’s trigger for one Brew event scope, creating it the first time. Brew events start automations from things that happen inside Brew. The first is `contact.unsubscribed`: a contact unsubscribed with an email’s unsubscribe link or their mail app’s one-click button (never a bounce, complaint, import or API edit).\n\n**Use when** an automation should start when a contact unsubscribes, from one marketing domain’s list or from every email the brand sends.\n\n**Input** `{ event: \"contact.unsubscribed\", scope: \"domain\", domainId }` for one marketing domain’s list (ids from `listDomains`), or `{ event: \"contact.unsubscribed\", scope: \"all\" }` for every email. An unsubscribe from all clicked in one of a domain’s emails also starts that domain’s trigger, while the contact was still on its list.\n\n**Returns** `201` with the new trigger row, or `200` with the existing one (`created: false`). Brew owns its title and payload, so the row is immutable and never fires over the API. The contact has just opted out, so an automation on this trigger sends only a message they need (such as confirming the unsubscribe) from a transactional domain, or mail from another marketing domain they are still on; publish refuses a flow none of whose emails could reach them.\n\n**Errors** `400 INVALID_REQUEST` when `domainId` is missing for `scope: \"domain\"` or sent for `scope: \"all\"`; `404 DOMAIN_NOT_FOUND` for an unknown or cross-brand domain; `422 DOMAIN_PURPOSE_NOT_ALLOWED` for a transactional domain, which owns no list; `409 TRIGGER_LIMIT_REACHED` when the brand already holds the maximum number of triggers.\n\n**See also** `createAutomation`, `fireTrigger`, `listDomains`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrewEventTriggersPostRequest" }, "example": { "event": "contact.unsubscribed", "scope": "domain", "domainId": "jd7f0c2a8w1x9m4n6p3q5r8s2t" } } } }, "responses": { "200": { "description": "The trigger already existed for this scope.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrewEventTriggerSaved" }, "example": { "triggerEventId": "k57abc123unsub", "title": "Unsubscribed from news.acme.com", "description": "Starts when a contact unsubscribes from emails sent from news.acme.com, from an email's unsubscribe link or the mail app's unsubscribe button. Unsubscribing from all emails in one of those emails starts it too.", "provider": "brew_event", "providerEventKey": "contact.unsubscribed", "brewEvent": { "event": "contact.unsubscribed", "scope": "domain", "domainHost": "news.acme.com" }, "payloadSchema": { "fields": [ { "key": "email", "required": true, "type": "string" }, { "children": [ { "key": "scope", "required": true, "type": "string" }, { "key": "domain", "required": false, "type": "string" }, { "key": "method", "required": true, "type": "string" }, { "key": "reasons", "required": true, "type": "array", "itemType": "string" }, { "key": "reasonText", "required": false, "type": "string" }, { "key": "emailId", "required": false, "type": "string" }, { "key": "emailTitle", "required": false, "type": "string" }, { "key": "sendId", "required": false, "type": "string" }, { "key": "at", "required": true, "type": "string" } ], "key": "unsubscribe", "required": true, "type": "object" } ], "type": "object" }, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z", "created": false } } } }, "201": { "description": "Created.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrewEventTriggerSaved" }, "example": { "triggerEventId": "k57abc123unsub", "title": "Unsubscribed from news.acme.com", "description": "Starts when a contact unsubscribes from emails sent from news.acme.com, from an email's unsubscribe link or the mail app's unsubscribe button. Unsubscribing from all emails in one of those emails starts it too.", "provider": "brew_event", "providerEventKey": "contact.unsubscribed", "brewEvent": { "event": "contact.unsubscribed", "scope": "domain", "domainHost": "news.acme.com" }, "payloadSchema": { "fields": [ { "key": "email", "required": true, "type": "string" }, { "children": [ { "key": "scope", "required": true, "type": "string" }, { "key": "domain", "required": false, "type": "string" }, { "key": "method", "required": true, "type": "string" }, { "key": "reasons", "required": true, "type": "array", "itemType": "string" }, { "key": "reasonText", "required": false, "type": "string" }, { "key": "emailId", "required": false, "type": "string" }, { "key": "emailTitle", "required": false, "type": "string" }, { "key": "sendId", "required": false, "type": "string" }, { "key": "at", "required": true, "type": "string" } ], "key": "unsubscribe", "required": true, "type": "object" } ], "type": "object" }, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z", "created": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`TRIGGER_LIMIT_REACHED`: The brand already holds the maximum number of trigger events.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "triggerLimitReached": { "summary": "TRIGGER_LIMIT_REACHED", "value": { "error": { "code": "TRIGGER_LIMIT_REACHED", "type": "conflict", "message": "The brand already holds the maximum number of trigger events.", "suggestion": "Delete an unused trigger with `DELETE /v1/automations/triggers/{triggerEventId}`, then retry. Each brand holds at most 100.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "triggers.write" } }, "/v1/automations/triggers": { "post": { "operationId": "createTrigger", "tags": [ "Automations" ], "summary": "Create a trigger", "description": "Creates a custom trigger event definition — the contract automations subscribe to. Body carries `{ title, description?, payloadSchema }`; the server mints `triggerEventId` and hardcodes `provider: \"brew_api\"`. Integration triggers (clerk, stripe, shopify, …) are provisioned by the corresponding integration only.\n\n`payloadSchema.fields` MUST declare `{ key: \"email\", type: \"string\", required: true }` so downstream automations can resolve a recipient. Returns `201` with the bare trigger row.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggersPostRequest" }, "example": { "title": "User Signed Up", "description": "Fires when a user completes signup.", "payloadSchema": { "type": "object", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "firstName", "type": "string", "required": false } ] } } } } }, "responses": { "201": { "description": "Created. The bare trigger row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerRow" }, "example": { "triggerEventId": "user_signed_up", "title": "User Signed Up", "description": "Fires when a user completes signup.", "provider": "brew_api", "payloadSchema": { "type": "object", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "firstName", "type": "string", "required": false } ] }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.\n\n`PAYLOAD_SCHEMA_EMAIL_REQUIRED`: A trigger payload schema must declare a required string `email` field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "payloadSchemaEmailRequired": { "summary": "PAYLOAD_SCHEMA_EMAIL_REQUIRED", "value": { "error": { "code": "PAYLOAD_SCHEMA_EMAIL_REQUIRED", "type": "invalid_request", "message": "A trigger payload schema must declare a required string `email` field.", "suggestion": "Add { key: \"email\", type: \"string\", required: true } to payloadSchema.fields before retrying.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`TRIGGER_ALREADY_EXISTS`: A trigger with that id already exists in the brand.\n\n`TRIGGER_LIMIT_REACHED`: The brand already holds the maximum number of trigger events.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "triggerAlreadyExists": { "summary": "TRIGGER_ALREADY_EXISTS", "value": { "error": { "code": "TRIGGER_ALREADY_EXISTS", "type": "conflict", "message": "A trigger with that id already exists in the brand.", "suggestion": "Reuse the existing trigger, or choose a different triggerEventId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerLimitReached": { "summary": "TRIGGER_LIMIT_REACHED", "value": { "error": { "code": "TRIGGER_LIMIT_REACHED", "type": "conflict", "message": "The brand already holds the maximum number of trigger events.", "suggestion": "Delete an unused trigger with `DELETE /v1/automations/triggers/{triggerEventId}`, then retry. Each brand holds at most 100.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`PAYLOAD_SCHEMA_EMAIL_REQUIRED`: A trigger payload schema must declare a required string `email` field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadSchemaEmailRequired": { "summary": "PAYLOAD_SCHEMA_EMAIL_REQUIRED", "value": { "error": { "code": "PAYLOAD_SCHEMA_EMAIL_REQUIRED", "type": "invalid_request", "message": "A trigger payload schema must declare a required string `email` field.", "suggestion": "Add { key: \"email\", type: \"string\", required: true } to payloadSchema.fields before retrying.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false }, "get": { "operationId": "listTriggers", "tags": [ "Automations" ], "summary": "List triggers", "description": "Lists every trigger the brand has under `{ data, pagination }`: `provider: \"brew_api\"` for API-created customs, `provider: \"clerk\" | \"stripe\" | …` for integration-provisioned triggers, and `provider: \"brew_event\"` for the unsubscribe triggers Brew starts itself. Each row carries its `payloadSchema`.\n\n**Use when** finding the `triggerEventId` to fire, to wire an automation to, or to read the typed contract of.\n\n**Input** `limit` and `cursor`.\n\n**Returns** `200` with a page of trigger rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key.\n\n**See also** `getTrigger` (with `include=skill`), `createTrigger`, `fireTrigger`, `listTriggerInstances`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of trigger rows.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggersListResponse" }, "example": { "data": [ { "triggerEventId": "user_signed_up", "title": "User Signed Up", "description": "Fires when a user completes signup.", "provider": "brew_api", "payloadSchema": { "type": "object", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "firstName", "type": "string", "required": false } ] }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.read" } }, "/v1/automations/triggers/{triggerEventId}": { "get": { "operationId": "getTrigger", "tags": [ "Automations" ], "summary": "Get a trigger", "description": "Reads one trigger as the bare row: `triggerEventId`, `title`, `provider`, `payloadSchema` and timestamps.\n\n**Use when** inspecting the payload shape before firing, or generating an integration brief for the fire endpoint.\n\n**Input** `triggerEventId` in the path (URL-encode composite integration ids); `include=skill` adds `skill`, a SKILL.md-shaped wiring brief built from the stored contract when one exists.\n\n**Returns** `200` with the row; `skill` is present only when requested.\n\n**Errors** `404 TRIGGER_EVENT_NOT_FOUND` for an unknown or cross-brand id; `400 INVALID_REQUEST` for an unknown `include` token.\n\n**See also** `listTriggers`, `getTriggerContract`, `fireTrigger`, `checkTriggerReady`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "schema": { "type": "string", "description": "Expansions: `skill` adds a SKILL.md-shaped wiring brief for the fire endpoint.", "x-brew-include-tokens": [ "skill" ] }, "required": false, "description": "Expansions: `skill` adds a SKILL.md-shaped wiring brief for the fire endpoint.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The trigger row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerRow" }, "example": { "triggerEventId": "user_signed_up", "title": "User Signed Up", "description": "Fires when a user completes signup.", "provider": "brew_api", "payloadSchema": { "type": "object", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "firstName", "type": "string", "required": false } ] }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.read" }, "patch": { "operationId": "updateTrigger", "tags": [ "Automations" ], "summary": "Update a trigger", "description": "Updates one or more editable fields (`title`, `description`, `payloadSchema`). Whether a trigger fires is governed solely by `automation.published` on each wired automation — there is no per-trigger off-switch. Integration-provisioned triggers are immutable here (`422 TRIGGER_IMMUTABLE`). While a published automation uses the trigger, a `payloadSchema` change that would stop it from running (removing or retyping a field it reads, or declaring the shape of an open object or list so one of its merge tags no longer resolves) is refused with `409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS`. Returns the bare updated row.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggersPatchRequest" }, "example": { "title": "User Signed Up (v2)" } } } }, "responses": { "200": { "description": "Updated.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerRow" }, "example": { "triggerEventId": "user_signed_up", "title": "User Signed Up", "description": "Fires when a user completes signup.", "provider": "brew_api", "payloadSchema": { "type": "object", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "firstName", "type": "string", "required": false } ] }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS`: A published automation consumes this trigger, so the contract change must stay backward compatible: enforcement cannot tighten, a referenced field cannot be removed, retyped, or made required without a fallback, and an open object or list cannot gain a shape that drops a field a published automation reads.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contractLockedByPublishedAutomations": { "summary": "CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS", "value": { "error": { "code": "CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS", "type": "conflict", "message": "A published automation consumes this trigger, so the contract change must stay backward compatible: enforcement cannot tighten, a referenced field cannot be removed, retyped, or made required without a fallback, and an open object or list cannot gain a shape that drops a field a published automation reads.", "suggestion": "Unpublish or detach the published automations that consume this trigger, or make a backward-compatible change (adding optional fields and loosening enforcement stay allowed).", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`TRIGGER_IMMUTABLE`: Integration-provisioned and Brew-event triggers cannot be changed through the API.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "triggerImmutable": { "summary": "TRIGGER_IMMUTABLE", "value": { "error": { "code": "TRIGGER_IMMUTABLE", "type": "invalid_request", "message": "Integration-provisioned and Brew-event triggers cannot be changed through the API.", "suggestion": "Only brew_api and custom triggers can be patched. Toggle integration per-event settings on the Integrations page instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.write" }, "delete": { "operationId": "deleteTrigger", "tags": [ "Automations" ], "summary": "Delete a trigger", "description": "Deletes a custom trigger. Refused with `409 TRIGGER_HAS_DEPENDENT_AUTOMATIONS` while automations still reference it (`details.referencingAutomations` lists each blocker). Idempotent — an already-gone trigger resolves with `deleted: false`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggersDeleteResponse" }, "example": { "triggerEventId": "user_signed_up", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`TRIGGER_HAS_DEPENDENT_AUTOMATIONS`: Automations still reference the trigger; `details.referencingAutomations[]` names them.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "triggerHasDependentAutomations": { "summary": "TRIGGER_HAS_DEPENDENT_AUTOMATIONS", "value": { "error": { "code": "TRIGGER_HAS_DEPENDENT_AUTOMATIONS", "type": "conflict", "message": "Automations still reference the trigger; `details.referencingAutomations[]` names them.", "suggestion": "Delete or detach the automations listed in `details.referencingAutomations` first, then retry DELETE.", "docs": "https://docs.brew.new/api-reference/api/errors", "details": { "referencingAutomations": [ { "automationId": "V1StGXR8_Z5jdHi6B-myT", "name": "Welcome series", "published": true } ] } } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.write" } }, "/v1/automations/triggers/{triggerEventId}/readiness": { "get": { "operationId": "checkTriggerReady", "tags": [ "Automations" ], "summary": "Check a trigger is ready to fire", "description": "Reports whether a fire would start anything right now, and everything a caller needs to wire one. Runs the same credential, brand scope and permission gates a real fire hits, without firing.\n\n**Use when** wiring an external service, before sending a live event.\n\n**Returns** `200 { ready, blockers[], payloadSchema, endpoint, publishedAutomations, counts, delivery? }`. A `NO_PUBLISHED_AUTOMATION` blocker with `ready: false` means the trigger resolves and the credential passes, but nothing published listens for it yet, so a fire would start no runs. That stays a 200 because a probe has to report why a fire would not work.\n\n`delivery` appears for an integration trigger whose source sends only the events set up at its end (a Shopify shop sends a topic only to its own webhook): whether Brew has received that event, and what to set up when it has not. It never changes `ready`.\n\n**Errors** `404 TRIGGER_EVENT_NOT_FOUND` for an unknown or cross-brand id; `409 TRIGGER_NOT_FIREABLE` for a Brew event trigger, which Brew starts itself.\n\n**See also** `fireTrigger`, `getTriggerContract`, `listTriggers`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The readiness report: whether a fire would start runs, and everything needed to wire the caller.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerReadiness" }, "example": { "triggerEventId": "user_signed_up", "ready": true, "blockers": [], "title": "User Signed Up", "provider": "brew_api", "payloadSchema": { "type": "object", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "firstName", "type": "string", "required": false } ] }, "endpoint": "/v1/automations/triggers/user_signed_up/fire", "publishedAutomations": [ { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "name": "Welcome flow" } ], "counts": { "automations": 1, "skipped": 0 } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`TRIGGER_NOT_FIREABLE`: Brew starts this trigger itself when its event happens, so it cannot be fired over the API.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "triggerNotFireable": { "summary": "TRIGGER_NOT_FIREABLE", "value": { "error": { "code": "TRIGGER_NOT_FIREABLE", "type": "conflict", "message": "Brew starts this trigger itself when its event happens, so it cannot be fired over the API.", "suggestion": "Try the automation with its Test action (POST /v1/automations/{automationId}/test) instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/automations/triggers/{triggerEventId}/fire": { "post": { "operationId": "fireTrigger", "tags": [ "Automations" ], "summary": "Fire a trigger", "description": "Fires the trigger: validates the payload against the stored contract, upserts the contact it describes, then starts one run per published automation attached to the trigger.\n\n**Use when** an event in your product should start every published automation attached to this trigger.\n\n**Input** `{ payload }`, validated against the trigger’s `payloadSchema`. Unknown fields are accepted and reported in `warnings[]`. The contact derived from the payload is upserted before the fan-out with the declared top-level scalar fields the fire sent; object and array fields stay template data, and a contract `fallbackValue` is never written onto the contact. A value the contact field’s type refuses is left out and reported as a `FIELD_TYPE_MISMATCH` warning (`field`, `expectedType`, `actualType`); the rest of the contact is written and the runs still start.\n\n**Returns** `202 { triggerInstanceId, triggerEventId, status, automationRunIds[], notStarted[], publishedAutomations[], counts, warnings[], receivedAt }`. Follow a run with `getAutomationRun`, the fire itself with `getTriggerInstance`. `notStarted[]` names each automation whose run failed to start and why, so a `triggered` fire with no runs explains itself. `counts.skipped` is the recipients a suppression already covered, so `automations: 2, skipped: 2` means nothing was delivered.\n\n**Idempotency** send a stable `Idempotency-Key` header on every retry. A repeat answers `200` with `status: \"replayed\"` and the ORIGINAL run ids; nothing fires twice. A fire key is matched against the stored trigger receipt, so it replays for as long as the receipt is kept (90 days), not only the 24 hours of the shared response cache. Use one key per business action and never reuse it for a different fire.\n\n**Errors** `400 INVALID_PAYLOAD` when the payload does not satisfy the schema, or when `email` (or `user.email`) is not one plain address such as `jane@example.com`: a display name (`Jane `), a list or a line break is refused with `details.errors[].code: \"invalid_email\"`, and no contact is written; `404 TRIGGER_EVENT_NOT_FOUND` for an unknown or cross-brand id; `422 NO_PUBLISHED_AUTOMATION` when nothing published listens for the trigger; `409 IDEMPOTENCY_CONFLICT` when a key is reused with a different body; `409 TRIGGER_NOT_FIREABLE` for a Brew event trigger, which Brew starts itself (try its automation with `testAutomation`).\n\n**See also** `checkTriggerReady`, `getTriggerInstance`, `listAutomationRuns`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries of the same trigger fire and request body. The shared response cache defaults to 24 hours; the trigger receipt replays the original run ids for as long as it is stored (90 days). Use one key per business action and never reuse it for a different fire.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers`. Custom triggers use `tri_…` ids; integration triggers use composite ids (e.g. `clerk:org_…:brand_…:user.created`, URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerFireRequest" }, "example": { "payload": { "email": "jane@example.com", "firstName": "Jane" } } } } }, "responses": { "200": { "description": "Idempotent replay: this `Idempotency-Key` already fired. The ids are the original run’s.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerFireAccepted" }, "example": { "triggerInstanceId": "tin_4fZ2kQ9pLm7xR1tV8wYcD", "triggerEventId": "user_signed_up", "status": "replayed", "automationRunIds": [ "jh7acthhe99pq4448xh83gn54x8eennb" ], "publishedAutomations": [ { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "name": "Welcome flow" } ], "counts": { "automations": 1, "skipped": 0 }, "warnings": [], "receivedAt": "2026-04-08T12:34:56.789Z" } } } }, "202": { "description": "Accepted: one run started per matched published automation.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerFireAccepted" }, "example": { "triggerInstanceId": "tin_4fZ2kQ9pLm7xR1tV8wYcD", "triggerEventId": "user_signed_up", "status": "triggered", "automationRunIds": [ "jh7acthhe99pq4448xh83gn54x8eennb" ], "publishedAutomations": [ { "automationId": "M3nRk8LqW2xT5vBp9YcZd", "name": "Welcome flow" } ], "counts": { "automations": 1, "skipped": 0 }, "warnings": [], "receivedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_PAYLOAD`: The test payload does not match the trigger’s payload schema.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidPayload": { "summary": "INVALID_PAYLOAD", "value": { "error": { "code": "INVALID_PAYLOAD", "type": "invalid_request", "message": "The test payload does not match the trigger’s payload schema.", "suggestion": "Send fields and types matching the trigger’s payloadSchema (see GET /v1/automations/triggers/{triggerEventId}).", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`TRIGGER_NOT_FIREABLE`: Brew starts this trigger itself when its event happens, so it cannot be fired over the API.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "triggerNotFireable": { "summary": "TRIGGER_NOT_FIREABLE", "value": { "error": { "code": "TRIGGER_NOT_FIREABLE", "type": "conflict", "message": "Brew starts this trigger itself when its event happens, so it cannot be fired over the API.", "suggestion": "Try the automation with its Test action (POST /v1/automations/{automationId}/test) instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`NO_PUBLISHED_AUTOMATION`: The trigger fired, but no published automation listens for it, so nothing would run.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "noPublishedAutomation": { "summary": "NO_PUBLISHED_AUTOMATION", "value": { "error": { "code": "NO_PUBLISHED_AUTOMATION", "type": "invalid_request", "message": "The trigger fired, but no published automation listens for it, so nothing would run.", "suggestion": "Publish an automation wired to this trigger, then fire again. GET /v1/automations/triggers/{triggerEventId}/readiness reports this before you send a live event.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "fail_closed", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.write" } }, "/v1/automations/triggers/{triggerEventId}/contract": { "get": { "operationId": "getTriggerContract", "tags": [ "Automations" ], "summary": "Get a trigger payload contract", "description": "The payload contract for the trigger: the STORED contract when one has been declared (`source: \"stored\"`, with `contractHash`, `version`, `enforcement`), otherwise the derived one (`source: \"derived_from_schema\"`, built from the trigger’s flat `payloadSchema`).\n\nContract fields form a tree: scalars (`string` | `int` | `float` | `boolean` | `date` | `enum`), `object` nodes with `children`, and `array` nodes with `children` (element object shape) or `itemType` (scalar elements). Derived contracts may carry `type: \"unknown\"` where no type evidence exists.\n\nPass `?format=` for generated artifacts instead of the JSON contract.", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "Rendering. `json` (default) returns the contract object; `ts` | `zod` | `jsonschema` | `skill` return `{format, content}` — a generated TypeScript type, Zod schema, JSON Schema document, or SKILL.md wiring brief.", "schema": { "type": "string", "enum": [ "json", "ts", "zod", "jsonschema", "skill" ] } }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers` (integration triggers use composite ids — URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers` (integration triggers use composite ids — URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The contract (`format=json`, default) or `{format, content}` for text formats.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractGetResponse" }, "example": { "subjectKind": "trigger", "subjectId": "user_signed_up", "source": "stored", "format": "json", "typeName": "UserSignedUpPayload", "contractHash": "22545d11e1d174ba0717ed37c9c4b460c96bed51ae31ea0af18266ebba30f76a", "version": 2, "enforcement": "off", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "plan", "type": "enum", "required": false, "enumValues": [ "free", "pro" ], "fallbackValue": "free" }, { "key": "order", "type": "object", "required": false, "children": [ { "key": "total", "type": "float", "required": true } ] } ] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.read" }, "put": { "operationId": "setTriggerContract", "tags": [ "Automations" ], "summary": "Declare a trigger payload contract", "description": "Declares the stored payload contract for the trigger, changes how it is enforced, or both, in one call. `fields` and `enforcement` are both optional, so arming enforcement is `{ \"enforcement\": \"strict\" }`. While a PUBLISHED automation consumes the trigger the change must stay backward compatible (the ratchet below); loosening is always allowed.\n\n**Use when** you want generated types, a dry-run validator (`validateTriggerPayload`) and drift detection for the JSON your service fires, or when you flip `enforcement`. Draft the tree from a real payload with `inferPayloadContract`. Trigger contracts MUST keep a top-level `{ key: \"email\", type: \"string\", required: true }` field so automations can resolve a recipient.\n\n**Input** `fields` is a tree: scalars (`string`, `int`, `float`, `boolean`, `date`, `enum`), `object` nodes with `children`, `array` nodes with `children` (object elements), `itemType` (scalar elements) or neither. The tree is validated BEFORE any write: unknown-typed nodes are refused, keys are unique per level, an `object` declares at least one child, and no two top-level fields that a fire copies onto the contact fold to one contact field (`plan` and `Plan`, `team_size` and `Team Size`; rename one or set `syncToContact: false` on one). `enforcement`: `off` (advisory, the default for a new contract), `prune` (drop undeclared keys before the run), `strict` (reject a payload carrying them). A `fallbackValue` satisfies `required` in EVERY mode: a producer that omits the key never fails a fire, every recipient gets the fallback. The version bumps only when the behavioral surface changes (keys, types, required, fallbacks; not descriptions or examples). Declaring a contract never changes fire behavior by itself. Loosening is the escape hatch when `strict` rejects a drifted producer in production.\n\n**Returns** `200` with the same body a follow-up `getTriggerContract` returns plus `warnings[]` (always present, often empty): `ENFORCEMENT_LOOSENED_WHILE_PUBLISHED` when enforcement went down while published automations consume the trigger (tightening back is refused until they are unpublished or detached), and one `REQUIRED_FIELD_SATISFIED_BY_FALLBACK` per required field that declares a fallback (`field` is its dotted path). Ratchet while a published automation consumes the trigger: tighten `off→prune`, `off→strict`, `prune→strict` = `409`; loosen = `200` + warning; remove, retype or enum-narrow a field, or add a required field WITHOUT a fallback = `409`; add an optional field, widen a type, add an enum value, or add a required field WITH a fallback = `200` (+ warning per fallback). With no published consumer every change is `200`.\n\n**Errors** `409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS` for a change the ratchet refuses (`message` names the incompatibility; unpublish or detach the consumers, or make a compatible change); `404 TRIGGER_EVENT_NOT_FOUND`; `422 TRIGGER_IMMUTABLE` for a Brew event trigger, whose contract Brew owns; `400 INVALID_REQUEST` (`param: \"fields\"`) when the tree fails structural validation, or when a body with no `fields` targets a trigger that has no stored contract yet.\n\n**See also** `getTriggerContract`, `validateTriggerPayload`, `inferPayloadContract`, `updateAutomation` (publishing a consumer starts the ratchet).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers` (integration triggers use composite ids — URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers` (integration triggers use composite ids — URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractPutRequest" }, "example": { "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "plan", "type": "enum", "required": false, "enumValues": [ "free", "pro" ], "fallbackValue": "free", "description": "Billing plan at signup time." }, { "key": "order", "type": "object", "required": false, "children": [ { "key": "total", "type": "float", "required": true } ] } ] } } } }, "responses": { "200": { "description": "Stored. The contract as a follow-up GET would return it, plus `warnings[]` about the write.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractPutResponse" }, "example": { "subjectKind": "trigger", "subjectId": "user_signed_up", "source": "stored", "format": "json", "typeName": "UserSignedUpPayload", "contractHash": "22545d11e1d174ba0717ed37c9c4b460c96bed51ae31ea0af18266ebba30f76a", "version": 3, "enforcement": "prune", "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "plan", "type": "enum", "required": false, "enumValues": [ "free", "pro" ], "fallbackValue": "free" }, { "key": "order", "type": "object", "required": false, "children": [ { "key": "total", "type": "float", "required": true } ] } ], "warnings": [ { "code": "ENFORCEMENT_LOOSENED_WHILE_PUBLISHED", "message": "Enforcement loosened from strict to prune while 1 published automation(s) consume this trigger. Loosening is allowed as the operator escape hatch, but tightening back to strict will be refused with 409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS until they are unpublished or detached." } ] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS`: A published automation consumes this trigger, so the contract change must stay backward compatible: enforcement cannot tighten, a referenced field cannot be removed, retyped, or made required without a fallback, and an open object or list cannot gain a shape that drops a field a published automation reads.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contractLockedByPublishedAutomations": { "summary": "CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS", "value": { "error": { "code": "CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS", "type": "conflict", "message": "A published automation consumes this trigger, so the contract change must stay backward compatible: enforcement cannot tighten, a referenced field cannot be removed, retyped, or made required without a fallback, and an open object or list cannot gain a shape that drops a field a published automation reads.", "suggestion": "Unpublish or detach the published automations that consume this trigger, or make a backward-compatible change (adding optional fields and loosening enforcement stay allowed).", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`TRIGGER_IMMUTABLE`: Integration-provisioned and Brew-event triggers cannot be changed through the API.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "triggerImmutable": { "summary": "TRIGGER_IMMUTABLE", "value": { "error": { "code": "TRIGGER_IMMUTABLE", "type": "invalid_request", "message": "Integration-provisioned and Brew-event triggers cannot be changed through the API.", "suggestion": "Only brew_api and custom triggers can be patched. Toggle integration per-event settings on the Integrations page instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.write" } }, "/v1/automations/triggers/{triggerEventId}/contract/validate": { "post": { "operationId": "validateTriggerPayload", "tags": [ "Automations" ], "summary": "Validate a trigger payload", "description": "Dry-runs a payload against the trigger's contract — the SAME validator the live path runs, against the stored contract when one exists (derived otherwise; `source` says which). Nothing fires, sends, or writes.\n\nAn invalid payload is still a `200`: the verdict is the response — read `valid`, `errors`, `warnings`, `resolvedPayload` (fallbacks applied), and `prunedKeys`. Pass `enforcement: \"prune\" | \"strict\"` to preview a different mode than the stored one. Fire for real with `POST …/fire`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trigger id returned by `POST /v1/automations/triggers` (integration triggers use composite ids — URL-encode the colons).", "example": "user_signed_up" }, "required": true, "description": "Trigger id returned by `POST /v1/automations/triggers` (integration triggers use composite ids — URL-encode the colons).", "name": "triggerEventId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractValidateRequest" }, "example": { "payload": { "email": "jane@example.com", "coupon": "SPRING" } } } } }, "responses": { "200": { "description": "The verdict — for BOTH valid and invalid payloads (`valid` discriminates).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractValidateResponse" }, "example": { "valid": true, "errors": [], "warnings": [ { "code": "unexpected_key", "field": "coupon", "message": "Field \"coupon\" is not declared in the contract" } ], "resolvedPayload": { "email": "jane@example.com", "plan": "free" }, "prunedKeys": [ "coupon" ], "source": "stored", "contractHash": "22545d11e1d174ba0717ed37c9c4b460c96bed51ae31ea0af18266ebba30f76a" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_EVENT_NOT_FOUND`: No trigger with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerEventNotFound": { "summary": "TRIGGER_EVENT_NOT_FOUND", "value": { "error": { "code": "TRIGGER_EVENT_NOT_FOUND", "type": "not_found", "message": "No trigger with that id exists in the brand.", "suggestion": "List triggers with GET /v1/automations/triggers.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.read" } }, "/v1/payload-contracts/infer": { "post": { "operationId": "inferPayloadContract", "tags": [ "Automations" ], "summary": "Infer a payload contract from an example", "description": "Drafts a contract from a real example payload: paste the JSON your system sends and get back typed `fields` — integers and floats split automatically, full ISO timestamps become `date`, object/array shapes are walked recursively. Every inferred field is `required: true` (relax explicitly).\n\nSpots inference cannot type (nulls, empty arrays) degrade honestly and are listed in `issues` with the offending path. Nothing is saved: review the draft, then `PUT` it to `…/triggers/{triggerEventId}/contract`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractInferRequest" }, "example": { "example": { "email": "jane@example.com", "order": { "total": 9.5, "placedAt": "2026-04-08T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "The unsaved contract draft.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadContractInferResponse" }, "example": { "fields": [ { "key": "email", "type": "string", "required": true }, { "key": "order", "type": "object", "required": true, "children": [ { "key": "total", "type": "float", "required": true }, { "key": "placedAt", "type": "date", "required": true } ] } ], "issues": [] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "none", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "triggers.read" } }, "/v1/automations/trigger-instances": { "get": { "operationId": "listTriggerInstances", "tags": [ "Automations" ], "summary": "List trigger instances", "description": "Lists fired trigger-event instances, newest first, under `{ data, pagination }`: the audit log of every inbound fire, from the API (`source: \"api\"`), an integration webhook (`source: \"integration\"`), or Brew itself (`source: \"brew_event\"`, a contact unsubscribing). Each row links the fire to the automations it matched and the runs it started (`automationRunIds`).\n\n**Use when** confirming that fires arrived, or following a fire to its runs and sends.\n\n**Input** `triggerEventId` to narrow to one trigger; `limit` and `cursor` (an opaque native cursor).\n\n**Returns** `200` with a page of `TriggerInstance` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or a malformed cursor.\n\n**See also** `getTriggerInstance`, `fireTrigger`, `listAutomationRuns` (`?triggerInstanceId=`), `listSends` (`?triggerInstanceId=`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": false, "name": "triggerEventId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of fired trigger-event instances.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerInstancesListResponse" }, "example": { "data": [ { "triggerInstanceId": "tin_4fZ2kQ9pLm7xR1tV8wYcD", "source": "api", "provider": "brew_api", "triggerEventId": "user_signed_up", "state": "processed", "matchedAutomationIds": [ "M3nRk8LqW2xT5vBp9YcZd" ], "automationRunIds": [ "jh7acthhe99pq4448xh83gn54x8eennb" ], "attempts": 1, "receivedAt": "2026-04-08T12:34:56.789Z", "processedAt": "2026-04-08T12:34:57.100Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/automations/trigger-instances/{triggerInstanceId}": { "get": { "operationId": "getTriggerInstance", "tags": [ "Automations" ], "summary": "Get a trigger instance", "description": "Reads one fired trigger-event instance as the bare row: its `state`, the automations it matched, the `automationRunIds` it started and the `rejectionReason` when it was refused.\n\n**Use when** following the `triggerInstanceId` a fire returned to the runs it started.\n\n**Input** `triggerInstanceId` in the path.\n\n**Returns** `200` with the row.\n\n**Errors** `404 TRIGGER_INSTANCE_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `listTriggerInstances`, `getAutomationRun`, `listSends` (`?triggerInstanceId=`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "triggerInstanceId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The fired trigger-event instance.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerInstance" }, "example": { "triggerInstanceId": "tin_4fZ2kQ9pLm7xR1tV8wYcD", "source": "api", "provider": "brew_api", "triggerEventId": "user_signed_up", "state": "processed", "matchedAutomationIds": [ "M3nRk8LqW2xT5vBp9YcZd" ], "automationRunIds": [ "jh7acthhe99pq4448xh83gn54x8eennb" ], "attempts": 1, "receivedAt": "2026-04-08T12:34:56.789Z", "processedAt": "2026-04-08T12:34:57.100Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`TRIGGER_INSTANCE_NOT_FOUND`: No fired trigger instance with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "triggerInstanceNotFound": { "summary": "TRIGGER_INSTANCE_NOT_FOUND", "value": { "error": { "code": "TRIGGER_INSTANCE_NOT_FOUND", "type": "not_found", "message": "No fired trigger instance with that id exists in the brand.", "suggestion": "List recent fires with GET /v1/automations/trigger-instances.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "automations", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "automation.runs.read" } }, "/v1/contacts": { "post": { "operationId": "upsertContacts", "tags": [ "Contacts" ], "summary": "Create or update contacts", "description": "Upserts a single contact OR a batch (`{ contacts: [...] }`, up to 1000 rows). Unknown custom fields auto-create field definitions on the brand, typed from the batch (native booleans/numbers, ISO-date strings → `date`, anything else `string`). `fieldsCreated` names only the definitions this request created: when two requests create the same new field at once, the first definition wins and the values in the other request are coerced or refused against it, exactly as if it had been sent second. Create the field first with `POST /v1/fields` to pin its type.\n\nCustom-field names are folded to one key: words split at spaces, `_`, `-` and a lower-to-upper letter change, then joined camelCase (`Plan`, `PLAN` and `plan` are the field `plan`; `team_size` and `Team Size` are `teamSize`). A key written under its folded name adds a `FIELD_NAME_NORMALIZED` warning (`original`, `normalized`). Two keys that fold to one field (`plan` and `Plan`) would lose one value, so they are a `422 FIELD_NAME_COLLISION` on a single upsert (nothing written) and a per-row `errors[]` entry (`code: FIELD_NAME_COLLISION`) in a batch.\n\nCustom-field values are coerced to the definition's type (dates → epoch ms, `\"1,234\"` → 1234, `yes`/`no` → booleans). A value that cannot be coerced (`\"$49\"` in a number field) is a `409 FIELD_TYPE_MISMATCH` on a single upsert and a per-row `errors[]` entry (`code: FIELD_TYPE_MISMATCH`, `field`) in a batch — the other rows still land. A value that was converted adds one `warnings[]` entry per field (`code: FIELD_TYPE_COERCED`, `field`, `from`, `to`); a date written to a `date` field is not reported. A `customFields` key is never stored under a core field name. One whose loss would change the contact (`subscribed`, `First Name`, `consent`, a suppression flag or domain opt-out, or an `email` naming another address) is a `422 CORE_FIELD_IMMUTABLE` on a single upsert (nothing written) and a per-row `errors[]` entry (`code: CORE_FIELD_IMMUTABLE`, `field`) in a batch; send `firstName`, `lastName`, `subscribed` and `consent` at the top level. A key naming a field Brew manages (`createdAt`, `validationStatus`) is dropped with a `warnings[]` entry (`code: CORE_FIELD_IGNORED`, `field`) and the contact is still written, and an `email` key repeating the contact address is ignored.\n\nDates: a JSON number is epoch milliseconds. A string may be ISO (`2026-04-03`, with or without a time and offset), a Unix timestamp in seconds (10 digits) or milliseconds (13), a month name (`3 Apr 2026`, `April 3, 2026`, `03-Apr-26`), year-first (`2026/04/03`), compact (`20260403`), month and year read as the 1st (`2026-04`), dotted day-first (`03.04.2026`), or a slash or dash date. A slash or dash date with a day over 12 reads that way (`13/04/2026` is 13 April). One that reads either way (`03/04/2026`) follows the day/month order the batch's other dates in that field prove, else month/day, with a `warnings[]` entry (`code: DATE_ORDER_ASSUMED`, `field`). Send `YYYY-MM-DD` to be unambiguous.\n\nOptional `consent: { source: \"api\" | \"form\" | \"import\", capturedAt?, policyVersion?, evidence? }` records marketing consent provenance on the contact (per row, or once at batch level as the default). It never changes `subscribed`. An inline marketing send later needs the contact to be subscribed, and warns when no record exists.\n\n`subscribed: false` unsubscribes the contact, new or existing. `subscribed: true` only applies to a NEW contact: Brew never re-subscribes a contact who opted out, so a single upsert asking for it is a `422 RESUBSCRIBE_NOT_ALLOWED` (nothing written), and a batch row keeps its other fields and adds a `warnings[]` entry (`code: RESUBSCRIBE_SKIPPED`, `email`).\n\nSingle: `201` with `{ contact, created, fieldsCreated, warnings }`. Batch: `200` with `{ summary, fieldsCreated, errors, warnings }` — or `207` when some rows failed (per-row errors in `errors[]`).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsPostRequest" }, "examples": { "single": { "summary": "Upsert a single contact", "value": { "email": "jane@example.com", "firstName": "Jane", "customFields": { "plan": "enterprise" }, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03", "evidence": "newsletter checkbox on /signup" } } }, "batch": { "summary": "Upsert a batch", "value": { "contacts": [ { "email": "jane@example.com", "firstName": "Jane" }, { "email": "john@example.com", "firstName": "John" } ], "consent": { "source": "import", "policyVersion": "2026-03" } } } } } } }, "responses": { "200": { "description": "Batch upsert applied (every row succeeded).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsPostBatchResponse" }, "example": { "summary": { "inserted": 2, "updated": 0, "failed": 0 }, "fieldsCreated": [], "errors": [], "warnings": [] } } } }, "201": { "description": "Single upsert applied.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsPostSingleResponse" }, "example": { "contact": { "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "enterprise", "revenue": 4200 } }, "created": true, "fieldsCreated": [ "plan" ], "warnings": [] } } } }, "207": { "description": "Batch partially applied — inspect `errors[]` for each failed row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsPostBatchResponse" }, "example": { "summary": { "inserted": 1, "updated": 0, "failed": 2 }, "fieldsCreated": [], "errors": [ { "email": "not-an-email", "code": "INVALID_EMAIL", "message": "not-an-email is not a valid email address." }, { "email": "john@example.com", "code": "FIELD_TYPE_MISMATCH", "field": "customFields.plan", "message": "Field 'customFields.plan' is type 'number' but received string '$49'." } ], "warnings": [] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`FIELD_TYPE_MISMATCH`: A value does not match the declared type of its custom field.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "fieldTypeMismatch": { "summary": "FIELD_TYPE_MISMATCH", "value": { "error": { "code": "FIELD_TYPE_MISMATCH", "type": "conflict", "message": "A value does not match the declared type of its custom field.", "suggestion": "Send a value that matches the field's type. To change the type, delete the field (this clears its value on every contact) and create it again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`BATCH_TOO_LARGE`: A batch write exceeds the per-request row cap.\n\n`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.\n\n`FIELD_NAME_COLLISION`: Two keys in one request name the same contact field (`plan` and `Plan`, `team_size` and `Team Size`), so one value would be lost.\n\n`INVALID_EMAIL`: A contact email is not a deliverable address shape.\n\n`MISSING_EMAIL`: A contact row has no `email`, the primary key.\n\n`RESUBSCRIBE_NOT_ALLOWED`: The write set `subscribed` to true on a contact who unsubscribed, and Brew never re-subscribes an opt-out through the API, MCP or an import; `details.email` names the contact.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "batchTooLarge": { "summary": "BATCH_TOO_LARGE", "value": { "error": { "code": "BATCH_TOO_LARGE", "type": "invalid_request", "message": "A batch write exceeds the per-request row cap.", "suggestion": "Split the request into smaller batches and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "fieldNameCollision": { "summary": "FIELD_NAME_COLLISION", "value": { "error": { "code": "FIELD_NAME_COLLISION", "type": "invalid_request", "message": "Two keys in one request name the same contact field (`plan` and `Plan`, `team_size` and `Team Size`), so one value would be lost.", "suggestion": "Send one of the two keys, or rename one so it names a different field.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "invalidEmail": { "summary": "INVALID_EMAIL", "value": { "error": { "code": "INVALID_EMAIL", "type": "invalid_request", "message": "A contact email is not a deliverable address shape.", "suggestion": "Fix the address named in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "missingEmail": { "summary": "MISSING_EMAIL", "value": { "error": { "code": "MISSING_EMAIL", "type": "invalid_request", "message": "A contact row has no `email`, the primary key.", "suggestion": "Provide an email address for every contact in the request body.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "resubscribeNotAllowed": { "summary": "RESUBSCRIBE_NOT_ALLOWED", "value": { "error": { "code": "RESUBSCRIBE_NOT_ALLOWED", "type": "invalid_request", "message": "The write set `subscribed` to true on a contact who unsubscribed, and Brew never re-subscribes an opt-out through the API, MCP or an import; `details.email` names the contact.", "suggestion": "Drop `subscribed` from the write; a contact who opted out re-subscribes through their own action, or from their contact page in the Brew app once they ask.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true }, "get": { "operationId": "listContacts", "tags": [ "Contacts" ], "summary": "List contacts", "description": "Lists the brand’s contacts under `{ data, pagination }`, newest first by default.\n\n**Use when** paging through contacts, running a free-text search, or reading one saved audience’s members. Typed filter clauses and counts are `searchContacts`.\n\n**Input** `search` (a whole email address matches only that contact, with its `+` encoded as `%2B`; other text matches any of its words in email, first and last name), `audienceId` (only that saved audience’s members), `sort` (any core column or custom field, default `createdAt`) and `order`, `limit` and `cursor`.\n\n**Returns** `200` with a page of `Contact` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown `audienceId`, an unsupported `sort` field or an invalid cursor.\n\n**See also** `getContact`, `searchContacts`, `upsertContacts`, `listContactFields`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "A whole email address matches only that contact. Other text matches the contacts whose email, first or last name contains any of its words, in `sort` order. Encode an address's `+` as `%2B`." }, "required": false, "description": "A whole email address matches only that contact. Other text matches the contacts whose email, first or last name contains any of its words, in `sort` order. Encode an address's `+` as `%2B`.", "name": "search", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Only members of this saved audience." }, "required": false, "description": "Only members of this saved audience.", "name": "audienceId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "default": "createdAt" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "required": false, "name": "order", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of contacts.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsListResponse" }, "example": { "data": [ { "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "enterprise", "revenue": 4200 } }, { "email": "john@example.com", "firstName": "John", "lastName": "Smith", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "starter" } } ], "pagination": { "limit": 50, "cursor": "eyJsYXN0SWQiOiIxMjMiLCJsYXN0U29ydCI6MTcxMjU5MjAwMDAwMH0=", "hasMore": true } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "contacts.read" } }, "/v1/contacts/{email}": { "patch": { "operationId": "updateContact", "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Patches fields on the contact (`{ fields: { : } }` — core columns or custom fields) and/or records marketing consent provenance (`{ consent: { source, capturedAt?, policyVersion?, evidence? } }`, never re-subscribing an opt-out). Send one or both. Returns `{ contact, updated, warnings }`: `updated` lists the fields whose stored value changed (`consent` included), and is empty when every value sent matched what was stored (nothing is written then). `warnings` carries the same `DATE_ORDER_ASSUMED` and `FIELD_TYPE_COERCED` caveats a single upsert reports: an ambiguous date such as `03/04/2026` reads month/day, so send `YYYY-MM-DD`. A JSON number past 9007199254740991 (2^53 - 1) arrives already rounded, so a `number` or `string` field refuses it with `409 FIELD_TYPE_MISMATCH`; send large ids as JSON strings to a `string` field. `fields.subscribed: false` unsubscribes; `true` on a contact who opted out is a `422 RESUBSCRIBE_NOT_ALLOWED` (they re-subscribe through their own action, or from their contact page in the Brew app). Two `fields` keys that name one field (`plan` and `Plan`, `customFields.plan` and `plan`) are a `422 FIELD_NAME_COLLISION`, nothing written.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The contact’s email address (URL-encoded). Email is the contact primary key.", "example": "jane%40example.com" }, "required": true, "description": "The contact’s email address (URL-encoded). Email is the contact primary key.", "name": "email", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsPatchRequest" }, "examples": { "fields": { "summary": "Change fields", "value": { "fields": { "firstName": "Janet", "plan": "scale" } } }, "consent": { "summary": "Record consent", "value": { "consent": { "source": "api", "policyVersion": "2026-03", "evidence": "imported from the CRM opt-in list" } } } } } } }, "responses": { "200": { "description": "Patched.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsPatchResponse" }, "example": { "contact": { "email": "jane@example.com", "firstName": "Janet", "lastName": "Doe", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "enterprise", "revenue": 4200 } }, "updated": [ "firstName", "plan", "consent" ], "warnings": [] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`CONTACT_NOT_FOUND`: No contact with that email exists in the brand.\n\n`FIELD_NOT_FOUND`: No custom field definition with that name exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "contactNotFound": { "summary": "CONTACT_NOT_FOUND", "value": { "error": { "code": "CONTACT_NOT_FOUND", "type": "not_found", "message": "No contact with that email exists in the brand.", "suggestion": "Create the contact first with POST /v1/contacts.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "fieldNotFound": { "summary": "FIELD_NOT_FOUND", "value": { "error": { "code": "FIELD_NOT_FOUND", "type": "not_found", "message": "No custom field definition with that name exists in the brand.", "suggestion": "Create the field first with POST /v1/fields or use a field that already exists.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`FIELD_TYPE_MISMATCH`: A value does not match the declared type of its custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "fieldTypeMismatch": { "summary": "FIELD_TYPE_MISMATCH", "value": { "error": { "code": "FIELD_TYPE_MISMATCH", "type": "conflict", "message": "A value does not match the declared type of its custom field.", "suggestion": "Send a value that matches the field's type. To change the type, delete the field (this clears its value on every contact) and create it again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`BATCH_TOO_LARGE`: A batch write exceeds the per-request row cap.\n\n`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.\n\n`FIELD_NAME_COLLISION`: Two keys in one request name the same contact field (`plan` and `Plan`, `team_size` and `Team Size`), so one value would be lost.\n\n`RESUBSCRIBE_NOT_ALLOWED`: The write set `subscribed` to true on a contact who unsubscribed, and Brew never re-subscribes an opt-out through the API, MCP or an import; `details.email` names the contact.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "batchTooLarge": { "summary": "BATCH_TOO_LARGE", "value": { "error": { "code": "BATCH_TOO_LARGE", "type": "invalid_request", "message": "A batch write exceeds the per-request row cap.", "suggestion": "Split the request into smaller batches and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "fieldNameCollision": { "summary": "FIELD_NAME_COLLISION", "value": { "error": { "code": "FIELD_NAME_COLLISION", "type": "invalid_request", "message": "Two keys in one request name the same contact field (`plan` and `Plan`, `team_size` and `Team Size`), so one value would be lost.", "suggestion": "Send one of the two keys, or rename one so it names a different field.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "resubscribeNotAllowed": { "summary": "RESUBSCRIBE_NOT_ALLOWED", "value": { "error": { "code": "RESUBSCRIBE_NOT_ALLOWED", "type": "invalid_request", "message": "The write set `subscribed` to true on a contact who unsubscribed, and Brew never re-subscribes an opt-out through the API, MCP or an import; `details.email` names the contact.", "suggestion": "Drop `subscribed` from the write; a contact who opted out re-subscribes through their own action, or from their contact page in the Brew app once they ask.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "contacts.write_single" }, "delete": { "operationId": "deleteContact", "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "Deletes the contact. Idempotent — an unknown email resolves with `deleted: false`. For bulk deletion use `POST /v1/contacts/batch-delete`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The contact’s email address (URL-encoded). Email is the contact primary key.", "example": "jane%40example.com" }, "required": true, "description": "The contact’s email address (URL-encoded). Email is the contact primary key.", "name": "email", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDeleteResponse" }, "example": { "email": "jane@example.com", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "contacts.write_single" }, "get": { "operationId": "getContact", "tags": [ "Contacts" ], "summary": "Get a contact", "description": "Reads one contact as the bare `Contact` row: core columns, `subscribed`, `consent`, validation state and `customFields`.\n\n**Use when** checking whether an address exists, reading its consent record, or inspecting its custom fields before a send.\n\n**Input** `email` in the path (URL-encoded; matched case-insensitively). `include=openProfile` attaches `openProfile`: the smart-send open-time profile, 48 UTC half-hour open counts (`histogram`), `totalOpens`, `lastOpenedAt`, and once there is enough history `bestOpenMinuteUtc`, `bestSendMinuteUtc` and `confidence`; `null` when the contact has no opens folded yet. It is not bot detection: machine opens cannot be told apart in it (per-event classification is on `getEventsAnalytics`). It needs the `emails` scope as well as `contacts`.\n\n**Returns** `200` with the row.\n\n**Errors** `404 CONTACT_NOT_FOUND` when no contact carries that address; `403 INSUFFICIENT_PERMISSIONS` when `include=openProfile` is asked for without the `emails` scope; `400 INVALID_REQUEST` for an unknown `include` token.\n\n**See also** `listContacts`, `updateContact`, `deleteContact`, `upsertContacts`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The contact’s email address (URL-encoded). Email is the contact primary key.", "example": "jane%40example.com" }, "required": true, "description": "The contact’s email address (URL-encoded). Email is the contact primary key.", "name": "email", "in": "path" }, { "schema": { "type": "string", "description": "Expansions: `openProfile` attaches the contact's smart-send open-time profile (needs the `emails` permission as well).", "x-brew-include-tokens": [ "openProfile" ] }, "required": false, "description": "Expansions: `openProfile` attaches the contact's smart-send open-time profile (needs the `emails` permission as well).", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The contact row, with `openProfile` when `include=openProfile`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactWithOpenProfile" }, "example": { "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "enterprise", "revenue": 4200 } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`CONTACT_NOT_FOUND`: No contact with that email exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "contactNotFound": { "summary": "CONTACT_NOT_FOUND", "value": { "error": { "code": "CONTACT_NOT_FOUND", "type": "not_found", "message": "No contact with that email exists in the brand.", "suggestion": "Create the contact first with POST /v1/contacts.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "contacts.read" } }, "/v1/contacts/search": { "post": { "operationId": "searchContacts", "tags": [ "Contacts" ], "summary": "Get contacts", "description": "The single \"Get Contacts\" read. Structured search over the brand’s contacts: free-text `search`, `filters` (`{ field, operator, value }` combined with `logic: \"and\" | \"or\" | \"none\"`; the allowed operators depend on the field’s type — see the `operator` schema — and an unsupported pairing is a `400`, never a dropped clause), `sort` + `order`, and cursor pagination. Returns `{ data, pagination }`.\n\n`search` with a whole email address matches only that contact, like `filters: [{ field: \"email\", operator: \"equals\", value: \"…\" }]` or `GET /v1/contacts/{email}`. Any other `search` text matches the contacts whose email, first or last name contains any of its words, which can include other contacts, in `sort` order, so act on a contact found by its address. Omit every filter to list everything.\n\nPass an optional `audienceId` to scope the search to a saved audience’s members — its stored filter set is evaluated as one unit with its own `logicalOperator` (an OR audience stays an OR) and then ANDed with `filters`, so the page is exactly who a send to that audience reaches (an unknown / cross-brand id, or an audience a send would refuse → `400`).\n\nSet `count: true` to get `{ count }` instead of a page.\n\n`include: [\"openProfile\"]` attaches each returned contact’s smart-send open-time profile (`openProfile`, as on `getContact`; `null` when they have no opens yet). Each row costs one profile read, so a page then holds at most 10 contacts (`pagination.limit` reports the size read); it needs the `emails` scope as well (`403 INSUFFICIENT_PERMISSIONS` without it) and is refused with `count: true`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsSearchRequest" }, "examples": { "filtered": { "summary": "Filter + sort", "value": { "filters": [ { "field": "plan", "operator": "equals", "value": "enterprise" } ], "sort": "createdAt", "order": "desc", "limit": 50 } }, "count": { "summary": "Count only", "value": { "filters": [ { "field": "subscribed", "operator": "equals", "value": "true" } ], "count": true } } } } } }, "responses": { "200": { "description": "A page of matching contacts — or `{ count }` when `count: true`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsSearchSuccessResponse" }, "examples": { "page": { "summary": "Result page", "value": { "data": [ { "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "enterprise", "revenue": 4200 } }, { "email": "john@example.com", "firstName": "John", "lastName": "Smith", "subscribed": true, "validationStatus": "valid", "lastValidatedAt": "2026-04-08T12:01:00.000Z", "suppressed": false, "suppressedReason": null, "consent": { "source": "form", "capturedAt": "2026-04-08T12:00:00.000Z", "policyVersion": "2026-03" }, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "importId": null, "customFields": { "plan": "starter" } } ], "pagination": { "limit": 50, "cursor": "eyJsYXN0SWQiOiIxMjMiLCJsYXN0U29ydCI6MTcxMjU5MjAwMDAwMH0=", "hasMore": true } } }, "count": { "summary": "Count mode", "value": { "count": 1284 } } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`FIELD_TYPE_MISMATCH`: A value does not match the declared type of its custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "fieldTypeMismatch": { "summary": "FIELD_TYPE_MISMATCH", "value": { "error": { "code": "FIELD_TYPE_MISMATCH", "type": "conflict", "message": "A value does not match the declared type of its custom field.", "suggestion": "Send a value that matches the field's type. To change the type, delete the field (this clears its value on every contact) and create it again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`BATCH_TOO_LARGE`: A batch write exceeds the per-request row cap.\n\n`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "batchTooLarge": { "summary": "BATCH_TOO_LARGE", "value": { "error": { "code": "BATCH_TOO_LARGE", "type": "invalid_request", "message": "A batch write exceeds the per-request row cap.", "suggestion": "Split the request into smaller batches and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "contacts.read" } }, "/v1/contacts/validate": { "post": { "operationId": "validateContacts", "tags": [ "Contacts" ], "summary": "Validate email deliverability", "description": "Batch deliverability check (up to 100 addresses) — run BEFORE importing or sending. Each address is classified `valid` (safe), `risky` (deliverable but flagged — e.g. role account, disposable, catch-all), or `invalid` (undeliverable / do-not-send), with a machine-readable `reason` and a `didYouMean` typo correction when applicable. Partial outages retain the legacy `status: risky` with `checkOutcome: unavailable` (not a completed risky verdict) and preserve the stored verdict. `persistence` reports matched, modified and failed update-only writes; validation never grants subscription or clears suppression. Cost: 2 credits PER ADDRESS (`X-Credit-Cost` = 2 × the number of addresses), charged ONLY on success — if the check cannot complete for the whole batch, the call returns `503` (transient outages are retryable; configuration failures need support) and is NOT billed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsValidateRequest" }, "example": { "emails": [ "ada@gmail.com", "temp@mailinator.com", "admin@stripe.com" ] } } } }, "responses": { "200": { "description": "One classification row per input address.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsValidateResponse" }, "example": { "data": [ { "email": "ada@gmail.com", "valid": true, "status": "valid", "checkOutcome": "completed" }, { "email": "temp@mailinator.com", "valid": false, "status": "invalid", "checkOutcome": "completed", "reason": "undeliverable" }, { "email": "ada@gmial.com", "valid": false, "status": "risky", "checkOutcome": "completed", "reason": "unknown", "didYouMean": "ada@gmail.com" }, { "email": "admin@stripe.com", "valid": false, "status": "risky", "checkOutcome": "completed", "reason": "role_address" } ], "persistence": { "matched": 4, "modified": 4, "failed": 0 } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "content.transform" } }, "/v1/contacts/import-csv": { "post": { "operationId": "importContactsCsv", "tags": [ "Contacts" ], "summary": "Bulk-import contacts from CSV", "description": "Parse a raw CSV string and upsert the rows as contacts (≤ 1000). By default each column header maps to the custom field its name folds to, the same camelCase name `POST /v1/contacts` stores (`Plan` → `plan`, `Team Size` → `teamSize`); `email` is required. A header that spells a core field, ignoring case, spaces, `_` and `-`, or whose field key equals it (`First.Name`), maps to it: `Email`, `First Name`, `Last Name` and `Subscribed` fill `email`, `firstName`, `lastName` and `subscribed`. Pass `mapping` to remap single columns; the columns it leaves out keep their default mapping, `\"\"` leaves a column out, and a key that names no column is a `400`. Two columns that land on one custom field (`plan,Plan`: names fold as on `POST /v1/contacts`) are a `422 FIELD_NAME_COLLISION` before any row is read: map one to another name or leave it out with `\"\"`. A core field that `mapping` fills is filled from that column alone: another column whose default would fill it is left out with a `CSV_COLUMN_IGNORED` warning. Rows with a missing/invalid email are SKIPPED (counted in `summary.skipped`), not errored; disposable-domain rows are imported with `validationStatus: \"risky\"` (deliverable but flagged). Returns the same `{ summary, fieldsCreated, errors, warnings }` as batch-create plus `importId` — `207` when some rows fail. The batch is listed in Import History under `fileName` (optional), and each contact it writes carries `importId` until a later import touches it (filter on it to list them; deleting the import in the app removes the contacts it created). For rows you already hold as JSON, use `POST /v1/contacts/import`.\n\nCSV cells are text: a column mapped onto an EXISTING field is coerced to that field's type (dates → epoch ms, `1,234` → 1234, `yes`/`no` → booleans), and a cell that cannot be coerced (`$49` in a number column) fails ITS row with a per-row `errors[]` entry (`code: FIELD_TYPE_MISMATCH`, `field`) while the other rows still land. A converted cell adds a `warnings[]` entry (`code: FIELD_TYPE_COERCED`, `field`, `from`, `to`); a date written to a `date` field is not reported. An undeclared column is created as a `string` field unless every value is an ISO date (→ `date`); predeclare `number` / `bool` columns with `POST /v1/fields`. A column whose field Brew manages (`Created At`, `Validation Status`) is not imported and adds a `warnings[]` entry (`code: CSV_COLUMN_IGNORED`, `field` names the column).\n\nA date column is read in ONE day/month order: the order its own dates prove (a day over 12 anywhere in the column, `13/04/2026`), else `dateOrder` (`day_first` reads `03/04/2026` as 3 April, `month_first` as 4 March), else month/day with a `warnings[]` entry (`code: DATE_ORDER_ASSUMED`, `field`). Dotted dates (`03.04.2026`) are day-first. ISO (`2026-04-03`), Unix seconds or milliseconds, month names (`3 Apr 2026`), year-first (`2026/04/03`) and compact (`20260403`) dates need no order. Convert to `YYYY-MM-DD` to be unambiguous.\n\nA `subscribed` column reads true/false and ESP status words (`unsubscribed`, `cleaned`, `blocklisted`, `transactional`, `active`, …). An opt-out unsubscribes the contact, new or existing (with `onConflict: \"skip\"` an existing contact is left unchanged, and its `CONTACT_EXISTS_SKIPPED` warning says so). A word that is not a subscription status (`maybe`) fails its row (`code: FIELD_TYPE_MISMATCH`, `field: subscribed`) instead of importing the contact subscribed. A subscribed value only applies to new contacts: a row that asks to re-subscribe a contact who opted out keeps its other fields and adds a `warnings[]` entry (`code: RESUBSCRIBE_SKIPPED`, `email`).\n\nTwo opt-in modes. `dryRun: true` returns the response this import would return (`summary`, `errors`, row `warnings`, `fieldsCreated` as fields it would create) with `dryRun: true` and no `importId`, and writes nothing: no contacts, field definitions or Import History entry; `validate` is not run and nothing is charged. Insert vs update is decided by the same address match the write uses, so a real run right after returns the same counts. `onConflict: \"skip\"` only creates missing contacts: each existing contact is left unchanged (an opt-out row included), counted in `summary.skipped` with a `CONTACT_EXISTS_SKIPPED` warning naming its `row`. Either way `inserted + updated + failed + skipped = total`. A dry run cannot foresee failures that only happen while writing (a concurrent change, a database refusal), so the real run can still fail where the preview succeeded. With `validate: true`, inline checks are still metered per submitted row, rows `skip` left alone included; a request that leaves no address to check is not charged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsImportCsvRequest" }, "example": { "csv": "email,firstName,lastName\nada@example.com,Ada,Lovelace\ngrace@example.com,Grace,Hopper", "mapping": { "email": "email", "firstName": "firstName", "lastName": "lastName" }, "fileName": "customers.csv" } } } }, "responses": { "200": { "description": "Import summary (all rows valid).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsImportResponse" }, "example": { "summary": { "inserted": 2, "updated": 0, "failed": 0, "skipped": 0, "total": 2 }, "fieldsCreated": [], "errors": [], "warnings": [], "importId": "imp_01JABCDEF0123456789XYZ" } } } }, "207": { "description": "Partial success — some rows failed validation.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsImportResponse" }, "example": { "summary": { "inserted": 1, "updated": 0, "failed": 1, "skipped": 2, "total": 4 }, "fieldsCreated": [], "errors": [ { "email": "john@example.com", "row": 2, "code": "FIELD_TYPE_MISMATCH", "field": "customFields.plan", "message": "Field 'customFields.plan' is type 'number' but received string '$49'." } ], "warnings": [ { "code": "CSV_ROW_SKIPPED", "row": 3, "message": "Row 3 has no email address, so it was skipped." }, { "code": "CSV_ROW_SKIPPED", "row": 4, "email": "not-an-email", "message": "Row 4 holds 'not-an-email', which is not a valid email address, so it was skipped." } ], "importId": "imp_01JABCDEF0123456789XYZ" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`FIELD_NAME_COLLISION`: Two keys in one request name the same contact field (`plan` and `Plan`, `team_size` and `Team Size`), so one value would be lost.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "fieldNameCollision": { "summary": "FIELD_NAME_COLLISION", "value": { "error": { "code": "FIELD_NAME_COLLISION", "type": "invalid_request", "message": "Two keys in one request name the same contact field (`plan` and `Plan`, `team_size` and `Team Size`), so one value would be lost.", "suggestion": "Send one of the two keys, or rename one so it names a different field.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "contacts.write_batch" } }, "/v1/contacts/import": { "post": { "operationId": "importContacts", "tags": [ "Contacts" ], "summary": "Bulk-import contacts from JSON", "description": "Create or update up to 1000 contacts from JSON rows and record them as one Import History batch: the JSON twin of `POST /v1/contacts/import-csv`. Rows take the batch-create shape (`email`, `firstName`, `lastName`, `subscribed`, `customFields`, `consent`) and follow its rules: a missing or invalid email, or an address repeated in the batch, fails its row (`errors[]`, `207`) while the others land. New contacts are subscribed unless the row says `subscribed: false`; re-subscribing a contact who opted out keeps its other fields and adds a `RESUBSCRIBE_SKIPPED` warning.\n\nThe batch is listed in Import History under `fileName` (optional), and each contact it writes carries the returned `importId` until a later import touches it (filter on it to list them; deleting the import in the app removes the contacts it created). `POST /v1/contacts` with `contacts[]` writes the same rows without an Import History entry, for recurring syncs.\n\nTwo opt-in modes. `dryRun: true` returns the response this import would return (`summary`, `errors`, row `warnings`, `fieldsCreated` as fields it would create) with `dryRun: true` and no `importId`, and writes nothing: no contacts, field definitions or Import History entry; `validate` is not run and nothing is charged. Insert vs update is decided by the same address match the write uses, so a real run right after returns the same counts. `onConflict: \"skip\"` only creates missing contacts: each existing contact is left unchanged (an opt-out row included), counted in `summary.skipped` with a `CONTACT_EXISTS_SKIPPED` warning naming its `row`. Either way `inserted + updated + failed + skipped = total`. A dry run cannot foresee failures that only happen while writing (a concurrent change, a database refusal), so the real run can still fail where the preview succeeded. With `validate: true`, inline checks are still metered per submitted row, rows `skip` left alone included; a request that leaves no address to check is not charged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsImportRequest" }, "example": { "contacts": [ { "email": "ada@example.com", "firstName": "Ada" }, { "email": "grace@example.com", "firstName": "Grace", "customFields": { "plan": "pro" } } ], "consent": { "source": "import" }, "fileName": "crm-export.json" } } } }, "responses": { "200": { "description": "Import summary (all rows valid).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsImportResponse" }, "example": { "summary": { "inserted": 2, "updated": 0, "failed": 0, "skipped": 0, "total": 2 }, "fieldsCreated": [ "plan" ], "errors": [], "warnings": [], "importId": "imp_01JABCDEF0123456789XYZ" } } } }, "207": { "description": "Partial success — some rows failed validation.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsImportResponse" }, "example": { "summary": { "inserted": 1, "updated": 0, "failed": 1, "skipped": 0, "total": 2 }, "fieldsCreated": [], "errors": [ { "email": "not-an-email", "row": 2, "code": "INVALID_EMAIL", "message": "'not-an-email' is not a valid email address." } ], "warnings": [], "importId": "imp_01JABCDEF0123456789XYZ" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "contacts.write_batch" } }, "/v1/contacts/batch-delete": { "post": { "operationId": "batchDeleteContacts", "tags": [ "Contacts" ], "summary": "Batch-delete contacts", "description": "Deletes up to 1000 contacts by email. Returns the deleted count plus `notFound[]` for emails that had no contact. Addresses are lookup keys, not re-validated: any address a contact was stored under matches, and one that matches nothing lands in `notFound[]` instead of failing the batch.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsBatchDeleteRequest" }, "example": { "emails": [ "jane@example.com", "gone@example.com" ] } } } }, "responses": { "200": { "description": "Batch delete applied.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsBatchDeleteResponse" }, "example": { "deletedCount": 1, "notFound": [ "gone@example.com" ] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`BATCH_TOO_LARGE`: A batch write exceeds the per-request row cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "batchTooLarge": { "summary": "BATCH_TOO_LARGE", "value": { "error": { "code": "BATCH_TOO_LARGE", "type": "invalid_request", "message": "A batch write exceeds the per-request row cap.", "suggestion": "Split the request into smaller batches and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "contacts.write_batch" } }, "/v1/fields": { "get": { "operationId": "listContactFields", "tags": [ "Contact Fields" ], "summary": "List contact fields", "description": "Lists core contact columns and custom field definitions under `{ data, pagination }`. Use the field names in audience filters, contact search, and `{{ field | fallback }}` merge tags. Add `?include=coverage` to decorate each row with fill stats — the % of contacts holding a non-empty value plus the most common values (sampled; `approximate: true` on large populations) — and optionally `audienceId` to scope those stats to one saved audience. Check coverage before personalizing on a field so most recipients see a real value, not the fallback.", "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Opt-in expansion: `coverage` adds per-field fill stats (percent of contacts with a non-empty value + top values).", "schema": { "type": "string", "enum": [ "coverage" ], "x-brew-include-tokens": [ "coverage" ] } }, { "name": "audienceId", "in": "query", "required": false, "description": "Scope `include=coverage` stats to one saved audience (`404 AUDIENCE_NOT_FOUND` on an unknown / cross-brand id). Ignored without the include.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor echoed from the previous page’s `pagination.cursor`. Omit for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of field definitions.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldsGetResponse" }, "example": { "data": [ { "fieldName": "email", "fieldType": "string", "label": "Email", "isCore": true, "isFilterable": true, "isSortable": true, "isSearchable": true }, { "fieldName": "plan", "fieldType": "string", "label": "Plan", "isCore": false, "isFilterable": true, "isSortable": true, "isSearchable": false, "coverage": { "percent": 62, "approximate": true, "topValues": [ { "value": "scale", "count": 610, "percent": 51 }, { "value": "starter", "count": 420, "percent": 35 } ], "dominantValue": "scale" } } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_NOT_FOUND`: No audience with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceNotFound": { "summary": "AUDIENCE_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_NOT_FOUND", "type": "not_found", "message": "No audience with that id exists in the brand.", "suggestion": "Use GET /v1/audiences to choose a saved audience, or send to explicit addresses.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "fields.read" }, "post": { "operationId": "createContactField", "tags": [ "Contact Fields" ], "summary": "Create a contact field", "description": "Creates a custom field definition (`{ fieldName, fieldType: \"string\" | \"number\" | \"date\" | \"bool\" }`). A `number` field holds values up to 9007199254740991 (2^53 - 1) in magnitude, the largest integer it stores exactly; a contact write with a larger JSON number is refused (in a `string` field too, since it arrives already rounded), so send 64-bit ids and counters as JSON strings to a `string` field. Returns `201` with the bare definition. (Contact upserts also auto-create unknown fields — explicit creation is for pinning the type up front.)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldsPostRequest" }, "example": { "fieldName": "plan", "fieldType": "string" } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFieldDefinition" }, "example": { "fieldName": "plan", "fieldType": "string", "label": "Plan", "isCore": false, "isFilterable": true, "isSortable": true, "isSearchable": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "fields.write" } }, "/v1/fields/{fieldName}": { "get": { "operationId": "getContactField", "tags": [ "Contact Fields" ], "summary": "Get a contact field", "description": "Reads one contact field definition (a core column or a custom field) as the bare row: `fieldName`, `fieldType` and its filter/sort/search flags.\n\n**Use when** confirming a merge-tag key or a filter field exists before using it.\n\n**Input** `fieldName` in the path.\n\n**Returns** `200` with the row.\n\n**Errors** `404 FIELD_NOT_FOUND` when no definition carries that name.\n\n**See also** `listContactFields`, `createContactField`, `deleteContactField`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The custom field name (URL-encoded when needed).", "example": "plan" }, "required": true, "description": "The custom field name (URL-encoded when needed).", "name": "fieldName", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The field definition.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFieldDefinition" }, "example": { "fieldName": "plan", "fieldType": "string" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`FIELD_NOT_FOUND`: No custom field definition with that name exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "fieldNotFound": { "summary": "FIELD_NOT_FOUND", "value": { "error": { "code": "FIELD_NOT_FOUND", "type": "not_found", "message": "No custom field definition with that name exists in the brand.", "suggestion": "Create the field first with POST /v1/fields or use a field that already exists.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "fields.read" }, "delete": { "operationId": "deleteContactField", "tags": [ "Contact Fields" ], "summary": "Delete a contact field", "description": "Deletes a custom field and clears its value from every contact. The values cannot be recovered, and a field created later with the same name starts empty.\n\n**Use when** a field and its values should go. To change a field's type, delete it, create it again with the new type and re-import the values. Check saved audiences first: afterwards a filter on the field sees no value, so `is_empty` and `not_exists` match every contact.\n\n**Input** `fieldName` in the path.\n\n**Returns** `200` with `{ fieldName, deleted }`. A name with no custom field resolves `deleted: false` and clears nothing, so repeating the call is safe. The three legacy consent fields (`marketingConsentSource`, `marketingConsentCapturedAt`, `marketingConsentPolicyVersion`) lose only the definition: their values stay, because they still serve as consent evidence.\n\n**Errors** `422 CORE_FIELD_IMMUTABLE` for a core column. `409 AUDIENCE_BUILD_ACTIVE` for the hidden field of an event-derived audience that is still building; retry once the build finishes.\n\n**See also** `listContactFields`, `getContactField`, `createContactField`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The custom field name (URL-encoded when needed).", "example": "plan" }, "required": true, "description": "The custom field name (URL-encoded when needed).", "name": "fieldName", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldsDeleteResponse" }, "example": { "fieldName": "plan", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`AUDIENCE_BUILD_ACTIVE`: The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceBuildActive": { "summary": "AUDIENCE_BUILD_ACTIVE", "value": { "error": { "code": "AUDIENCE_BUILD_ACTIVE", "type": "conflict", "message": "The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.", "suggestion": "Wait for the build to finish (poll GET /v1/audiences/{audienceId}?include=build), then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "fields.write" } }, "/v1/audiences": { "get": { "operationId": "listAudiences", "tags": [ "Audiences" ], "summary": "List audiences", "description": "Lists the brand’s saved audiences under `{ data, pagination }`. Each row carries its contact `filters`, a member `count` and ISO timestamps; an audience is the recipient target for `createSend`. Stale counts are refreshed on a best-effort basis. If a recount fails or reaches its time budget, the saved count is returned. Use `GET /v1/audiences/{audienceId}?include=count` for an on-demand count.\n\n**Use when** choosing the `audienceId` for a campaign or an automation launch.\n\n**Input** `limit` and `cursor`.\n\n**Returns** `200` with a page of `Audience` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key.\n\n**See also** `getAudience` (live `count`, `build`), `createAudience`, `searchContacts`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Only audiences whose name contains this text (case-insensitive)." }, "required": false, "description": "Only audiences whose name contains this text (case-insensitive).", "name": "search", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of audiences.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesListResponse" }, "example": { "data": [ { "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "audienceName": "Nordic Founders", "filters": { "filters": [ { "field": "country", "operator": "equals", "value": "NO" } ], "logicalOperator": "and" }, "count": 1284, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "audiences", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "audiences.read" }, "post": { "operationId": "createAudience", "tags": [ "Audiences" ], "summary": "Create an audience", "description": "Creates a saved audience from a name + filter set (`{ filters: [{ field, operator, value? }], logicalOperator: \"and\" | \"or\" }`). Returns `201` with the bare audience row. An `email in [...]` clause listing more than 100 addresses is converted automatically: a fresh date custom field is stamped on the listed EXISTING contacts and the stored filter becomes `customFields. is_not_empty` (a snapshot — addresses with no contact record are skipped), reported back as `emailListMaterializations`; 10,000 addresses max per clause.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesPostRequest" }, "example": { "name": "Nordic Founders", "filters": { "filters": [ { "field": "country", "operator": "equals", "value": "NO" } ], "logicalOperator": "and" } } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceWriteResponse" }, "example": { "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "audienceName": "Nordic Founders", "filters": { "filters": [ { "field": "country", "operator": "equals", "value": "NO" } ], "logicalOperator": "and" }, "count": 1284, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`FIELD_TYPE_MISMATCH`: A value does not match the declared type of its custom field.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "fieldTypeMismatch": { "summary": "FIELD_TYPE_MISMATCH", "value": { "error": { "code": "FIELD_TYPE_MISMATCH", "type": "conflict", "message": "A value does not match the declared type of its custom field.", "suggestion": "Send a value that matches the field's type. To change the type, delete the field (this clears its value on every contact) and create it again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "audiences", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "audiences.write" } }, "/v1/audiences/{audienceId}": { "get": { "operationId": "getAudience", "tags": [ "Audiences" ], "summary": "Get an audience", "description": "Reads one saved audience as the bare `Audience` row.\n\n**Use when** sizing a send, checking an audience’s filters, or polling an event-cohort build started by `createAudienceFromEvents`.\n\n**Input** `audienceId` in the path; `include=count` replaces the cached `count` with a freshly computed member total and `include=build` attaches the latest event-cohort build status (comma-separate both).\n\n**Returns** `200` with the row; `build` is present only when requested and a build exists.\n\n**Errors** `404 AUDIENCE_NOT_FOUND` for an unknown or cross-brand id; `400 INVALID_REQUEST` for an unknown `include` token.\n\n**See also** `listAudiences`, `updateAudience`, `duplicateAudience`, `createSend`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "example": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f" }, "required": true, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "name": "audienceId", "in": "path" }, { "schema": { "type": "string", "description": "Comma-separated expansions: `count` recomputes the live member total; `build` attaches the latest event-cohort build status.", "x-brew-include-tokens": [ "count", "build" ] }, "required": false, "description": "Comma-separated expansions: `count` recomputes the live member total; `build` attaches the latest event-cohort build status.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The audience row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" }, "example": { "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "audienceName": "Nordic Founders", "filters": { "filters": [ { "field": "country", "operator": "equals", "value": "NO" } ], "logicalOperator": "and" }, "count": 1284, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_NOT_FOUND`: No audience with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceNotFound": { "summary": "AUDIENCE_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_NOT_FOUND", "type": "not_found", "message": "No audience with that id exists in the brand.", "suggestion": "Use GET /v1/audiences to choose a saved audience, or send to explicit addresses.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "audiences", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "audiences.read" }, "patch": { "operationId": "updateAudience", "tags": [ "Audiences" ], "summary": "Update an audience", "description": "Updates `name` and/or `filters` (at least one required). Pass the latest row’s `updatedAt` as `expectedUpdatedAt` to reject stale read-modify-write edits. Returns the bare updated row. Replacement filters follow the same email-list rule as create: an `email in [...]` clause over 100 addresses is converted into a stamped custom-field snapshot (a fresh field per update), reported as `emailListMaterializations`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "example": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f" }, "required": true, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "name": "audienceId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesPatchRequest" }, "example": { "name": "Nordic Founders (active)" } } } }, "responses": { "200": { "description": "Updated.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceWriteResponse" }, "example": { "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "audienceName": "Nordic Founders", "filters": { "filters": [ { "field": "country", "operator": "equals", "value": "NO" } ], "logicalOperator": "and" }, "count": 1284, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_NOT_FOUND`: No audience with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceNotFound": { "summary": "AUDIENCE_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_NOT_FOUND", "type": "not_found", "message": "No audience with that id exists in the brand.", "suggestion": "Use GET /v1/audiences to choose a saved audience, or send to explicit addresses.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`AUDIENCE_BUILD_ACTIVE`: The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.\n\n`AUDIENCE_EDIT_CONFLICT`: The audience changed since it was read; the update was not applied.\n\n`AUDIENCE_MEMBERSHIP_NOT_EXPRESSIBLE`: The audience’s filters cannot add or remove these contacts exactly (for example, AND-combined conditions, or an OR branch that would still match).\n\n`FIELD_TYPE_MISMATCH`: A value does not match the declared type of its custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceBuildActive": { "summary": "AUDIENCE_BUILD_ACTIVE", "value": { "error": { "code": "AUDIENCE_BUILD_ACTIVE", "type": "conflict", "message": "The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.", "suggestion": "Wait for the build to finish (poll GET /v1/audiences/{audienceId}?include=build), then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "audienceEditConflict": { "summary": "AUDIENCE_EDIT_CONFLICT", "value": { "error": { "code": "AUDIENCE_EDIT_CONFLICT", "type": "conflict", "message": "The audience changed since it was read; the update was not applied.", "suggestion": "Reload the latest audience filters and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "audienceMembershipNotExpressible": { "summary": "AUDIENCE_MEMBERSHIP_NOT_EXPRESSIBLE", "value": { "error": { "code": "AUDIENCE_MEMBERSHIP_NOT_EXPRESSIBLE", "type": "conflict", "message": "The audience’s filters cannot add or remove these contacts exactly (for example, AND-combined conditions, or an OR branch that would still match).", "suggestion": "Rewrite the audience with `filters` instead, or create a separate audience for these contacts.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "fieldTypeMismatch": { "summary": "FIELD_TYPE_MISMATCH", "value": { "error": { "code": "FIELD_TYPE_MISMATCH", "type": "conflict", "message": "A value does not match the declared type of its custom field.", "suggestion": "Send a value that matches the field's type. To change the type, delete the field (this clears its value on every contact) and create it again.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`CORE_FIELD_IMMUTABLE`: The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "coreFieldImmutable": { "summary": "CORE_FIELD_IMMUTABLE", "value": { "error": { "code": "CORE_FIELD_IMMUTABLE", "type": "invalid_request", "message": "The field is a core contact column and cannot be created, changed, or deleted as a custom field.", "suggestion": "Use a custom field name instead.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "audiences", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "audiences.write" }, "delete": { "operationId": "deleteAudience", "tags": [ "Audiences" ], "summary": "Delete an audience", "description": "Deletes the audience. Idempotent — an unknown id resolves with `deleted: false`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "example": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f" }, "required": true, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "name": "audienceId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesDeleteResponse" }, "example": { "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`AUDIENCE_BUILD_ACTIVE`: The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceBuildActive": { "summary": "AUDIENCE_BUILD_ACTIVE", "value": { "error": { "code": "AUDIENCE_BUILD_ACTIVE", "type": "conflict", "message": "The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.", "suggestion": "Wait for the build to finish (poll GET /v1/audiences/{audienceId}?include=build), then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "audiences", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "audiences.write" } }, "/v1/audiences/from-events": { "post": { "operationId": "createAudienceFromEvents", "tags": [ "Audiences" ], "summary": "Create an audience from analytics events", "description": "Creates a frozen audience snapshot from the same membership filters as `/events`: 1–10 canonical event types, an absolute window up to 90 days (`from` may be omitted when `sendId` is set — the window then derives from that send), optional send/email ids, multi-select automation/audience ids, recipient include/exclude rules, and the machine-click policy. `cohort.exclude` builds the COMPLEMENT instead: every member of a base audience (default: the send's audience; `\"all\"` = the whole brand) who did NOT match — the base's clauses are copied at build time AND the cohort field must be empty — which is how to re-send after a cancelled send (`eventTypes: [\"sent\"]`, the `sendId`, `exclude: {}`). Every call generates a unique date field; each matching existing contact stores its latest matching-event timestamp. Returns `201` immediately with `materializationStatus: pending` plus build progress. The audience is unavailable for campaign, smart-send, and automation delivery until the status becomes `ready`. Failed/partial/stale builds remain non-sendable and partial values are cleaned. Poll `GET /v1/audiences/{audienceId}?include=build`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesFromEventsRequest" }, "example": { "cohort": { "eventTypes": [ "opened" ], "from": "2026-07-04T00:00:00.000Z", "to": "2026-08-03T00:00:00.000Z" } } } } }, "responses": { "201": { "description": "Created. The audience exists immediately; `build` tracks the background stamping run.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesFromEventsResponse" }, "example": { "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "audienceName": "Openers · Jul 4 – Aug 3, 2026", "filters": { "filters": [ { "field": "customFields.openedJul4Aug3", "operator": "is_not_empty", "type": "date" } ], "logicalOperator": "and" }, "count": 0, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z", "materializationStatus": "pending", "build": { "jobId": "kh7c2m4q8n9w2p1x7c3b5v6n9h7s2d4f", "status": "pending", "cohort": { "eventTypes": [ "opened" ], "from": "2026-07-04T00:00:00.000Z", "to": "2026-08-03T00:00:00.000Z" }, "field": { "key": "openedJul4Aug3", "label": "Opened Jul 4 – Aug 3", "type": "date" }, "counts": { "eventsScanned": 0 }, "enqueuedAt": "2026-08-03T12:00:00.000Z" } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`AUDIENCE_BUILD_ALREADY_ACTIVE`: Too many audience builds are already in progress for the workspace.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceBuildAlreadyActive": { "summary": "AUDIENCE_BUILD_ALREADY_ACTIVE", "value": { "error": { "code": "AUDIENCE_BUILD_ALREADY_ACTIVE", "type": "conflict", "message": "Too many audience builds are already in progress for the workspace.", "suggestion": "Wait for the in-flight builds to finish (poll GET /v1/audiences/{audienceId}?include=build), then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 10 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 10, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "contacts", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "contacts.write_batch" } }, "/v1/audiences/{audienceId}/duplicate": { "post": { "operationId": "duplicateAudience", "tags": [ "Audiences" ], "summary": "Duplicate an audience", "description": "Creates a deterministic copy of the saved audience’s live filters with a server-generated “(copy)” name. Contacts are not copied; both audiences resolve against the same contact records.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "example": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f" }, "required": true, "description": "Audience id (opaque Convex document id) returned by `POST /v1/audiences` and listed by `GET /v1/audiences`.", "name": "audienceId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "201": { "description": "Copied.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" }, "example": { "audienceId": "mh8b9x5r9n1k3p2y8c4d6w7q1j9t3f5g", "audienceName": "Nordic Founders (copy)", "filters": { "filters": [ { "field": "country", "operator": "equals", "value": "NO" } ], "logicalOperator": "and" }, "count": 1284, "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`AUDIENCE_NOT_FOUND`: No audience with that id exists in the brand.\n\n`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceNotFound": { "summary": "AUDIENCE_NOT_FOUND", "value": { "error": { "code": "AUDIENCE_NOT_FOUND", "type": "not_found", "message": "No audience with that id exists in the brand.", "suggestion": "Use GET /v1/audiences to choose a saved audience, or send to explicit addresses.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`AUDIENCE_BUILD_ACTIVE`: The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.\n\n`AUDIENCE_EDIT_CONFLICT`: The audience changed since it was read; the update was not applied.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "audienceBuildActive": { "summary": "AUDIENCE_BUILD_ACTIVE", "value": { "error": { "code": "AUDIENCE_BUILD_ACTIVE", "type": "conflict", "message": "The audience is being built, so neither it nor the hidden field its build stamps can be changed, copied, or deleted yet.", "suggestion": "Wait for the build to finish (poll GET /v1/audiences/{audienceId}?include=build), then retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "audienceEditConflict": { "summary": "AUDIENCE_EDIT_CONFLICT", "value": { "error": { "code": "AUDIENCE_EDIT_CONFLICT", "type": "conflict", "message": "The audience changed since it was read; the update was not applied.", "suggestion": "Reload the latest audience filters and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "audiences", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "audiences.write" } }, "/v1/domains": { "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "List domains", "description": "Lists the brand’s sending domains under `{ data, pagination }`: ALL lifecycle states by default, so a caller mid-verification can read `pending` rows and their DNS `records`.\n\n**Use when** picking the `domainId` for `createSend` or a sendEmail node, or reading DNS records to publish.\n\n**Input** `sendableOnly=true` keeps only verified, send-ready domains (the set valid for sends and automation `sendEmail` nodes); `sendingPurpose` keeps one purpose (campaigns and audience sends require `marketing`; automation sendEmail nodes accept both); `limit` and `cursor`.\n\n**Returns** `200` with a page of `Domain` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or purpose.\n\n**See also** `getDomain`, `addDomain`, `verifyDomain`, `getDomainHealth`.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, only verified send-ready domains." }, "required": false, "description": "When `true`, only verified send-ready domains.", "name": "sendableOnly", "in": "query" }, { "schema": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "Filter listed domains by purpose. Use marketing for campaigns and automations." }, "required": false, "description": "Filter listed domains by purpose. Use marketing for campaigns and automations.", "name": "sendingPurpose", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of domains.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsListResponse" }, "example": { "data": [ { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainUrl": "https://send.example.com", "name": "send.example.com", "region": "us-east-1", "status": "pending", "sendingEnabled": true, "sendable": false, "sendingPurpose": "marketing", "records": [ { "record": "DKIM", "name": "resend._domainkey", "type": "TXT", "ttl": "Auto", "status": "pending", "value": "p=MIGfMA0..." } ], "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.read" }, "post": { "operationId": "addDomain", "tags": [ "Domains" ], "summary": "Add a domain", "description": "Registers a sending domain with the provider. Optional `sendingPurpose` is `marketing` (default; campaigns, audience sends, automations) or `transactional` (event-triggered automation mail — no unsubscribe link required, merely-unsubscribed contacts still receive it). Returns `201` with the bare row in `status: \"pending\"` plus the DNS `records` to publish. Once the records are live, call `POST /v1/domains/{domainId}/verify` until `sendable: true`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsPostRequest" }, "example": { "name": "send.example.com" } } } }, "responses": { "201": { "description": "Added — publish the returned DNS records, then verify.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainUrl": "https://send.example.com", "name": "send.example.com", "region": "us-east-1", "status": "pending", "sendingEnabled": true, "sendable": false, "sendingPurpose": "marketing", "records": [ { "record": "DKIM", "name": "resend._domainkey", "type": "TXT", "ttl": "Auto", "status": "pending", "value": "p=MIGfMA0..." } ], "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`DOMAIN_ALREADY_EXISTS`: The brand already has this domain.\n\n`DOMAIN_CLAIMED_ELSEWHERE`: The domain is registered in another Brew workspace.\n\n`DOMAIN_OTHER_BRAND`: The domain is attached to a different brand in this workspace.\n\n`DOMAIN_VERIFIED_ELSEWHERE`: Another workspace already verified this domain.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainAlreadyExists": { "summary": "DOMAIN_ALREADY_EXISTS", "value": { "error": { "code": "DOMAIN_ALREADY_EXISTS", "type": "conflict", "message": "The brand already has this domain.", "suggestion": "Fetch the existing domain with GET /v1/domains.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainClaimedElsewhere": { "summary": "DOMAIN_CLAIMED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_CLAIMED_ELSEWHERE", "type": "conflict", "message": "The domain is registered in another Brew workspace.", "suggestion": "Remove it from the other workspace first, or contact support to move it.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainOtherBrand": { "summary": "DOMAIN_OTHER_BRAND", "value": { "error": { "code": "DOMAIN_OTHER_BRAND", "type": "conflict", "message": "The domain is attached to a different brand in this workspace.", "suggestion": "Use that brand’s credential, or remove the domain from it first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerifiedElsewhere": { "summary": "DOMAIN_VERIFIED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_VERIFIED_ELSEWHERE", "type": "conflict", "message": "Another workspace already verified this domain.", "suggestion": "Only unverified domains can be reclaimed. Remove it from the other workspace first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`DOMAIN_PROVIDER_ERROR`: The sending provider rejected the domain.\n\n`DOMAIN_VERIFICATION_FAILED`: The DNS records are not published yet, so verification did not pass.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainProviderError": { "summary": "DOMAIN_PROVIDER_ERROR", "value": { "error": { "code": "DOMAIN_PROVIDER_ERROR", "type": "invalid_request", "message": "The sending provider rejected the domain.", "suggestion": "Check the domain name is a valid, registrable domain and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerificationFailed": { "summary": "DOMAIN_VERIFICATION_FAILED", "value": { "error": { "code": "DOMAIN_VERIFICATION_FAILED", "type": "invalid_request", "message": "The DNS records are not published yet, so verification did not pass.", "suggestion": "Confirm the DNS records from GET /v1/domains are published, then retry verify.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" } }, "/v1/domains/{domainId}": { "get": { "operationId": "getDomain", "tags": [ "Domains" ], "summary": "Get a domain", "description": "Reads one sending domain as the bare `Domain` row: verification `status`, DNS `records`, `sendable`, `sendingPurpose` and the `openTracking`/`clickTracking` flags. Sender defaults are write-only here: the row does not echo them.\n\n**Use when** polling verification after `verifyDomain`, or confirming a domain before a send.\n\n**Input** `domainId` in the path.\n\n**Returns** `200` with the row.\n\n**Errors** `404 DOMAIN_NOT_FOUND` for an unknown or cross-brand id.\n\n**See also** `listDomains`, `verifyDomain`, `getDomainHealth`, `updateDomain`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The domain row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainUrl": "https://send.example.com", "name": "send.example.com", "region": "us-east-1", "status": "pending", "sendingEnabled": true, "sendable": false, "sendingPurpose": "marketing", "records": [ { "record": "DKIM", "name": "resend._domainkey", "type": "TXT", "ttl": "Auto", "status": "pending", "value": "p=MIGfMA0..." } ], "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.read" }, "patch": { "operationId": "updateDomain", "tags": [ "Domains" ], "summary": "Update domain settings", "description": "Updates sender defaults (`defaultSenderName`, `defaultFromEmail`, `defaultReplyToEmail`) and/or `sendingPurpose` — at least one required. `defaultFromEmail` is the sender MAILBOX (the text before `@`) — the host is always this domain, so a full address is accepted and reduced to its local part; `defaultReplyToEmail`, by contrast, is a whole address. Live gates fail closed if a campaign still points at a transactional domain. Verification is its own action: `POST /v1/domains/{domainId}/verify`. Returns the bare updated row.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsPatchRequest" }, "example": { "defaultSenderName": "Brew", "defaultFromEmail": "hello" } } } }, "responses": { "200": { "description": "Updated.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainUrl": "https://send.example.com", "name": "send.example.com", "region": "us-east-1", "status": "pending", "sendingEnabled": true, "sendable": false, "sendingPurpose": "marketing", "records": [ { "record": "DKIM", "name": "resend._domainkey", "type": "TXT", "ttl": "Auto", "status": "pending", "value": "p=MIGfMA0..." } ], "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`DOMAIN_ALREADY_EXISTS`: The brand already has this domain.\n\n`DOMAIN_CLAIMED_ELSEWHERE`: The domain is registered in another Brew workspace.\n\n`DOMAIN_OTHER_BRAND`: The domain is attached to a different brand in this workspace.\n\n`DOMAIN_VERIFIED_ELSEWHERE`: Another workspace already verified this domain.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainAlreadyExists": { "summary": "DOMAIN_ALREADY_EXISTS", "value": { "error": { "code": "DOMAIN_ALREADY_EXISTS", "type": "conflict", "message": "The brand already has this domain.", "suggestion": "Fetch the existing domain with GET /v1/domains.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainClaimedElsewhere": { "summary": "DOMAIN_CLAIMED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_CLAIMED_ELSEWHERE", "type": "conflict", "message": "The domain is registered in another Brew workspace.", "suggestion": "Remove it from the other workspace first, or contact support to move it.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainOtherBrand": { "summary": "DOMAIN_OTHER_BRAND", "value": { "error": { "code": "DOMAIN_OTHER_BRAND", "type": "conflict", "message": "The domain is attached to a different brand in this workspace.", "suggestion": "Use that brand’s credential, or remove the domain from it first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerifiedElsewhere": { "summary": "DOMAIN_VERIFIED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_VERIFIED_ELSEWHERE", "type": "conflict", "message": "Another workspace already verified this domain.", "suggestion": "Only unverified domains can be reclaimed. Remove it from the other workspace first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PROVIDER_ERROR`: The sending provider rejected the domain.\n\n`DOMAIN_VERIFICATION_FAILED`: The DNS records are not published yet, so verification did not pass.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainProviderError": { "summary": "DOMAIN_PROVIDER_ERROR", "value": { "error": { "code": "DOMAIN_PROVIDER_ERROR", "type": "invalid_request", "message": "The sending provider rejected the domain.", "suggestion": "Check the domain name is a valid, registrable domain and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerificationFailed": { "summary": "DOMAIN_VERIFICATION_FAILED", "value": { "error": { "code": "DOMAIN_VERIFICATION_FAILED", "type": "invalid_request", "message": "The DNS records are not published yet, so verification did not pass.", "suggestion": "Confirm the DNS records from GET /v1/domains are published, then retry verify.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" }, "delete": { "operationId": "deleteDomain", "tags": [ "Domains" ], "summary": "Delete a domain", "description": "Removes the domain from the provider and deletes the local row. Idempotent — an unknown id resolves with `deleted: false`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or already gone).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsDeleteResponse" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`DOMAIN_ALREADY_EXISTS`: The brand already has this domain.\n\n`DOMAIN_CLAIMED_ELSEWHERE`: The domain is registered in another Brew workspace.\n\n`DOMAIN_OTHER_BRAND`: The domain is attached to a different brand in this workspace.\n\n`DOMAIN_VERIFIED_ELSEWHERE`: Another workspace already verified this domain.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainAlreadyExists": { "summary": "DOMAIN_ALREADY_EXISTS", "value": { "error": { "code": "DOMAIN_ALREADY_EXISTS", "type": "conflict", "message": "The brand already has this domain.", "suggestion": "Fetch the existing domain with GET /v1/domains.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainClaimedElsewhere": { "summary": "DOMAIN_CLAIMED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_CLAIMED_ELSEWHERE", "type": "conflict", "message": "The domain is registered in another Brew workspace.", "suggestion": "Remove it from the other workspace first, or contact support to move it.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainOtherBrand": { "summary": "DOMAIN_OTHER_BRAND", "value": { "error": { "code": "DOMAIN_OTHER_BRAND", "type": "conflict", "message": "The domain is attached to a different brand in this workspace.", "suggestion": "Use that brand’s credential, or remove the domain from it first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerifiedElsewhere": { "summary": "DOMAIN_VERIFIED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_VERIFIED_ELSEWHERE", "type": "conflict", "message": "Another workspace already verified this domain.", "suggestion": "Only unverified domains can be reclaimed. Remove it from the other workspace first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PROVIDER_ERROR`: The sending provider rejected the domain.\n\n`DOMAIN_VERIFICATION_FAILED`: The DNS records are not published yet, so verification did not pass.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainProviderError": { "summary": "DOMAIN_PROVIDER_ERROR", "value": { "error": { "code": "DOMAIN_PROVIDER_ERROR", "type": "invalid_request", "message": "The sending provider rejected the domain.", "suggestion": "Check the domain name is a valid, registrable domain and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerificationFailed": { "summary": "DOMAIN_VERIFICATION_FAILED", "value": { "error": { "code": "DOMAIN_VERIFICATION_FAILED", "type": "invalid_request", "message": "The DNS records are not published yet, so verification did not pass.", "suggestion": "Confirm the DNS records from GET /v1/domains are published, then retry verify.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" } }, "/v1/domains/{domainId}/verify": { "post": { "operationId": "verifyDomain", "tags": [ "Domains" ], "summary": "Verify a domain", "description": "Re-checks the DNS records with the provider and refreshes the row. Empty body. Safe to poll — keep calling until `sendable: true` (DNS propagation can take minutes to hours). Returns the bare refreshed row.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The refreshed domain row.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainUrl": "https://send.example.com", "name": "send.example.com", "region": "us-east-1", "status": "verified", "sendingEnabled": true, "sendable": true, "sendingPurpose": "marketing", "records": [ { "record": "DKIM", "name": "resend._domainkey", "type": "TXT", "ttl": "Auto", "status": "pending", "value": "p=MIGfMA0..." } ], "createdAt": "2026-04-08T12:34:56.789Z", "updatedAt": "2026-04-08T12:34:56.789Z", "verifiedAt": "2026-04-08T13:00:00.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`DOMAIN_ALREADY_EXISTS`: The brand already has this domain.\n\n`DOMAIN_CLAIMED_ELSEWHERE`: The domain is registered in another Brew workspace.\n\n`DOMAIN_OTHER_BRAND`: The domain is attached to a different brand in this workspace.\n\n`DOMAIN_VERIFIED_ELSEWHERE`: Another workspace already verified this domain.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainAlreadyExists": { "summary": "DOMAIN_ALREADY_EXISTS", "value": { "error": { "code": "DOMAIN_ALREADY_EXISTS", "type": "conflict", "message": "The brand already has this domain.", "suggestion": "Fetch the existing domain with GET /v1/domains.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainClaimedElsewhere": { "summary": "DOMAIN_CLAIMED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_CLAIMED_ELSEWHERE", "type": "conflict", "message": "The domain is registered in another Brew workspace.", "suggestion": "Remove it from the other workspace first, or contact support to move it.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainOtherBrand": { "summary": "DOMAIN_OTHER_BRAND", "value": { "error": { "code": "DOMAIN_OTHER_BRAND", "type": "conflict", "message": "The domain is attached to a different brand in this workspace.", "suggestion": "Use that brand’s credential, or remove the domain from it first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerifiedElsewhere": { "summary": "DOMAIN_VERIFIED_ELSEWHERE", "value": { "error": { "code": "DOMAIN_VERIFIED_ELSEWHERE", "type": "conflict", "message": "Another workspace already verified this domain.", "suggestion": "Only unverified domains can be reclaimed. Remove it from the other workspace first.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`DOMAIN_PROVIDER_ERROR`: The sending provider rejected the domain.\n\n`DOMAIN_VERIFICATION_FAILED`: The DNS records are not published yet, so verification did not pass.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainProviderError": { "summary": "DOMAIN_PROVIDER_ERROR", "value": { "error": { "code": "DOMAIN_PROVIDER_ERROR", "type": "invalid_request", "message": "The sending provider rejected the domain.", "suggestion": "Check the domain name is a valid, registrable domain and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainVerificationFailed": { "summary": "DOMAIN_VERIFICATION_FAILED", "value": { "error": { "code": "DOMAIN_VERIFICATION_FAILED", "type": "invalid_request", "message": "The DNS records are not published yet, so verification did not pass.", "suggestion": "Confirm the DNS records from GET /v1/domains are published, then retry verify.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" } }, "/v1/domains/{domainId}/unsubscribes": { "get": { "operationId": "listDomainUnsubscribes", "tags": [ "Domains" ], "summary": "List a domain's unsubscribes", "description": "Every MARKETING sending domain is its own unsubscribe list, keyed by the domain's host inside the brand's contacts. Returns one page (`{ data, pagination }`, newest first). Each row carries `scope`: `domain` (on this host's list), `all` (the brand-wide opt-out — `subscribed: false` on the contact, which blocks every marketing send) or `both`. `?scope=` narrows; `?q=` searches by address. Transactional domains own no list → `422 DOMAIN_PURPOSE_NOT_ALLOWED`.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "An address (anything with `@`) matches that address — exactly once complete, by prefix while partial. Other text is a word search over the address and the contact name.", "schema": { "type": "string", "maxLength": 320 } }, { "name": "scope", "in": "query", "required": false, "description": "Which opt-outs to include: `domain` = this host’s list only, `all` = the brand-wide opt-out only, `any` (default) = either.", "schema": { "type": "string", "enum": [ "any", "domain", "all" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor echoed from the previous page’s `pagination.cursor`. Omit for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of the domain’s unsubscribe list.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribesListResponse" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainHost": "send.example.com", "data": [ { "email": "jane@example.com", "scope": "domain", "unsubscribedAt": "2026-09-17T09:12:00.000Z", "source": "link", "sendId": "kh7c1w2m3n4p5q6r7s8t9u0v1w2x3y4z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.read" }, "post": { "operationId": "addDomainUnsubscribes", "tags": [ "Domains" ], "summary": "Add addresses to a domain's unsubscribe list", "description": "Suppresses up to 1,000 addresses from THIS marketing domain's mail. An existing contact is suppressed for this host only — sends from OTHER marketing domains still reach it; set `subscribed: false` on the contact for a brand-wide opt-out. An address with no contact is created already globally unsubscribed, so every marketing domain skips it (`summary.created`). Addresses already on the list count under `alreadyUnsubscribed`, never errored (idempotent); malformed ones are reported in `invalid` and skipped.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribesAddRequest" }, "example": { "emails": [ "jane@example.com", "sam@example.com" ] } } } }, "responses": { "200": { "description": "Per-address outcome summary.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribesAddResponse" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainHost": "send.example.com", "summary": { "received": 2, "added": 1, "alreadyUnsubscribed": 0, "created": 1, "invalid": 0 }, "invalid": [] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" } }, "/v1/domains/{domainId}/unsubscribes/{email}": { "delete": { "operationId": "removeDomainUnsubscribe", "tags": [ "Domains" ], "summary": "Remove an address from a domain's unsubscribe list", "description": "Takes one address off THIS domain's list (resubscribes it to this host only). Idempotent — `removed: false` when the address was not on the list. Never clears the brand-wide opt-out: `globallyUnsubscribed: true` means every marketing send still skips the contact until `PATCH /v1/contacts/{email}` sets `subscribed: true`. URL-encode the address.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "maxLength": 320, "description": "The address to take off the list (URL-encoded).", "example": "jane%40example.com" }, "required": true, "description": "The address to take off the list (URL-encoded).", "name": "email", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Removed (or was not listed).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribeRemoveResponse" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainHost": "send.example.com", "email": "jane@example.com", "removed": true, "globallyUnsubscribed": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" } }, "/v1/domains/{domainId}/unsubscribes/import": { "post": { "operationId": "importDomainUnsubscribes", "tags": [ "Domains" ], "summary": "Import a CSV into a domain's unsubscribe list", "description": "Migrates an unsubscribe list (another ESP's export) into THIS marketing domain's list. `csv` is the file text: an `email` header — or any column of addresses, or one headerless column; pass `column` to name the header when detection fails (`400` otherwise). Synchronous and bounded: 10,000 rows per call (`truncated: true` when the file carried more — split it across calls) and 2,000,000 characters (a longer `csv` is rejected as `400 INVALID_REQUEST`). Idempotent per address. An address with no contact row is created already globally unsubscribed, exactly as `POST /v1/domains/{domainId}/unsubscribes` does, so every marketing domain skips it. The contact CSV importer's `subscribed` column is the BRAND-WIDE flag — use this endpoint for per-domain opt-outs.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribesImportRequest" }, "example": { "csv": "email\njane@example.com\nsam@example.com\n" } } } }, "responses": { "200": { "description": "Import summary.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribesImportResponse" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainHost": "send.example.com", "summary": { "rows": 2, "added": 1, "alreadyUnsubscribed": 0, "created": 1, "skipped": 0 }, "skippedSample": [], "truncated": false, "column": "email" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE`: The request body exceeds the route cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadTooLarge": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "type": "invalid_request", "message": "The request body exceeds the route cap.", "suggestion": "Reduce the payload size and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "domains.write" } }, "/v1/domains/{domainId}/unsubscribes/export": { "get": { "operationId": "exportDomainUnsubscribes", "tags": [ "Domains" ], "summary": "Export a domain's unsubscribe list", "description": "The whole list as CSV text (`Email,Scope,Unsubscribed At,Source,Send ID`) inside the JSON envelope — the v1 transport is JSON-only. Capped at 50,000 rows or ~4 MB of CSV, whichever comes first, so the response stays under the platform body limit (`truncated: true` beyond; narrow with `?scope=`).", "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "Which opt-outs to include: `domain` = this host’s list only, `all` = the brand-wide opt-out only, `any` (default) = either.", "schema": { "type": "string", "enum": [ "any", "domain", "all" ] } }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "CSV text plus counts.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUnsubscribesExportResponse" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "domainHost": "send.example.com", "csv": "Email,Scope,Unsubscribed At,Source,Send ID\r\njane@example.com,domain,2026-09-17T09:12:00.000Z,link,kh7c1w2m3n4p5q6r7s8t9u0v1w2x3y4z\r\n", "rowCount": 1, "truncated": false } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`DOMAIN_PURPOSE_NOT_ALLOWED`: The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "domainPurposeNotAllowed": { "summary": "DOMAIN_PURPOSE_NOT_ALLOWED", "value": { "error": { "code": "DOMAIN_PURPOSE_NOT_ALLOWED", "type": "invalid_request", "message": "The sending domain is admitted for a different purpose than this send (marketing vs transactional).", "suggestion": "Use a marketing domain for campaigns and audience sends. For transactional flows, wire the design into a published automation with a trigger and fire POST /v1/automations/triggers/{triggerEventId}/fire.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.read" } }, "/v1/domains/{domainId}/health": { "get": { "operationId": "getDomainHealth", "tags": [ "Domains" ], "summary": "Get domain health", "description": "The domain's deliverability health in one FREE read: a `verdict` (`healthy` / `at_risk` / `critical`) with actionable `signals`, DNS/auth state incl. DMARC, active percentage-based gradual sends, sampled bounce/complaint activity from campaign and automation sends, workspace reputation, and inbox-placement history. No bounce or complaint threshold is attached to a gradual-send configuration. `include=scoreHistory` adds `scoreHistory`: up to 50 saved score snapshots, newest first (score, grade, confidence, the event that saved it, and each pillar's score and weight); only snapshots saved under this brand count, searched among the domain's newest 500, so a domain that moved between brands can show fewer. `include=scoreRuns` adds `scoreRuns`: the last 5 automated domain score runs (the 5-variant seed check), each with its status in the shared run vocabulary, the score it ended on, the credits it cost and every variant's placement test.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "example": "kx7bkh53hasmfeh5kd7sqgykt187g8ww" }, "required": true, "description": "Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`.", "name": "domainId", "in": "path" }, { "schema": { "type": "string", "description": "Expansions: `scoreHistory` attaches up to 50 saved score snapshots, newest first; `scoreRuns` the last 5 automated domain score runs.", "x-brew-include-tokens": [ "scoreHistory", "scoreRuns" ] }, "required": false, "description": "Expansions: `scoreHistory` attaches up to 50 saved score snapshots, newest first; `scoreRuns` the last 5 automated domain score runs.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The aggregate health report.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainHealth" }, "example": { "domainId": "kx7bkh53hasmfeh5kd7sqgykt187g8ww", "name": "send.example.com", "status": "verified", "sendable": true, "verdict": "at_risk", "readiness": "ready_with_warnings", "score": { "placementMeasured": true, "value": 72, "grade": "fair", "confidence": "medium", "components": { "placement": { "score": 68, "weight": 0.35, "basis": "seed_test" }, "authentication": { "score": 100, "weight": 0.2, "basis": "dns" }, "reputation": { "score": 74, "weight": 0.2, "basis": "org_history" }, "content": { "score": 62, "weight": 0.15, "basis": "recent_sends" }, "posture": { "score": 55, "weight": 0.1, "basis": "warmup_stage" } }, "trend": { "direction": "up", "previousScore": 64, "previousComputedAt": "2026-06-21T09:00:00.000Z" } }, "authentication": { "spf": "verified", "dkim": "verified", "dmarc": "missing" }, "tracking": { "linksStatus": "live", "openTracking": true, "clickTracking": true }, "warmup": [ { "sendId": "W7nT1vPb9Ycr4Kq8ZxL2m", "currentTranche": 3, "sentSoFar": 175, "rampEndsAt": "2026-07-15T00:00:00.000Z" } ], "dailyVolume": [], "domainActivity": { "sampled": true, "sampleSendCount": 12, "sentCount": 2400, "bouncedCount": 31, "complainedCount": 1, "bounceRate": 0.0129, "complaintRate": 0.0004 }, "orgReputation": { "scope": "org", "totalSent": 18250, "bounceRate": 0.011, "complaintRate": 0.0003 }, "recentPlacementTests": [ { "testId": "ibp_2f1c9d8a", "emailId": "V1StGXR8_Z5jdHi6B-myT", "status": "completed", "overall": { "total": 41, "inbox": 33, "spam": 8, "missing": 0, "pending": 0 }, "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" }, "spamFilterFlagged": false, "createdAt": "2026-07-13T17:00:00.000Z" } ], "signals": [ { "id": "dmarc_missing", "severity": "warning", "summary": "No DMARC record is configured for this domain.", "suggestion": "Add a TXT record: _dmarc.send.example.com TXT \"v=DMARC1; p=reject; rua=mailto:dmarc@send.example.com\" — Gmail/Yahoo bulk-sender rules require DMARC. This policy blocks spoofing. Then re-verify the domain to pick it up." } ], "checkedAt": "2026-07-13T18:00:00.000Z" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`DOMAIN_NOT_FOUND`: No domain with that id exists in the brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "domainNotFound": { "summary": "DOMAIN_NOT_FOUND", "value": { "error": { "code": "DOMAIN_NOT_FOUND", "type": "not_found", "message": "No domain with that id exists in the brand.", "suggestion": "Use GET /v1/domains to choose a verified domain.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "domains", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "domains.read" } }, "/v1/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "List templates", "description": "Lists public templates under { data, pagination }. The default full representation includes HTML. Set representation=summary for metadata, previewImage, viewUrl, and referenceEmailId without HTML. Supports exact brand and category filters and a group filter (a browse group: every category in it); query matches title text or an exact template identifier. semantic ranks up to 200 matches using vector search; query additionally filters those matches when both are supplied. Browse defaults to 50 full rows or 20 summary rows. Brand and category match case-insensitively. Continue with pagination.cursor, including after an empty filtered page with hasMore=true. Templates are organization-wide references; pass referenceEmailId to POST /v1/emails to remix one. Set count=true for { count }, the number of templates matching brand, category and group (refreshed every 15 minutes), instead of rows; add groupBy=brand, groupBy=category or groupBy=group for per-value counts, largest first, 100 groups a page with the same pagination.cursor (count does not combine with semantic or query).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Only this brand's templates, by domain (e.g. `brew.new`); case-insensitive." }, "required": false, "description": "Only this brand's templates, by domain (e.g. `brew.new`); case-insensitive.", "name": "brand", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Email category, matched case-insensitively (unknown → empty page): welcome, onboarding, newsletter, content, event-invitation, event-reminder, event-recap, product-launch, product-update, product-pitch, promotional, cart-abandonment, re-engagement, subscription, feedback-request, referral, company-news, fundraising, order-confirmation, shipping-update, receipt, password-reset, verification, security-alert, account-update, notification, support, internal, business, general." }, "required": false, "description": "Email category, matched case-insensitively (unknown → empty page): welcome, onboarding, newsletter, content, event-invitation, event-reminder, event-recap, product-launch, product-update, product-pitch, promotional, cart-abandonment, re-engagement, subscription, feedback-request, referral, company-news, fundraising, order-confirmation, shipping-update, receipt, password-reset, verification, security-alert, account-update, notification, support, internal, business, general.", "name": "category", "in": "query" }, { "schema": { "type": "string", "enum": [ "welcome-onboarding", "newsletter", "content", "events", "product-news", "sales", "retention", "company", "transactional", "internal", "other" ], "description": "A browse group: every category in it (e.g. `events` = invitations, reminders and recaps)." }, "required": false, "description": "A browse group: every category in it (e.g. `events` = invitations, reminders and recaps).", "name": "group", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Rank by relevance to this text instead of newest first (top 200; `brand`/`category` still narrow)." }, "required": false, "description": "Rank by relevance to this text instead of newest first (top 200; `brand`/`category` still narrow).", "name": "semantic", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Case-insensitive title substring or exact public template identifier. Applied within semantic results when semantic is supplied." }, "required": false, "description": "Case-insensitive title substring or exact public template identifier. Applied within semantic results when semantic is supplied.", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "full", "summary" ], "description": "Full rows include HTML. Summary rows include selection metadata and links only." }, "required": false, "description": "Full rows include HTML. Summary rows include selection metadata and links only.", "name": "representation", "in": "query" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Return `{ count }`, the number of templates matching `brand`/`category`/`group`, instead of rows. Not with `semantic` or `query`." }, "required": false, "description": "Return `{ count }`, the number of templates matching `brand`/`category`/`group`, instead of rows. Not with `semantic` or `query`.", "name": "count", "in": "query" }, { "schema": { "type": "string", "enum": [ "brand", "category", "group" ], "description": "With `count: true`: also count per brand, category or group, largest first, 100 groups a page; continue with `cursor`.", "x-brew-group-by-tokens": [ "brand", "category", "group" ] }, "required": false, "description": "With `count: true`: also count per brand, category or group, largest first, 100 groups a page; continue with `cursor`.", "name": "groupBy", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size, 1–100 (default 50: each row carries its full HTML).", "example": 50 }, "required": false, "description": "Page size, 1–100 (default 50: each row carries its full HTML).", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A page of templates matching the filters, or their counts when count=true.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplatesListResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "brand": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "minLength": 1, "format": "date-time" }, "referenceEmailId": { "type": "string", "minLength": 1 }, "viewUrl": { "type": "string", "format": "uri" } }, "required": [ "emailId", "title", "previewImage", "updatedAt", "referenceEmailId", "viewUrl" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "description": "Templates matching `brand`/`category`." }, "groupBy": { "type": "string", "enum": [ "brand", "category", "group" ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "The brand domain, category or group; pass it back as the filter of the same name (`brand`, `category` or `group`)." }, "name": { "type": "string", "minLength": 1, "description": "The brand's curated display name, when it has one." }, "count": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "value", "count" ], "additionalProperties": false }, "description": "With `groupBy`: up to 100 groups, largest first." }, "groupCount": { "type": "integer", "minimum": 0, "description": "Distinct brands or categories across every page." }, "ungroupedCount": { "type": "integer", "minimum": 0, "description": "Matching templates with no brand (or no category), so in no group." }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "count" ], "additionalProperties": false } ] }, "example": { "data": [ { "emailId": "seed-vercel-newsletter", "title": "Vercel Newsletter", "category": "newsletter", "brand": "vercel.com", "html": "…", "previewImage": "https://storage.example.com/templates/seed.png", "updatedAt": "2026-04-08T00:00:00.000Z" } ], "pagination": { "limit": 50, "cursor": "eyJ…", "hasMore": true } } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "templates.read" } }, "/v1/templates/{templateId}": { "get": { "operationId": "getTemplate", "tags": [ "Templates" ], "summary": "Get a public template", "description": "Returns metadata, preview and canonical links, and referenceEmailId for one public template. Add include=html to inspect its rendered content. Large HTML is returned as a downloadable content.url instead of truncated JSON.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": true, "name": "templateId", "in": "path" }, { "schema": { "type": "string", "enum": [ "html" ], "description": "Expansions: `html` adds the rendered HTML; a large page arrives as a `content.url` download link instead.", "x-brew-include-tokens": [ "html" ] }, "required": false, "description": "Expansions: `html` adds the rendered HTML; a large page arrives as a `content.url` download link instead.", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Template details and optional rendered content.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "brand": { "type": "string", "minLength": 1 }, "previewImage": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "minLength": 1, "format": "date-time" }, "referenceEmailId": { "type": "string", "minLength": 1 }, "viewUrl": { "type": "string", "format": "uri" }, "templateId": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "content": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "mimeType": { "type": "string", "enum": [ "text/html" ] }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "url", "mimeType", "bytes" ], "additionalProperties": false } }, "required": [ "emailId", "title", "previewImage", "updatedAt", "referenceEmailId", "viewUrl", "templateId" ], "additionalProperties": false } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`TEMPLATE_NOT_FOUND`: No public template matches that id.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "templateNotFound": { "summary": "TEMPLATE_NOT_FOUND", "value": { "error": { "code": "TEMPLATE_NOT_FOUND", "type": "not_found", "message": "No public template matches that id.", "suggestion": "List templates with GET /v1/templates and use a returned emailId as the templateId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "templates.read" } }, "/v1/flows": { "get": { "operationId": "listFlows", "tags": [ "Templates" ], "summary": "List flows", "description": "Lists public email flows, one brand’s real onboarding or newsletter sequence with the day each email landed, as cards under `{ data, pagination, total }`. Organization-wide: the same bounded corpus the gallery shows (a few hundred flows), paged with `limit`/`cursor`.\n\n**Use when** studying how real brands sequence email to plan or remix an automation, or finding the `slug` to read one flow in full.\n\n**Input** `brand` (exact domain), `category`, `type` (`signup` | `newsletter`), `sort` (`newest` | `emails` | `span` | `remixes`), or `semantic` for relevance-ranked search (then `sort` is ignored).\n\n**Returns** `200` with flow cards and `total`, the number of flows the query matches across every page (filters narrow it; `semantic` only orders it), so one `limit=1` call counts them. `isTotalExact` is false when the read was cut at 500 flows (the newest, or the 500 nearest a `semantic` query; filters apply after it), and `total` is then a floor. A card never carries `anchor` or `steps`; every card carries the `slug` that `getFlow` takes. A flow holds at most 12 steps: capture keeps the first 12 and cuts the tail, so `emailCount: 12` means twelve **or more** were sent.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or value; `503 SERVICE_UNAVAILABLE` when `semantic` search cannot run (no index, or its kill switch); retry without `semantic`.\n\n**See also** `getFlow`, `listTemplates`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Exact brand domain filter for LIST, e.g. `brew.new`." }, "required": false, "description": "Exact brand domain filter for LIST, e.g. `brew.new`.", "name": "brand", "in": "query" }, { "schema": { "type": "string", "enum": [ "verification", "transactional", "direct_sales", "welcome", "promotion", "newsletter", "education", "abandoned_cart", "winback", "other" ], "description": "Filter LIST by the flow’s dominant step category (`welcome`, `newsletter`, `promotion`, `education`, …)." }, "required": false, "description": "Filter LIST by the flow’s dominant step category (`welcome`, `newsletter`, `promotion`, `education`, …).", "name": "category", "in": "query" }, { "schema": { "type": "string", "enum": [ "newsletter", "signup" ], "description": "Filter LIST by how the sequence starts: `signup` (after creating an account) or `newsletter` (after subscribing)." }, "required": false, "description": "Filter LIST by how the sequence starts: `signup` (after creating an account) or `newsletter` (after subscribing).", "name": "type", "in": "query" }, { "schema": { "type": "string", "enum": [ "onboarding", "trial", "events", "product_updates", "promotions" ], "description": "Filter LIST by the flow’s kind: what the sequence is for." }, "required": false, "description": "Filter LIST by the flow’s kind: what the sequence is for.", "name": "kind", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Semantic search over what the sequences are about — “developer onboarding drip”, “trial expiry win-back”. Results come back in relevance order and `sort` is ignored." }, "required": false, "description": "Semantic search over what the sequences are about — “developer onboarding drip”, “trial expiry win-back”. Results come back in relevance order and `sort` is ignored.", "name": "semantic", "in": "query" }, { "schema": { "type": "string", "enum": [ "newest", "emails", "span", "remixes" ], "description": "LIST order: `newest` (default), `emails` (longest sequences first), `span` (sequences that run the longest first), `remixes` (most remixed first)." }, "required": false, "description": "LIST order: `newest` (default), `emails` (longest sequences first), `span` (sequences that run the longest first), `remixes` (most remixed first).", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A page of flow cards.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowsListResponse" }, "example": { "data": [ { "slug": "brew.new", "brand": { "name": "Brew", "logo": "https://cdn.brew.new/brand/fetched-logo/brew.new/logo.png" }, "title": "Brew onboarding flow", "type": "signup", "category": "welcome", "categoryLabel": "Welcome", "emailCount": 6, "spanDays": 14, "remixCount": 12, "previewImages": [ "https://cdn.brew.new/email-preview-brew-1.png", "https://cdn.brew.new/email-preview-brew-2.png", "https://cdn.brew.new/email-preview-brew-3.png" ], "publishedAt": "2026-09-01T12:00:00.000Z", "updatedAt": "2026-09-01T12:00:00.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false }, "total": 1, "isTotalExact": true } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: Semantic search over flows cannot run right now (no search index, or its kill switch), so a `semantic` query is refused rather than answered with an empty page.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "Semantic search over flows cannot run right now (no search index, or its kill switch), so a `semantic` query is refused rather than answered with an empty page.", "suggestion": "Retry without `semantic`: `brand`, `category`, `type` and `sort` still narrow and order the list.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "templates.read" } }, "/v1/flows/{slug}": { "get": { "operationId": "getFlow", "tags": [ "Templates" ], "summary": "Get a flow", "description": "One public flow as the bare row, with `anchor` (what day 0 means) and every step’s `subject`, `previewText`, `dayOffset`, `delayDays`, `category`, `previewImage` and `emailId`. Organization-wide.\n\n**Use when** reading a sequence in full before remixing it, or fetching each step’s rendered body.\n\n**Input** `slug` in the path: the brand domain from a `listFlows` card (case-insensitive). `include=html` adds each step’s rendered HTML, best-effort per step: a step whose body is no longer servable comes back without `html` rather than failing the flow.\n\n**Returns** `200` with the flow. A step’s `emailId` is a template reference: pass it as `referenceEmailId` on `POST /v1/emails`; for the body itself use `include=html` here (`GET /v1/templates` lists the gallery and takes no id).\n\n**Errors** `404 FLOW_NOT_FOUND` when the flow is unknown, private, or a step’s template was taken down (the anonymous read fails closed as a whole).\n\n**See also** `listFlows`, `generateEmail`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The flow’s brand domain. A bare domain returns the brand’s primary flow; one send stream’s flow is `?kind=` on it (or the path `/v1/flows/{domain}/{kind}`), as each `GET /v1/flows` row’s `slug` (`/`) names it. Case-insensitive.", "example": "brew.new" }, "required": true, "description": "The flow’s brand domain. A bare domain returns the brand’s primary flow; one send stream’s flow is `?kind=` on it (or the path `/v1/flows/{domain}/{kind}`), as each `GET /v1/flows` row’s `slug` (`/`) names it. Case-insensitive.", "name": "slug", "in": "path" }, { "schema": { "type": "string", "pattern": "^[a-z][a-z-]*[a-z](?:-[0-9]{1,3})?$", "description": "The flow's kind for a bare-domain `slug`, hyphenated: `onboarding`, `trial`, `events`, `product-updates`, `promotions`, optionally followed by `-2`, `-3`… for a brand's later flow of that kind." }, "required": false, "description": "The flow's kind for a bare-domain `slug`, hyphenated: `onboarding`, `trial`, `events`, `product-updates`, `promotions`, optionally followed by `-2`, `-3`… for a brand's later flow of that kind.", "name": "kind", "in": "query" }, { "schema": { "type": "string", "description": "Detail-only expansions, comma-separated. `html` adds each step’s rendered HTML. Rendered email is bulky — over MCP only the first step or two fit one response; the rest arrive without `html` and the summary says how many were kept. A step’s `emailId` is already a valid `referenceEmailId`, so reuse needs no body; for the bodies themselves call `GET /v1/flows/{slug}?include=html` over REST, which has no cap. Best-effort per step: a step whose body is no longer servable comes back without `html` rather than failing the flow.", "x-brew-include-tokens": [ "html" ] }, "required": false, "description": "Detail-only expansions, comma-separated. `html` adds each step’s rendered HTML. Rendered email is bulky — over MCP only the first step or two fit one response; the rest arrive without `html` and the summary says how many were kept. A step’s `emailId` is already a valid `referenceEmailId`, so reuse needs no body; for the bodies themselves call `GET /v1/flows/{slug}?include=html` over REST, which has no cap. Best-effort per step: a step whose body is no longer servable comes back without `html` rather than failing the flow.", "name": "include", "in": "query" } ], "responses": { "200": { "description": "The flow, with `anchor` and every step.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" }, "example": { "slug": "brew.new", "brand": { "name": "Brew", "logo": "https://cdn.brew.new/brand/fetched-logo/brew.new/logo.png" }, "title": "Brew onboarding flow", "type": "signup", "category": "welcome", "categoryLabel": "Welcome", "emailCount": 6, "spanDays": 14, "remixCount": 12, "previewImages": [ "https://cdn.brew.new/email-preview-brew-1.png", "https://cdn.brew.new/email-preview-brew-2.png", "https://cdn.brew.new/email-preview-brew-3.png" ], "publishedAt": "2026-09-01T12:00:00.000Z", "updatedAt": "2026-09-01T12:00:00.000Z", "anchor": "signedUpAt", "steps": [ { "order": 1, "dayOffset": 0, "delayDays": 0, "subject": "Welcome to Brew", "previewText": "Here’s how to set up your first brand.", "category": "welcome", "categoryLabel": "Welcome", "emailId": "pt1_k97nvhqe6xgyj67g58ajwj1tj58egexx", "previewImage": "https://cdn.brew.new/email-preview-brew-1.png" }, { "order": 2, "dayOffset": 2.1, "delayDays": 2.1, "subject": "Three templates to try today", "category": "education", "categoryLabel": "Education", "emailId": "pt1_k97s409kdrzbeajqffq6011wfn8egmdq", "previewImage": "https://cdn.brew.new/email-preview-brew-2.png" } ] } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`FLOW_NOT_FOUND`: No public flow matches that slug: it is unknown, private, or one of its steps is no longer public.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "flowNotFound": { "summary": "FLOW_NOT_FOUND", "value": { "error": { "code": "FLOW_NOT_FOUND", "type": "not_found", "message": "No public flow matches that slug: it is unknown, private, or one of its steps is no longer public.", "suggestion": "List flows with GET /v1/flows and use a returned slug (the brand domain, for example notion.com).", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "templates.read" } }, "/v1/brand": { "get": { "operationId": "getBrand", "tags": [ "Brand" ], "summary": "Get the brand bound to this API key", "description": "Returns the bare brand row for the single brand bound to the API key. Check `ready` (`status === \"completed\"`) before calling `POST /v1/emails`, which returns `422 BRAND_NOT_READY` until brand extraction finishes.\n\n`identity` is always returned: the brand name and tagline saved in Brew (`identity.brandName`, `identity.tagline`), plus its description, contact details and links. `domain` is the website the brand was extracted from, not its name.\n\nEmbed the design context in the same call with `?include=emailDesign,imageStyle,logos` (comma-separated). `emailDesign` / `imageStyle` are the markdown design system the email agent follows; `logos` is the CDN logo set. `include=identity` is still accepted and changes nothing. The paginated image library is a separate read (`GET /v1/brand/images`).", "parameters": [ { "schema": { "type": "string", "description": "Comma-separated sub-resources to embed: `emailDesign`, `imageStyle`, `logos`. `identity` (saved name, tagline, description, links) is always returned; naming it is accepted and changes nothing.", "x-brew-include-tokens": [ "identity", "emailDesign", "imageStyle", "logos" ] }, "required": false, "description": "Comma-separated sub-resources to embed: `emailDesign`, `imageStyle`, `logos`. `identity` (saved name, tagline, description, links) is always returned; naming it is accepted and changes nothing.", "name": "include", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The brand bound to this API key with its saved `identity`, plus any sub-resources named in `?include=`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandGetResponse" }, "example": { "brandId": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg", "domain": "vercel.com", "status": "completed", "ready": true, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z", "identity": { "brandName": "Vercel", "tagline": "Develop. Preview. Ship." } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brand.read" }, "patch": { "operationId": "updateBrand", "tags": [ "Brand" ], "summary": "Update brand identity + design system", "description": "Partial update of the writable design artifacts in one call. `identity` shallow-merges the provided fields; `emailDesign` / `imageStyle` replace the markdown design-system documents the email agent follows. Provide at least one. Returns the brand in the `GET /v1/brand` shape: `identity` always, plus the markdown documents the call wrote.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPatchRequest" }, "examples": { "identity": { "summary": "Merge identity fields", "value": { "identity": { "tagline": "Complete user management for modern apps." } } }, "design": { "summary": "Replace the email-design house style", "value": { "emailDesign": "# email-design.md\n\nUpdated house style…" } } } } } }, "responses": { "200": { "description": "The updated brand with its `identity`, plus the markdown documents the call wrote.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandGetResponse" }, "example": { "brandId": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg", "domain": "vercel.com", "status": "completed", "ready": true, "identity": { "brandName": "Vercel", "tagline": "Complete user management for modern apps." } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brand.write" } }, "/v1/brand/images": { "get": { "operationId": "getBrandImages", "tags": [ "Brand" ], "summary": "Get brand images", "description": "The brand’s asset library, as the Assets page shows it: logos, brand images (from the site or uploaded, including the social preview and site screenshot) and images made with Brew. Omit `?q=` to BROWSE it, newest first or `?sort=oldest`. Pass `?q=` for SEMANTIC search over brand and generated images (the query is embedded + vector-searched), in relevance order. Both are free. `?kind=logo|brand|generated` narrows either mode; logos are not searchable. Each row carries `assetId` (the id the app opens at `/assets?image=`), `kind`, `url` and what is known: description, dimensions, category, page, when it was added, and a logo’s variant. (`GET /v1/brand` returns the brand `identity`, and the smaller `emailDesign` / `imageStyle` / `logos` sub-resources embed with `?include=…`; images stay separate because they paginate.)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Semantic search over what the images show. Results come back in relevance order and `sort` is ignored. Logos are not searchable." }, "required": false, "description": "Semantic search over what the images show. Results come back in relevance order and `sort` is ignored. Logos are not searchable.", "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "logo", "brand", "generated" ], "description": "`logo`, `brand` (images from the site or uploaded, including the social preview and site screenshot) or `generated` (made with Brew). Omit for every kind." }, "required": false, "description": "`logo`, `brand` (images from the site or uploaded, including the social preview and site screenshot) or `generated` (made with Brew). Omit for every kind.", "name": "kind", "in": "query" }, { "schema": { "type": "string", "enum": [ "newest", "oldest" ], "description": "Browse order: `newest` (default) or `oldest`." }, "required": false, "description": "Browse order: `newest` (default) or `oldest`.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of brand assets (semantic results, in relevance order, when `?q=`).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandImagesResponse" }, "example": { "data": [ { "assetId": "5bc912f9", "kind": "generated", "url": "https://cdn.brew.new/cnt/abc.png", "description": "Clerk user-profile component", "width": 1056, "height": 1002, "addedAt": "2026-09-24T18:02:11.000Z" }, { "assetId": "1d4e7a20", "kind": "logo", "url": "https://cdn.brew.new/cnt/logo.svg", "logo": { "type": "logo", "theme": "dark", "background": "transparent", "format": "svg" } } ], "pagination": { "limit": 20, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brand.read" } }, "/v1/brand/images/{assetId}": { "delete": { "operationId": "deleteBrandImage", "tags": [ "Brand" ], "summary": "Delete a brand image", "description": "Removes one image from the brand library and from image search, as Delete image on the Assets page does. Its file stays hosted at its URL, so emails already using it keep rendering.\n\n**Use when** an image should no longer be offered for new designs. Confirm with the user first. Free; no credits are charged.\n\n**Input** `assetId` in the path, as `getBrandImages` returns it. One image per call.\n\n**Returns** `200` with `{ assetId, deleted }`. An `assetId` not in the library resolves `deleted: false` and changes nothing, so repeating the call is safe.\n\n**Errors** `400 INVALID_REQUEST` for a logo (manage logos on the Assets page) or a malformed `assetId`.\n\n**See also** `getBrandImages`, `addImage`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{8}$", "description": "The image to delete: the `assetId` that `GET /v1/brand/images` returns.", "example": "5bc912f9" }, "required": true, "description": "The image to delete: the `assetId` that `GET /v1/brand/images` returns.", "name": "assetId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Deleted (or not in the library).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandImageDeleteResponse" }, "example": { "assetId": "5bc912f9", "deleted": true } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brand.write" } }, "/v1/brands": { "get": { "operationId": "listBrands", "tags": [ "Brands" ], "summary": "List the brands this credential can reach", "description": "Organization-scoped credentials see every brand in the organization; a brand-scoped credential sees exactly the one brand it is bound to.\n\nThis is how an organization-scoped credential discovers the ids it passes in `X-Brand-Id` on every other endpoint.", "parameters": [ { "schema": { "type": "string", "enum": [ "extracting", "completed", "failed", "deleting" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "The brands this credential can reach.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandsListResponse" }, "example": { "data": [ { "brandId": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg", "domain": "vercel.com", "status": "completed", "ready": true, "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:05:00.000Z" }, { "brandId": "kx9d1p2qbrxy4nkm55ftz3lmvn21abcd", "domain": "acme.com", "status": "extracting", "ready": false, "progress": 0, "phase": "analyzing", "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brands.read" }, "post": { "operationId": "createBrand", "tags": [ "Brands" ], "summary": "Create a brand and start its extraction", "description": "Starts an asynchronous brand extraction that crawls the site and builds the design system. Returns `201` immediately with `status: \"extracting\"` — poll `GET /v1/brands/{brandId}` until `ready` is `true` (typically 1–3 minutes) before calling `POST /v1/emails`, which returns `422 BRAND_NOT_READY` until then.\n\nRequires an ORGANIZATION-scoped credential (`403 ORG_SCOPE_REQUIRED` otherwise) and the `brands` scope, which is NOT implied by `emails`.\n\nExtraction requires a non-empty credit balance but is not itself charged to your credits.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandsCreateRequest" }, "example": { "url": "acme.com", "instructions": "Use the product pages for tone. Primary brand color is the deep navy in the header." } } } }, "responses": { "201": { "description": "The brand was created and extraction started. Poll `extraction.statusUrl`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandsCreateResponse" }, "example": { "brandId": "kx9d1p2qbrxy4nkm55ftz3lmvn21abcd", "domain": "acme.com", "status": "extracting", "ready": false, "progress": 0, "phase": "analyzing", "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z", "extraction": { "chatId": "6f1c2b9e-6c2a-4a2e-9f5f-2b7d9a3e4c11", "statusUrl": "/v1/brands/kx9d1p2qbrxy4nkm55ftz3lmvn21abcd" } } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`BRAND_LIMIT_REACHED`: The plan allows no more brands.\n\n`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandLimitReached": { "summary": "BRAND_LIMIT_REACHED", "value": { "error": { "code": "BRAND_LIMIT_REACHED", "type": "payment_required", "message": "The plan allows no more brands.", "suggestion": "Delete an unused brand, or upgrade the plan to add more brands.", "docs": "https://docs.brew.new/api-reference/api/credits" } } }, "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).\n\n`ORG_SCOPE_REQUIRED`: The operation acts on the organization, so a brand-scoped credential cannot call it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "orgScopeRequired": { "summary": "ORG_SCOPE_REQUIRED", "value": { "error": { "code": "ORG_SCOPE_REQUIRED", "type": "authorization_error", "message": "The operation acts on the organization, so a brand-scoped credential cannot call it.", "suggestion": "Create an organization-scoped API key in Settings, API, or reconnect MCP at the organization level.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "409": { "description": "`BRAND_DOMAIN_CONFLICT`: The organization already has a brand for that domain.\n\n`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandDomainConflict": { "summary": "BRAND_DOMAIN_CONFLICT", "value": { "error": { "code": "BRAND_DOMAIN_CONFLICT", "type": "conflict", "message": "The organization already has a brand for that domain.", "suggestion": "Find the existing brand with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 5 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 5, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "brands", "x-brew-brand-scope": "org", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "brands.write" } }, "/v1/brands/{brandId}": { "get": { "operationId": "getBrandById", "tags": [ "Brands" ], "summary": "Get one brand’s lifecycle state", "description": "The polling endpoint for `POST /v1/brands`. Reports `status`, `progress` and `phase` while extracting, and `error` when extraction failed. Terminal states are `completed` and `failed`.\n\nFor the brand’s DESIGN CONTEXT (identity, markdown design system, logos) use `GET /v1/brand` instead.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Brand id (opaque Convex document id) returned by `POST /v1/brands` and listed by `GET /v1/brands`.", "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" }, "required": true, "description": "Brand id (opaque Convex document id) returned by `POST /v1/brands` and listed by `GET /v1/brands`.", "name": "brandId", "in": "path" } ], "responses": { "200": { "description": "The brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandGetByIdResponse" }, "example": { "brandId": "kx9d1p2qbrxy4nkm55ftz3lmvn21abcd", "domain": "acme.com", "status": "extracting", "ready": false, "progress": 0, "phase": "analyzing", "createdAt": "2026-04-08T12:00:00.000Z", "updatedAt": "2026-04-08T12:00:00.000Z" } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brands.read" } }, "/v1/content/generate-image": { "post": { "operationId": "generateImage", "tags": [ "Content" ], "summary": "Generate an image", "description": "Generates an image via the Brew AI image pipeline. `text-to-image` (default) creates from a prompt; `image-editing` edits `image1` (required) guided by the prompt. Returns a CDN-hosted URL, and saves the image to the brand’s generated images (`GET /v1/brand/images?kind=generated`). Usage-metered: charges the actual image gateway cost (no fixed price).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "Prompt + optional mode / aspect ratio / source images.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentGenerateImageRequest" } } } }, "responses": { "200": { "description": "The operation result.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentImageResponse" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "content.generate" } }, "/v1/content/gif": { "post": { "operationId": "createGif", "tags": [ "Content" ], "summary": "Generate a GIF", "description": "Produces a looping animated GIF (5-second source clip), routed by the `from` discriminator: `prompt` generates an on-brand still then animates it, `image` animates a source image (both via the AI gif workflow), and `video` converts a source MP4. For `prompt` and `image` sources, aspect ratio is one of `16:9`, `9:16`, `1:1` (default `16:9`), and the GIF has that shape: a source image of another shape is centre-cropped when that keeps at least 75% of it, otherwise padded in its own edge colour, never stretched. `imageUrl` takes any public PNG, JPEG, WebP, GIF (first frame), AVIF or TIFF up to 50 MB and 268 megapixels, of any size or shape; SVG, HEIC and BMP return `422 CONTENT_OPERATION_FAILED`. For `video`, aspectRatio is not accepted; use width and fps for conversion. Returns CDN-hosted `gifUrl` (plus `videoUrl`, `width`/`height` and motion metadata for the AI sources). Credit-metered (fixed cost: prompt 20, image 10, video 10).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "A `from` discriminator: `{ from:\"prompt\", prompt, … }`, `{ from:\"image\", imageUrl, … }`, or `{ from:\"video\", videoUrl, … }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentGifRequest" } } } }, "responses": { "200": { "description": "The operation result.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentGifResponse" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "content.generate" } }, "/v1/content/transform": { "post": { "operationId": "transformImage", "tags": [ "Content" ], "summary": "Transform an image", "description": "Deterministic image transform routed by the `operation` discriminator: `optimize` rehosts a palette PNG (resize ≤1200px), `resize` produces exact dimensions via the vision-guided fal pipeline (Sharp cover-crop fallback), `remove_background` returns a transparent PNG cutout (Bria RMBG 2.0). Returns the CDN-hosted `url` + dimensions. Credit-metered (fixed cost: optimize 1, resize 2, remove_background 1).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "An `operation` discriminator: `{ operation:\"optimize\", imageUrl }`, `{ operation:\"resize\", imageUrl, width, height, … }`, or `{ operation:\"remove_background\", imageUrl }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentTransformRequest" } } } }, "responses": { "200": { "description": "The operation result.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentTransformResponse" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "content.transform" } }, "/v1/content/html-to-png": { "post": { "operationId": "htmlToPng", "tags": [ "Content" ], "summary": "Render HTML to a PNG", "description": "Renders an HTML document to a PNG screenshot hosted on the CDN. Credit-metered (fixed cost).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "Full `html` + optional viewport width / max height.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentHtmlToPngRequest" } } } }, "responses": { "200": { "description": "The operation result.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPngResponse" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "402": { "description": "`INSUFFICIENT_CREDITS`: The credit balance is below what this operation requires; `details.cost` is the amount needed.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "insufficientCredits": { "summary": "INSUFFICIENT_CREDITS", "value": { "error": { "code": "INSUFFICIENT_CREDITS", "type": "payment_required", "message": "The credit balance is below what this operation requires; `details.cost` is the amount needed.", "suggestion": "Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage.", "docs": "https://docs.brew.new/api-reference/api/credits", "details": { "cost": 5, "remaining": 0, "planKey": "free" } } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": true, "x-brew-rate-policy": "content.transform" } }, "/v1/content/add-image": { "post": { "operationId": "addImage", "tags": [ "Content" ], "summary": "Add image", "description": "Adds an image to the brand image library: fetches or reads it, converts it, stores it, and vector-indexes it so the email agent can find it. Free; no credits are charged.\n\n**Use when** a public image URL, a batch of them, or a local file should be reusable in designs and searches.\n\n**Input** exactly one of `imageUrl` (one public URL, synchronous), `imageUrls` (1 to 100 public URLs, a durable background import) or `uploadId` (a local file whose bytes were sent to the `uploadUrl` from `createImageUpload`, synchronous).\n\n**Returns** `200` with `{ url, width, height, aspectRatio, assetId }` for `imageUrl` and `uploadId`; `202` with `{ accepted, skipped, runId }` for `imageUrls`. An image whose size could not be measured answers `width` and `height` `0` and `aspectRatio` `unknown`. Repeating an `uploadId` call returns the same answer for 24 hours, even if the image was deleted since.\n\n**Errors** `422 CONTENT_OPERATION_FAILED` when the image cannot be fetched, decoded or saved (for an upload: bytes that are not PNG, JPEG, GIF, WebP, AVIF, TIFF or SVG). For `uploadId`: `404 UPLOAD_NOT_FOUND` (unknown, expired or another brand), `409 UPLOAD_NOT_RECEIVED` (the bytes were never sent), `409 UPLOAD_IN_PROGRESS` (another call is converting it; retry shortly) and `413 PAYLOAD_TOO_LARGE` (over 20 MB, or an SVG over 2 MB).\n\n**See also** `createImageUpload`, `getBrandImages`, `deleteBrandImage`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "api-request-2026-04-08-001" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "requestBody": { "required": true, "description": "Pass one public `imageUrl` for a synchronous import, `imageUrls` with 1 to 100 public URLs for a durable batch import, or the `uploadId` of a local file sent through `POST /v1/content/image-uploads`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentAddImageRequest" } } } }, "responses": { "200": { "description": "The image was optimized, saved to the brand library, and rehosted; `url` is a durable cdn.brew.new URL.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentAddImageResponse" }, "example": { "url": "https://cdn.brew.new/cnt/1d943539cbe0cc60.png", "width": 1200, "height": 675, "aspectRatio": "wide", "assetId": "5f750e5f" } } } }, "202": { "description": "The batch was accepted for durable import; images appear in the brand library progressively.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentAddImageBatchResponse" }, "example": { "accepted": 3, "skipped": 1, "runId": "brand-image-import-01JZ9X8Y7W6V5T4S3R2Q1P0N9M" } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`UPLOAD_NOT_FOUND`: The image upload is unknown, expired, or belongs to another brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "uploadNotFound": { "summary": "UPLOAD_NOT_FOUND", "value": { "error": { "code": "UPLOAD_NOT_FOUND", "type": "not_found", "message": "The image upload is unknown, expired, or belongs to another brand.", "suggestion": "Open a new upload with POST /v1/content/image-uploads, send the file, then add it within 15 minutes.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "409": { "description": "`IDEMPOTENCY_CONFLICT`: The same Idempotency-Key was reused with a different request body.\n\n`IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still executing.\n\n`UPLOAD_IN_PROGRESS`: Another request is still adding this uploaded image.\n\n`UPLOAD_NOT_RECEIVED`: The image upload has not received its file yet.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "IDEMPOTENCY_CONFLICT", "value": { "error": { "code": "IDEMPOTENCY_CONFLICT", "type": "conflict", "message": "The same Idempotency-Key was reused with a different request body.", "suggestion": "Reuse the original payload or send a new idempotency key.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "idempotencyInProgress": { "summary": "IDEMPOTENCY_IN_PROGRESS", "value": { "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "conflict", "message": "A request with this Idempotency-Key is still executing.", "suggestion": "Wait for the original request to finish, then retry the same key to replay its response.", "docs": "https://docs.brew.new/api-reference/api/idempotency" } } }, "uploadInProgress": { "summary": "UPLOAD_IN_PROGRESS", "value": { "error": { "code": "UPLOAD_IN_PROGRESS", "type": "conflict", "message": "Another request is still adding this uploaded image.", "suggestion": "Wait a few seconds, then call POST /v1/content/add-image with the same uploadId to receive its result.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "uploadNotReceived": { "summary": "UPLOAD_NOT_RECEIVED", "value": { "error": { "code": "UPLOAD_NOT_RECEIVED", "type": "conflict", "message": "The image upload has not received its file yet.", "suggestion": "POST the raw file bytes to the uploadUrl, then call POST /v1/content/add-image with the same uploadId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE`: The request body exceeds the route cap.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "payloadTooLarge": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "type": "invalid_request", "message": "The request body exceeds the route cap.", "suggestion": "Reduce the payload size and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "422": { "description": "`CONTENT_OPERATION_FAILED`: The media operation could not be completed for the given input.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "contentOperationFailed": { "summary": "CONTENT_OPERATION_FAILED", "value": { "error": { "code": "CONTENT_OPERATION_FAILED", "type": "invalid_request", "message": "The media operation could not be completed for the given input.", "suggestion": "Check the input described in the message and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "replay", "x-brew-credited": false, "x-brew-rate-policy": "content.transform" } }, "/v1/content/image-uploads": { "post": { "operationId": "createImageUpload", "tags": [ "Content" ], "summary": "Create an image upload", "description": "Opens a single-use upload for one local image file. POST the file's raw bytes to the returned `uploadUrl`, then call `addImage` with the `uploadId` to put it in the brand library. The bytes go straight to storage, so files up to 20 MB fit even though a JSON body is capped far lower. Free; no credits are charged.\n\n**Use when** the image is a file on your machine rather than a public URL (a public URL goes straight to `addImage` as `imageUrl`).\n\n**Input** `fileName`, `contentType` (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`, `image/tiff` or `image/svg+xml`) and `size` in bytes (at most 20,000,000; 2,097,152 for SVG).\n\n**Returns** `201` with `{ uploadId, uploadUrl, expiresAt, maxBytes }`. Within 15 minutes, send the bytes: `curl -X POST --data-binary @logo.png \"\"` answers `200` with `{ uploadId, status: \"uploaded\", size, expiresAt }`; call `addImage` before that `expiresAt` (15 minutes from when the bytes land) (`404 UPLOAD_NOT_FOUND` for an unknown or expired URL, `413 PAYLOAD_TOO_LARGE` over `maxBytes`). The URL carries its own credential; keep it private. Sending again never replaces the first file.\n\n**Errors** `400 INVALID_REQUEST` for an unsupported `contentType` or a `size` over the cap; `429 RATE_LIMITED` also when the brand already has 20 uploads open (its message says so, and `Retry-After` is when the oldest expires).\n\n**See also** `addImage`, `getBrandImages`.", "requestBody": { "required": true, "description": "The file to upload: its name, type and size in bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentImageUploadCreateRequest" } } } }, "responses": { "201": { "description": "The upload is open. POST the raw file bytes to `uploadUrl`, then call `POST /v1/content/add-image` with `uploadId`.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentImageUploadCreateResponse" }, "example": { "uploadId": "imgup_V1StGXR8_Z5jdHi6B-myT", "uploadUrl": "https://example-deployment-123.convex.site/uploads/brand-image?uploadId=imgup_V1StGXR8_Z5jdHi6B-myT&token=9b1c4f6e2a7d8e3f0a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f", "expiresAt": "2026-10-01T18:15:00.000Z", "maxBytes": 20000000 } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "parameters": [ { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "disabled", "x-brew-credited": false, "x-brew-rate-policy": "content.transform" } }, "/v1/usage": { "get": { "operationId": "getUsage", "tags": [ "Usage" ], "summary": "Get usage", "description": "Returns the org usage snapshot: current plan, AI credit balance (limit/used/remaining — `null` = unlimited), monthly email-send quota (`remaining` = `limit` − `used` − `reserved`, where `reserved` is held by sends still delivering), and the billing-period window. Check it before a credit-metered call. Billing belongs to the ORGANIZATION, so this needs an organization-scoped credential: a key bound to one brand gets `403 ORG_SCOPE_REQUIRED` no matter which scopes it holds.", "responses": { "200": { "description": "Usage snapshot — plan, credits, and email-send quota.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageGetResponse" }, "example": { "plan": { "key": "pro", "name": "Pro" }, "credits": { "limit": 50000, "used": 364, "remaining": 49636 }, "emailSends": { "limit": 200000, "used": 911, "reserved": 27880, "remaining": 171209 }, "period": { "start": "2026-05-28T18:10:35.000Z", "end": "2026-06-28T18:10:35.000Z" } } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "usage.read" } }, "/v1/integrations": { "get": { "operationId": "listIntegrations", "tags": [ "Integrations" ], "summary": "List integrations", "description": "Returns the product integration catalog for the brand in scope under `{ data, pagination }`, with a `connected` flag per provider. Canonical providers also expose active, ready installation counts and readiness per capability. Connecting is a human Settings hop at `/integrations/{provider}`; never paste a connect URL into model output. Brand-scoped (`X-Brand-Id` on an org credential). No permission scope.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "Catalog rows for every known provider.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationsListResponse" }, "example": { "data": [ { "provider": "hubspot", "name": "HubSpot", "category": "data_out", "connected": true, "installationCount": 1, "capabilities": [ { "capabilityId": "contacts_import", "isReady": true }, { "capabilityId": "crm_context", "isReady": true }, { "capabilityId": "export_template", "isReady": true } ] }, { "provider": "klaviyo", "name": "Klaviyo", "category": "data_out", "connected": true }, { "provider": "typeform", "name": "Typeform", "category": "data_in", "connected": false, "comingSoon": true } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "integrations.read" } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "tags": [ "API Keys" ], "summary": "List API keys", "security": [ { "sessionAuth": [] } ], "description": "Lists one cursor page of API-key metadata for the active organization. Requires an exact `org:admin` Clerk session; API-key and OAuth actors receive `403`. Organization-level — takes no `X-Brand-Id`. `brandId` on a row is the key's binding, not the request actor. Stored secrets and hashes are never returned.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "example": 100 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque Convex cursor from the previous response. Omit for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } } ], "responses": { "200": { "description": "API keys in the active Clerk session's organization.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysListResponse" }, "example": { "data": [ { "keyId": "kd7b3s7fapqz8mjm12ekz1kxdx87yceg", "name": "CI", "keyPreview": "brew_abc...wxyz", "createdAt": "2026-04-08T12:00:00.000Z", "status": "active", "permissions": [ "all" ] } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 60 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 60, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "api_keys.read" }, "post": { "operationId": "createApiKey", "tags": [ "API Keys" ], "summary": "Create an API key", "security": [ { "sessionAuth": [] } ], "description": "Mints a new API key through an exact `org:admin` Clerk session; API-key and OAuth actors receive `403`. The plaintext `key` is returned once and only its hash plus final preview are stored. This operation intentionally does not support response replay or `Idempotency-Key`, because replay would disclose the credential again. `brandId` in the body is the NEW KEY's binding (omit for an organization-wide key) — the only v1 body field named `brandId`. Permissions default to `[\"all\"]`. To rotate without downtime, send only `replacesKeyId`; Brew copies the active predecessor's name, scope, and permissions and leaves it active until you revoke it after switching consumers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysCreateRequest" }, "example": { "name": "CI", "permissions": [ "emails", "domains" ], "brandId": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } } } }, "responses": { "201": { "description": "The new key. Store `key` now — it is not shown again.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysCreateResponse" }, "example": { "key": "brew_abcdefghijklmnopqrstuvwxyz012345", "keyId": "kd7b3s7fapqz8mjm12ekz1kxdx87yceg", "message": "Save this key securely. You won't be able to see it again." } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "disabled", "x-brew-credited": false, "x-brew-rate-policy": "api_keys.write" } }, "/v1/api-keys/{keyId}": { "delete": { "operationId": "revokeApiKey", "tags": [ "API Keys" ], "summary": "Revoke an API key", "security": [ { "sessionAuth": [] } ], "description": "Revokes an API key in the active organization. Requires an exact `org:admin` Clerk session; API-key and OAuth actors receive `403`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "API key id returned by `GET /v1/api-keys` or `POST /v1/api-keys`.", "example": "kd7b3s7fapqz8mjm12ekz1kxdx87yceg" }, "required": true, "description": "API key id returned by `GET /v1/api-keys` or `POST /v1/api-keys`.", "name": "keyId", "in": "path" } ], "responses": { "200": { "description": "The key was revoked.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysDeleteResponse" }, "example": { "keyId": "kd7b3s7fapqz8mjm12ekz1kxdx87yceg", "deleted": true, "revokedAt": "2026-06-28T18:10:35.000Z" } } } }, "400": { "description": "`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`NOT_FOUND`: No v1 resource lives at this path.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "notFound": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "type": "not_found", "message": "No v1 resource lives at this path.", "suggestion": "Check the request path and HTTP method against the API reference.", "docs": "https://docs.brew.new/api-reference/api/api-introduction" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 20 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 20, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "org", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "api_keys.write" } }, "/v1/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Liveness probe", "description": "No auth, no rate limit — a public liveness surface a dependent service (e.g. the Brew MCP server) can poll. Returns `{ status: \"ok\", version }`.", "security": [], "responses": { "200": { "description": "The service is up.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": false, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok", "version": "v1" } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "public", "x-brew-idempotency": "none", "x-brew-credited": false } }, "/v1/help": { "get": { "operationId": "getHelp", "tags": [ "Meta" ], "summary": "Machine-readable API catalog", "description": "No auth, no rate limit — a structured-JSON catalog an MCP server (or any agent) can parse to self-discover how to use Brew: auth, permission scopes, rate limits, flat credit costs, the error envelope, and the full endpoint list (derived from this same OpenAPI document, so it never drifts). Returns a generic JSON object; read the live response for the concrete shape.", "security": [], "responses": { "200": { "description": "The API catalog.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": false, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpResponse" } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "public", "x-brew-idempotency": "none", "x-brew-credited": false } }, "/v1/chats": { "get": { "operationId": "listChats", "tags": [ "Chats" ], "summary": "List chats", "description": "Lists the brand's Brew chats, most recently active first, under `{ data, pagination }`, as the app's chat list shows them: `chatId`, `title`, the opening prompt, Brew's latest reply, `status` (still streaming or not), `origin` (the chat app it started in; null for the Brew web app) and a link. No transcript and no participants. Free.\n\n**Use when** finding a chat to resume, or seeing what was worked on recently.\n\n**Input** `limit` and `cursor` (an opaque native cursor).\n\n**Returns** `200` with a page of `ChatListRow` rows.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or a malformed cursor.\n\n**See also** `getChatContext` (one chat, with its artifacts and recent messages).", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of chats.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatList" }, "example": { "data": [ { "chatId": "Hk2mZ8t9QbY3sW1vR0pLd", "title": "Spring launch campaign", "firstUserPrompt": "Draft a launch email for the spring collection", "lastAssistantPreview": "Updated the hero and added a \"Shop now\" button.", "status": "completed", "origin": null, "updatedAt": "2026-06-30T12:34:56.789Z", "url": "https://brew.new/chat/Hk2mZ8t9QbY3sW1vR0pLd" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } }, "/v1/chats/{chatId}": { "get": { "operationId": "getChatContext", "tags": [ "Chats" ], "summary": "Get chat context", "description": "Read a brand-scoped digest of a Brew chat for resuming the conversation in an external agent: the emails + automations it created/referenced (latest version, with preview), the trigger events it touched, and a trimmed tail of the transcript. Read-only and free. `404 CHAT_NOT_FOUND` for an unknown id OR a chat owned by a different brand (the two are indistinguishable).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The Brew chat id (from the chat URL / the app).", "example": "Hk2mZ8t9QbY3sW1vR0pLd" }, "required": true, "description": "The Brew chat id (from the chat URL / the app).", "name": "chatId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The chat context digest.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "chatId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "modelId": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "messageCount": { "type": "number" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email", "automation" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "imageUrl": { "type": "string" } }, "required": [ "type", "id", "title" ] } }, "triggerEventIds": { "type": "array", "items": { "type": "string" } }, "recentMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "text": { "type": "string" } }, "required": [ "role", "text" ] } } }, "required": [ "chatId", "title", "modelId", "updatedAt", "messageCount", "artifacts", "triggerEventIds", "recentMessages" ] }, "example": { "chatId": "Hk2mZ8t9QbY3sW1vR0pLd", "title": "Spring launch campaign", "modelId": "anthropic/claude-opus-5.5", "updatedAt": "2026-06-30T12:34:56.789Z", "messageCount": 18, "artifacts": [ { "type": "email", "id": "tCYL9yyvZZ5XmR6saDR-M", "title": "Spring Launch — Hero", "imageUrl": "https://cdn.brew.new/email-preview-tCYL9yyvZZ5XmR6saDR-M.png" }, { "type": "automation", "id": "au_7t2", "title": "Welcome series" } ], "triggerEventIds": [ "te_signup" ], "recentMessages": [ { "role": "user", "text": "Make the hero bolder and add a CTA." }, { "role": "assistant", "text": "Updated the hero and added a \"Shop now\" button." } ] } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`CHAT_NOT_FOUND`: No chat with that id is visible to this credential’s brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "chatNotFound": { "summary": "CHAT_NOT_FOUND", "value": { "error": { "code": "CHAT_NOT_FOUND", "type": "not_found", "message": "No chat with that id is visible to this credential’s brand.", "suggestion": "Check the chatId, and that your key or connector is bound to that chat’s brand.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "503": { "description": "`SERVICE_UNAVAILABLE`: A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "serviceUnavailable": { "summary": "SERVICE_UNAVAILABLE", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "type": "service_unavailable", "message": "A dependency the operation must consult (billing, the idempotency store) is temporarily unavailable, so the request was refused rather than run unmetered.", "suggestion": "Retry the request after a short delay.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } }, "/v1/insights": { "get": { "operationId": "listInsights", "tags": [ "Insights" ], "summary": "List insights", "description": "The brand’s Brew Insights as the Insights page ranks them, most severe first and then by score, under `{ data, pagination, freshness }`. Each row is one deterministic finding of the insight engine; the engine keeps at most 200 findings in view.\n\n**Use when** reporting what Brew found about the brand’s email: deliverability problems, campaigns that under- or over-performed, timing, audience and automation opportunities.\n\n**Input** `state` (`open`, the default: active findings and snoozes that have ended; or `all`, which adds resolved, cleared, dismissed and stale findings), `severity` to read one severity (up to 200 of its own, however many more severe findings exist), `limit`/`cursor` to page. A `cursor` belongs to the walk that returned it: it continues only the same `state` and `severity`, and only while the findings it already returned are still the rows before it. A finding added, removed or moved further down is served when its page comes, so a walk returns each finding of the list as it stands at its last page exactly once. `include` adds the intelligence layer the page shows beside the findings: `pulse` (the last 7 days against the 7 before), `report` (the latest report the analysis agent published), `suggestions` (its proposed and launched suggestions, up to 25) and `memo` (the agent’s memory across runs).\n\n**Returns** `200`. Each row carries `insightId`, `title`, `description` (the detector’s headline), `severity`, `confidence`, `kind`, `category`, `detectorId`, `state`, `firstSeenAt`, `lastSeenAt`, `recurrenceCount`, an optional `action` and the finding’s `url` in Brew. `freshness` is on every page: `dataAsOf` is how current the data behind the findings is, and `latestAttempt.status: failed` means they may be stale. An expansion that does not exist yet answers `null`. Read-only and free.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key, value or `include` token, or a malformed `cursor`. Also `400 INVALID_REQUEST` with `param: cursor` when the findings changed since the cursor was issued (one it already returned left the list or moved, or a new finding ranks among them; the engine re-ran, or a finding was snoozed, dismissed or changed state): read again from the first page, without `cursor`. A cursor issued for another `state` or `severity` is refused the same way.\n\n**See also** `getInsight`, `getAnalyticsOverview`.", "parameters": [ { "schema": { "type": "string", "enum": [ "open", "all" ], "description": "`open` (default) lists active findings and snoozes that have ended. `all` adds resolved, cleared, dismissed and stale findings and snoozes still in effect." }, "required": false, "description": "`open` (default) lists active findings and snoozes that have ended. `all` adds resolved, cleared, dismissed and stale findings and snoozes still in effect.", "name": "state", "in": "query" }, { "schema": { "type": "string", "enum": [ "critical", "warning", "opportunity", "info" ], "description": "Only findings of this severity: `critical`, `warning`, `opportunity` or `info`, up to 200 of its own." }, "required": false, "description": "Only findings of this severity: `critical`, `warning`, `opportunity` or `info`, up to 200 of its own.", "name": "severity", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated expansions: `pulse` adds the weekly pulse, `report` the latest intelligence report, `suggestions` its open suggestions (up to 25), `memo` the analysis agent’s memo.", "x-brew-include-tokens": [ "pulse", "report", "suggestions", "memo" ] }, "required": false, "description": "Comma-separated expansions: `pulse` adds the weekly pulse, `report` the latest intelligence report, `suggestions` its open suggestions (up to 25), `memo` the analysis agent’s memo.", "name": "include", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of findings, the engine’s freshness and any expansions asked for.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightList" }, "example": { "data": [ { "insightId": "k17a8m2v4w5x6y7z8a9b0c1d2e3f4g5h", "title": "Spring sale", "description": "Spring sale bounced 6.2% of sends, above the 6% line.", "severity": "critical", "confidence": "high", "kind": "insight", "category": "deliverability", "detectorId": "deliv.bounce_rate_breach", "state": "active", "firstSeenAt": "2026-10-01T12:00:00.000Z", "lastSeenAt": "2026-10-02T06:04:12.000Z", "recurrenceCount": 1, "action": { "kind": "navigate", "label": "Open campaign analytics", "url": "https://brew.new/analytics/sends/Vx2mZ8t9QbY3sW1vR0pLd" }, "url": "https://brew.new/insights/k17a8m2v4w5x6y7z8a9b0c1d2e3f4g5h" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false }, "freshness": { "dataAsOf": "2026-10-02T06:00:00.000Z", "lastSuccessfulRunAt": "2026-10-02T06:04:12.000Z", "latestAttempt": { "status": "succeeded", "at": "2026-10-02T06:04:12.000Z" } }, "pulse": { "windowEnd": "2026-10-02T00:00:00.000Z", "delivered": 12400, "priorDelivered": 11900, "uniqueOpens": 4960, "priorUniqueOpens": 4400, "uniqueClicks": 620, "priorUniqueClicks": 590, "unsubscribed": 18, "priorUnsubscribed": 21, "openRatePct": 40, "priorOpenRatePct": 37, "clickRatePct": 5, "priorClickRatePct": 5, "openDirection": "up", "clickDirection": "steady", "countsOnly": false, "measured": true } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "analytics.read" } }, "/v1/insights/{insightId}": { "get": { "operationId": "getInsight", "tags": [ "Insights" ], "summary": "Get an insight", "description": "One finding in full, as its page in Brew reads it: the list row’s fields plus `rationale`, `closedReason`, `closedAt`, `lastActedAt`, `churnCount`, the frozen `metrics`, `evidence` links, its `subject`, the detector’s `method` (what it measures, how, against what, and what resolves it), `generatedBy` (the engine run that produced it and what that run could not see) and `freshness`.\n\n**Use when** explaining why a finding exists or what would resolve it. `metrics` were frozen when the finding was computed and are the only numbers to quote about it.\n\n**Input** `insightId` in the path, as a `listInsights` row carries it.\n\n**Returns** `200` with the finding. Read-only and free.\n\n**Errors** `404 INSIGHT_NOT_FOUND` for an unknown, malformed or over-long id OR a finding of another brand: one identical error, so the cases are indistinguishable.\n\n**See also** `listInsights`.", "parameters": [ { "schema": { "type": "string", "description": "The `insightId` a `GET /v1/insights` row carries.", "example": "k17a8m2v4w5x6y7z8a9b0c1d2e3f4g5h" }, "required": true, "description": "The `insightId` a `GET /v1/insights` row carries.", "name": "insightId", "in": "path" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "The finding.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Insight" }, "example": { "insightId": "k17a8m2v4w5x6y7z8a9b0c1d2e3f4g5h", "title": "Spring sale", "description": "Spring sale bounced 6.2% of sends, above the 6% line.", "severity": "critical", "confidence": "high", "kind": "insight", "category": "deliverability", "detectorId": "deliv.bounce_rate_breach", "state": "active", "firstSeenAt": "2026-10-01T12:00:00.000Z", "lastSeenAt": "2026-10-02T06:04:12.000Z", "recurrenceCount": 1, "action": { "kind": "navigate", "label": "Open campaign analytics", "url": "https://brew.new/analytics/sends/Vx2mZ8t9QbY3sW1vR0pLd" }, "url": "https://brew.new/insights/k17a8m2v4w5x6y7z8a9b0c1d2e3f4g5h", "rationale": "Mailbox providers start filtering a sender whose campaigns bounce above 6%.", "closedReason": null, "closedAt": null, "lastActedAt": null, "churnCount": 0, "metrics": { "bounceRate": { "kind": "rate", "value": 0.062, "numerator": 62, "denominator": 1000, "basis": "sent" }, "bounced": { "kind": "count", "value": 62, "noun": "bounces" } }, "evidence": [ { "label": "62 bounced, 3 unsubscribed" } ], "subject": { "kind": "campaign", "id": "Vx2mZ8t9QbY3sW1vR0pLd", "label": "Spring sale" }, "method": { "what": "A campaign whose bounce rate crosses the level mailbox providers act on.", "how": "Bounced ÷ sent, compared against fixed thresholds: 3% is a warning, 6% is critical.", "comparedAgainst": "Absolute industry thresholds, not your own history: providers do not grade on a curve.", "resolvesWhen": "A later send of the same campaign stays under 3%, usually after cleaning the list." }, "generatedBy": { "trigger": "send_settled", "startedAt": "2026-10-02T06:00:03.000Z", "completedAt": "2026-10-02T06:04:12.000Z", "blindSpots": [] }, "freshness": { "dataAsOf": "2026-10-02T06:00:00.000Z", "lastSuccessfulRunAt": "2026-10-02T06:04:12.000Z", "latestAttempt": { "status": "succeeded", "at": "2026-10-02T06:04:12.000Z" } } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`INSIGHT_NOT_FOUND`: No insight with that id is visible to this credential’s brand.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "insightNotFound": { "summary": "INSIGHT_NOT_FOUND", "value": { "error": { "code": "INSIGHT_NOT_FOUND", "type": "not_found", "message": "No insight with that id is visible to this credential’s brand.", "suggestion": "Use an insightId from the brand’s insight list, and check that your key or connector is bound to that insight’s brand.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "analytics.read" } }, "/v1/notifications": { "get": { "operationId": "listNotifications", "tags": [ "Notifications" ], "summary": "List notifications", "description": "Lists the brand's notifications, newest first, under `{ data, pagination }`, as the app's bell shows them: generations, sends, imports, domain checks and score runs finishing or failing, plus comment mentions and replies. Each row has `type`, `status`, `title`, `subtitle`, a `url` into the app and the ids it concerns (`chatId`, `emailId`, `domainId`). Reading marks nothing read. Free.\n\n**Access** each row is shown only when the credential may read its feature, scopes included, so an empty page can mean nothing happened or that this credential cannot see that kind of row (a `type` it cannot see is an empty page, not an error). By type:\n\n- `chat_stream`, `preview_email`: the `emails` scope.\n- `email_sent`, `email_scheduled`, `email_send_failed`, `gradual_send_paused`, `gradual_send_completed`, `send_review_rejected`: `sends` (`emails` implies it).\n- `domain_status`, `domain_score_run`: `domains` (`emails` implies it).\n- `import_job`, `validation_job`: `contacts`.\n- `automation_pause_window_closed`: `automations`.\n- `brand_extracted`, `brand_image_import`, `integration_attention` (a connected integration such as Stripe needs a reconnect, moved to another brand, or lost a permission): every credential on the brand.\n- `api_key_created`: the `all` scope (a signed-in member, or a key or connection holding `all`).\n- `send_limit_reached`: organization admins only (a signed-in admin, an admin’s organization-wide connection, or an organization-wide key holding `all`); never a brand key.\n- `comment_mention`, `comment_reply` (`isPersonal: true`): only the person addressed, signed in or on a personal connection; never an API key.\n\n**Use when** checking what finished or failed since you last looked.\n\n**Input** `type` keeps one notification type; `limit` and `cursor` (an opaque native cursor; a page can hold fewer rows than `limit` while `hasMore` is true).\n\n**Returns** `200` with a page of `Notification` rows; `notificationId` (`ntf_…`) is stable for the row’s life.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key or `type`, or a malformed cursor.\n\n**See also** `getChatContext`, `getEmail`, `getDomainHealth`.", "parameters": [ { "schema": { "type": "string", "enum": [ "chat_stream", "import_job", "brand_image_import", "validation_job", "email_sent", "email_scheduled", "preview_email", "brand_extracted", "domain_status", "domain_score_run", "api_key_created", "email_send_failed", "gradual_send_paused", "gradual_send_completed", "send_limit_reached", "automation_pause_window_closed", "send_review_rejected", "comment_mention", "comment_reply", "integration_attention" ], "description": "Only notifications of this type. A type this credential cannot see (its scopes, or a person-only or admin-only type) is an empty page." }, "required": false, "description": "Only notifications of this type. A type this credential cannot see (its scopes, or a person-only or admin-only type) is an empty page.", "name": "type", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of notifications.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" }, "example": { "data": [ { "notificationId": "ntf_4b8f0c2e91d7a3f65e10", "type": "email_sent", "status": "completed", "title": "Spring launch sent", "subtitle": "12,480 recipients", "url": "https://brew.new/emails?emailIds=2SmZOWV3ZQ7W5x6g3m4pA", "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "isPersonal": false, "createdAt": "2026-10-01T12:00:00.000Z", "updatedAt": "2026-10-01T12:20:00.000Z", "completedAt": "2026-10-01T12:20:00.000Z" } ], "pagination": { "limit": 100, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "none", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "brand.read" } }, "/v1/emails/{emailId}/comments": { "get": { "operationId": "listEmailComments", "tags": [ "Emails" ], "summary": "List email comments", "description": "Lists one design's open comment threads, newest activity first, under `{ data, pagination }`, as the canvas pins show them: `commentId`, `target` (whole email or one element), the 12 most recent `participants` with `participantCount`, `messageCount`, the latest message preview and a link to the thread. People are `{ userId, name }`; resolving deletes a thread. Free.\n\n**Use when** reading what teammates asked for on a design before editing it.\n\n**Input** `emailId` in the path; `limit` and `cursor`. `include=messages` adds each thread's newest messages (author, body, mentions), oldest first, and caps the page at 3 threads sharing a fixed size budget. A thread with older messages returns `messagesCursor`: send it back with that thread's `commentId` to read the next older slice (the whole budget, at least one message), until it comes back null. `commentId` alone reads one thread.\n\n**Returns** `200` with a page of `EmailCommentThread` rows. A design with no threads is an empty page.\n\n**Errors** `400 INVALID_REQUEST` for an unknown query key, an unknown `include` token, a malformed cursor, a `messagesCursor` without its `commentId` or from another thread, or `cursor` with `commentId`. `404 EMAIL_NOT_FOUND` for an `emailId` the brand does not have: unknown, malformed or another brand’s design, one identical error as `getEmail` answers. `404 COMMENT_NOT_FOUND` for a `commentId` that is not an open thread on that design (resolving deletes a thread, so a resolved one is the same case).\n\n**See also** `getEmail`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "example": "2SmZOWV3ZQ7W5x6g3m4pA" }, "required": true, "description": "Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.", "name": "emailId", "in": "path" }, { "schema": { "type": "string", "description": "Comma-separated expansions: `messages` adds each thread's newest messages (author, body, mentions), oldest first, with a `messagesCursor` for older ones, and caps the page at 3 threads.", "x-brew-include-tokens": [ "messages" ] }, "required": false, "description": "Comma-separated expansions: `messages` adds each thread's newest messages (author, body, mentions), oldest first, with a `messagesCursor` for older ones, and caps the page at 3 threads.", "name": "include", "in": "query" }, { "schema": { "type": "string", "minLength": 5, "maxLength": 64, "description": "Read this one thread (`cmt_…`) instead of the page; not with `cursor`." }, "required": false, "description": "Read this one thread (`cmt_…`) instead of the page; not with `cursor`.", "name": "commentId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A thread's `messagesCursor` from a previous response, with that thread's `commentId`: returns the thread with its next older messages and the next `messagesCursor`. Implies `include=messages`." }, "required": false, "description": "A thread's `messagesCursor` from a previous response, with that thread's `commentId`: returns the thread with its next older messages and the next `messagesCursor`. Implies `include=messages`.", "name": "messagesCursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100). Defaults to 100.", "example": 50 }, "required": false, "description": "Page size (1-100). Defaults to 100.", "name": "limit", "in": "query", "example": 50 }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "name": "X-Brand-Id", "in": "header", "required": false, "description": "The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise `400 BRAND_ID_REQUIRED` — there is no default brand); list ids with `GET /v1/brands`. Brand-scoped credentials may omit it, and sending a different brand returns `403 BRAND_SCOPE_MISMATCH`. A brand outside your organization returns `404 BRAND_NOT_FOUND`.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "kx7b3s7fapqz8mjm12ekz1kxdx87yceg" } ], "responses": { "200": { "description": "A page of the design's open comment threads.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 99 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCommentThreadList" }, "example": { "data": [ { "commentId": "cmt_V1StGXR8_Z5jdHi6B-myT", "emailId": "2SmZOWV3ZQ7W5x6g3m4pA", "status": "open", "target": { "kind": "element", "elementId": "elm_4f9Kq", "nodeType": "button" }, "participants": [ { "userId": "user_2xK9mPq4Rt7Vw1Yb", "name": "Grace Hopper" }, { "userId": "user_2abcQ8sLm3Nd5Tz", "name": "Ada Lovelace" } ], "participantCount": 2, "messageCount": 3, "lastMessageAt": "2026-10-01T12:05:00.000Z", "lastMessagePreview": "Bolder works. Shipping it.", "url": "https://brew.new/emails/ungrouped?emailIds=2SmZOWV3ZQ7W5x6g3m4pA&focusEmailIds=2SmZOWV3ZQ7W5x6g3m4pA&commentId=cmt_V1StGXR8_Z5jdHi6B-myT", "messages": [ { "messageId": "cmm_9pQ2wErT5yU8iO1aSdF3g", "author": { "userId": "user_2xK9mPq4Rt7Vw1Yb", "name": "Grace Hopper" }, "body": "@Ada Lovelace can the CTA be bolder?", "mentions": [ { "userId": "user_2abcQ8sLm3Nd5Tz", "name": "Ada Lovelace" } ], "createdAt": "2026-10-01T12:00:00.000Z", "updatedAt": "2026-10-01T12:00:00.000Z" }, { "messageId": "cmm_3hJ6kL9zX2cV5bN8mQ1wE", "author": { "userId": "user_2abcQ8sLm3Nd5Tz", "name": "Ada Lovelace" }, "body": "Bolder works. Shipping it.", "mentions": [], "createdAt": "2026-10-01T12:05:00.000Z", "updatedAt": "2026-10-01T12:05:00.000Z" } ], "messagesCursor": "eyJ2IjoxLCJjIjoiY210X1YxU3RHWFI4X1o1amRIaTZCLW15VCIsImEiOiIyMDI2LTEwLTAxVDEyOjAwOjAwLjAwMFoiLCJtIjoiY21tXzlwUTJ3RXJUNXlVOGlPMWFTZEYzZyJ9" } ], "pagination": { "limit": 3, "cursor": null, "hasMore": false } } } } }, "400": { "description": "`BRAND_ID_REQUIRED`: An organization-scoped credential called a brand-scoped operation without naming the brand.\n\n`INVALID_REQUEST`: The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandIdRequired": { "summary": "BRAND_ID_REQUIRED", "value": { "error": { "code": "BRAND_ID_REQUIRED", "type": "invalid_request", "message": "An organization-scoped credential called a brand-scoped operation without naming the brand.", "suggestion": "List brands with GET /v1/brands, then name one with the X-Brand-Id header. There is no default brand.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidRequest": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "type": "invalid_request", "message": "The body or query failed validation: an unknown key, a wrong type, or a missing required field. `param` names the offender.", "suggestion": "Fix the field reported in `param` and retry.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "401": { "description": "`API_KEY_REVOKED`: The API key was revoked.\n\n`AUTHENTICATION_REQUIRED`: No API key or session accompanied the request.\n\n`INVALID_API_KEY`: The API key is malformed or unknown.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "apiKeyRevoked": { "summary": "API_KEY_REVOKED", "value": { "error": { "code": "API_KEY_REVOKED", "type": "authentication_error", "message": "The API key was revoked.", "suggestion": "Create a new active API key and retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "authenticationRequired": { "summary": "AUTHENTICATION_REQUIRED", "value": { "error": { "code": "AUTHENTICATION_REQUIRED", "type": "authentication_error", "message": "No API key or session accompanied the request.", "suggestion": "Provide a valid API key or sign in with an organization session.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "invalidApiKey": { "summary": "INVALID_API_KEY", "value": { "error": { "code": "INVALID_API_KEY", "type": "authentication_error", "message": "The API key is malformed or unknown.", "suggestion": "Check the API key format and retry with a valid active key.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "403": { "description": "`ACCOUNT_SUSPENDED`: The organization behind the credential is suspended.\n\n`BRAND_SCOPE_MISMATCH`: A brand-scoped credential named a brand other than the one it is bound to.\n\n`INSUFFICIENT_PERMISSIONS`: The credential lacks the permission scope the operation needs.\n\n`INSUFFICIENT_ROLE`: The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "accountSuspended": { "summary": "ACCOUNT_SUSPENDED", "value": { "error": { "code": "ACCOUNT_SUSPENDED", "type": "authorization_error", "message": "The organization behind the credential is suspended.", "suggestion": "The organization behind this credential is suspended. Contact support@brew.new; do not retry.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "brandScopeMismatch": { "summary": "BRAND_SCOPE_MISMATCH", "value": { "error": { "code": "BRAND_SCOPE_MISMATCH", "type": "authorization_error", "message": "A brand-scoped credential named a brand other than the one it is bound to.", "suggestion": "Omit the brand to use the one this credential is bound to, or use an organization-scoped credential to reach other brands.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientPermissions": { "summary": "INSUFFICIENT_PERMISSIONS", "value": { "error": { "code": "INSUFFICIENT_PERMISSIONS", "type": "authorization_error", "message": "The credential lacks the permission scope the operation needs.", "suggestion": "Use an API key or session with the required permission.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } }, "insufficientRole": { "summary": "INSUFFICIENT_ROLE", "value": { "error": { "code": "INSUFFICIENT_ROLE", "type": "authorization_error", "message": "The caller lacks the access the operation needs: `param` names `member` (access to the brand) or `org_admin` (the organization role).", "suggestion": "Ask an organization admin to run this, to add you to the brand, or to make you an admin.", "docs": "https://docs.brew.new/api-reference/api/authentication" } } } } } } }, "404": { "description": "`BRAND_NOT_FOUND`: The named or bound brand does not exist in this organization (unknown, deleting, or another organization).\n\n`COMMENT_NOT_FOUND`: The design has no open comment thread with that id (resolving a thread deletes it).\n\n`EMAIL_NOT_FOUND`: No email design with that id exists in the brand (cross-brand ids surface as 404).", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "brandNotFound": { "summary": "BRAND_NOT_FOUND", "value": { "error": { "code": "BRAND_NOT_FOUND", "type": "not_found", "message": "The named or bound brand does not exist in this organization (unknown, deleting, or another organization).", "suggestion": "List the brands this credential can reach with GET /v1/brands.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "commentNotFound": { "summary": "COMMENT_NOT_FOUND", "value": { "error": { "code": "COMMENT_NOT_FOUND", "type": "not_found", "message": "The design has no open comment thread with that id (resolving a thread deletes it).", "suggestion": "List the design’s threads with GET /v1/emails/{emailId}/comments and use a returned commentId.", "docs": "https://docs.brew.new/api-reference/api/errors" } } }, "emailNotFound": { "summary": "EMAIL_NOT_FOUND", "value": { "error": { "code": "EMAIL_NOT_FOUND", "type": "not_found", "message": "No email design with that id exists in the brand (cross-brand ids surface as 404).", "suggestion": "List designs with GET /v1/emails.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } }, "429": { "description": "`RATE_LIMITED`: The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." }, "X-RateLimit-Limit": { "schema": { "type": "integer", "description": "Requests allowed in the current rolling rate limit window.", "example": 100 }, "required": true, "description": "Requests allowed in the current rolling rate limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer", "description": "Requests remaining in the current rolling rate limit window.", "example": 0 }, "required": true, "description": "Requests remaining in the current rolling rate limit window." }, "X-RateLimit-Reset": { "schema": { "type": "integer", "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window.", "example": 1712592360 }, "required": true, "description": "Unix timestamp in seconds when the oldest recorded request leaves the rolling window." }, "Retry-After": { "schema": { "type": "integer", "description": "Seconds to wait before retrying the request.", "example": 42 }, "required": true, "description": "Seconds to wait before retrying the request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "rateLimited": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "type": "rate_limit", "message": "The credential exhausted the rolling window for this route policy; Retry-After is when the oldest recorded request leaves, and the refused request does not take a slot.", "suggestion": "Wait the Retry-After time, then retry the same request.", "docs": "https://docs.brew.new/api-reference/api/rate-limits", "retryAfter": 42, "details": { "scope": "credential", "limit": 100, "remaining": 0, "reset": 1712592360, "consumed": false } } } } } } } }, "500": { "description": "`INTERNAL_ERROR`: An unexpected failure; the x-request-id header identifies it.", "headers": { "x-request-id": { "schema": { "type": "string", "description": "Unique request identifier. Share this with support when debugging a request.", "example": "req_8cac13fd94e6420cacdd75a1aa403a28" }, "required": true, "description": "Unique request identifier. Share this with support when debugging a request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" }, "examples": { "internalError": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "type": "internal_error", "message": "An unexpected failure; the x-request-id header identifies it.", "suggestion": "Retry the request. If it keeps failing, contact support with the x-request-id header.", "docs": "https://docs.brew.new/api-reference/api/errors" } } } } } } } }, "x-brew-scope": "emails", "x-brew-brand-scope": "brand", "x-brew-idempotency": "none", "x-brew-credited": false, "x-brew-rate-policy": "emails.read" } } }, "webhooks": {} }