> ## Documentation Index > Fetch the complete documentation index at: https://docs.brew.new/llms.txt > Use this file to discover all available pages before exploring further. # Create an automation > Deterministic create — the body carries the full graph (`{ name, triggerEventId?, nodes, connections }`). Returns `201` with the bare `AutomationRow`. **Trigger binding (exactly one):** for an EVENT automation pass `triggerEventId` (then publish with `PATCH … { "published": true }`). For a MANUAL-AUDIENCE automation OMIT `triggerEventId` and give the trigger node `config: { "mode": "manualAudience", "audienceId": "aud_…" }` — it is launched on demand with `POST /v1/automations/{automationId}/run` rather than published. Chain `POST /v1/emails { prompt }` first to mint the design each `sendEmail` node references — every `sendEmail` node MUST carry `emailId`, `emailVersionId`, `domainId`, `subject`, `previewText`. **Dry-run** — add `dryRun: true` to validate without persisting; returns `200` with `{ valid, blockers[], warnings[], nodeCounts }`. ## OpenAPI ````yaml /api-reference/openapi-public-v1.yaml post /v1/automations openapi: 3.1.0 info: title: Brew Public API v1 version: 1.0.0 description: >- Generated from the Brew app Zod contracts (`lib//contracts.ts`). This file is the source of truth for the public API documentation. ## Resource paths Identity lives in the URL path (`/v1/analytics/sends/{sendId}`) — never in a query param or request body. Collections are plural top-level segments (`/v1/emails`); query params exist only for collection pagination + simple filters. Relationships are sub-resources (`/v1/emails/{emailId}/sends`), and non-CRUD operations are explicit action sub-paths (`/v1/automations/{automationId}/test`). ## Response envelopes - Lists: `{ data: Row[], pagination: { limit, cursor: string | null, hasMore } }` — loop `while (cursor !== null)`. - Get-one and writes: the bare resource (creates return `201`; async sends `202`). - Deletes: `{ , deleted: boolean }` — idempotent (already-gone ids resolve with `deleted: false`). - Errors: `{ error: { code, type, message, param?, suggestion, docs } }` — branch on the stable `code`. - ONE exception: `POST /v1/automations/triggers/{triggerEventId}/fire` responds with the legacy fire envelope `{ success, status, code, message, receivedAt, details }` (shared with internal webhook infrastructure). ## Brand scoping API keys are always scoped to a specific brand. The brand is resolved from the key on every request. **No public endpoint accepts a `brandId` field** in its request body or query string — sending one returns `400 INVALID_REQUEST`. Resources that exist in a different brand surface as `404` (never `403`), so the API does not leak cross-brand existence. `GET /v1/templates` is organization-wide and not constrained to the key brand. Brands themselves are managed in the Brew dashboard. ## Idempotency Send an `Idempotency-Key` header (≤ 100 chars) on any POST your code might retry. Same key + same body within 24h returns the original response; same key + different body returns `409 IDEMPOTENCY_CONFLICT`. 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/test` fires a one-off test. Sending is not campaign-specific. Send reads (list, status, per-send event feeds) live under Analytics (`/v1/analytics/sends`). - name: Analytics description: >- Read-only cross-resource analytics: lifetime per-campaign KPIs, windowed automation performance, the unified event feed, send reads (`/v1/analytics/sends`), and the fired-trigger audit log (`/v1/analytics/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: >- Read a brand-scoped digest of a Brew chat — referenced emails/automations/triggers + a trimmed transcript — so an external agent can resume the conversation. - name: Meta description: >- Public discovery surface (no auth): the machine-readable API catalog (`/v1/help`). paths: /v1/automations: post: tags: - Automations summary: Create an automation description: >- Deterministic create — the body carries the full graph (`{ name, triggerEventId?, nodes, connections }`). Returns `201` with the bare `AutomationRow`. **Trigger binding (exactly one):** for an EVENT automation pass `triggerEventId` (then publish with `PATCH … { "published": true }`). For a MANUAL-AUDIENCE automation OMIT `triggerEventId` and give the trigger node `config: { "mode": "manualAudience", "audienceId": "aud_…" }` — it is launched on demand with `POST /v1/automations/{automationId}/run` rather than published. Chain `POST /v1/emails { prompt }` first to mint the design each `sendEmail` node references — every `sendEmail` node MUST carry `emailId`, `emailVersionId`, `domainId`, `subject`, `previewText`. **Dry-run** — add `dryRun: true` to validate without persisting; returns `200` with `{ valid, blockers[], warnings[], nodeCounts }`. operationId: createAutomation 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/AutomationsPostRequest' examples: deterministic: summary: Create a trigger → sendEmail flow value: name: Welcome flow description: Welcome new signups triggerEventId: tri_signup nodes: - id: trg label: On signup type: trigger config: actionType: trigger - id: send_welcome label: Welcome type: sendEmail config: actionType: sendEmail emailId: eml_welcome emailVersionId: emv_welcome_v1 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: tri_signup nodes: - id: trg label: On signup type: trigger config: actionType: trigger connections: [] dryRun: true responses: '200': description: >- Dry-run result (no writes). `valid` indicates whether the graph would publish cleanly. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. '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 for when the rolling window fully resets. example: 1712592360 required: true description: >- Unix timestamp in seconds for when the rolling window fully resets. content: application/json: schema: $ref: '#/components/schemas/AutomationRow' example: automationId: auto_abc automationVersionId: av_v1 triggerEventId: tri_signup name: Welcome flow version: latest published: false nodes: - id: trg label: On signup type: trigger config: actionType: trigger - id: send_welcome label: Welcome type: sendEmail config: actionType: sendEmail emailId: eml_welcome emailVersionId: emv_welcome_v1 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: - eml_welcome createdAt: '2026-04-08T12:00:00.000Z' updatedAt: '2026-04-08T12:00:00.000Z' '400': description: >- Strict-body violation OR the graph references designs / domains that do not exist or are not ready. `AUTOMATION_GRAPH_INVALID` includes `error.details.issues` with one entry per offending node / connection. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' examples: schemaInvalid: summary: Required field missing value: error: code: INVALID_REQUEST type: invalid_request message: Request body validation failed. suggestion: >- Send `{ name, triggerEventId, nodes, connections }` with each sendEmail node carrying `emailId`, `emailVersionId`, `domainId`, `subject`, `previewText`. docs: https://docs.brew.new/api-reference/api/errors graphInvalid: summary: Graph references unknown email / domain value: error: code: AUTOMATION_GRAPH_INVALID type: invalid_request message: >- "Welcome" references emailVersionId 'emv_missing' which does not exist in this brand. (and 1 more graph issue) param: nodes[0].config.emailVersionId suggestion: >- Fix every issue reported in `details.issues` then resubmit. Each entry includes the offending `nodeId` (or connection index) and a `kind` discriminator your SDK can branch on. docs: https://docs.brew.new/api-reference/api/errors details: issues: - kind: email_not_found nodeId: send_welcome nodeLabel: Welcome message: >- "Welcome" references emailVersionId 'emv_missing' which does not exist in this brand. Generate the email via POST /v1/emails and reuse the returned emailId + emailVersionId. - kind: domain_not_ready nodeId: send_welcome nodeLabel: Welcome message: >- "Welcome" references domain 'kx7…' which is not verified for sending. Finish domain verification or pick a different domainId. '401': description: The API key was missing, invalid, or 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: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INVALID_API_KEY type: authentication_error message: The provided API key is invalid. suggestion: Check the API key format and retry with a valid active key. docs: https://docs.brew.new/api-reference/api/authentication '403': description: The caller does not have the required `automations` permission. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INSUFFICIENT_PERMISSIONS type: authorization_error message: The caller does not have the required permission. suggestion: Use an API key or session with the required permission. docs: https://docs.brew.new/api-reference/api/authentication param: automations '404': description: The referenced `triggerEventId` does not exist. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: TRIGGER_EVENT_NOT_FOUND type: not_found message: Trigger event 'tri_unknown' was not found in this brand. suggestion: >- Pass a triggerEventId returned by POST /v1/automations/triggers. docs: https://docs.brew.new/api-reference/api/errors param: triggerEventId '409': description: The same `Idempotency-Key` was reused with a different request body. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: IDEMPOTENCY_CONFLICT type: conflict message: >- The same idempotency key was reused with a different request payload. suggestion: Reuse the original payload or send a new idempotency key. docs: https://docs.brew.new/api-reference/api/idempotency '429': description: The request hit the rolling rate limit 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 for when the rolling window fully resets. example: 1712592360 required: true description: >- Unix timestamp in seconds for when the rolling window fully resets. 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' example: error: code: RATE_LIMITED type: rate_limit message: Too many requests. suggestion: Wait for the retry window before sending another request. docs: https://docs.brew.new/api-reference/api/rate-limits retryAfter: 42 '500': description: Unexpected internal error. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INTERNAL_ERROR type: internal_error message: An unexpected error occurred. suggestion: Retry the request. If it keeps failing, contact support. docs: https://docs.brew.new/api-reference/api/errors components: schemas: 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: type: object properties: actionType: type: string mode: type: string enum: - event - manualAudience triggerEventId: type: string audienceId: type: string eventName: type: string 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 emailId: type: string minLength: 1 emailVersionId: type: string minLength: 1 domainId: type: string minLength: 1 subject: type: string minLength: 1 previewText: type: string minLength: 1 fromName: type: string minLength: 1 replyTo: type: string format: email emailTitle: type: string fromAddress: type: string required: - emailId - emailVersionId - domainId - subject - previewText 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: type: object properties: actionType: 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: - logicalOperator - conditions 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 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 additionalProperties: false maxItems: 500 connections: type: array items: type: object properties: from: type: string minLength: 1 to: type: string minLength: 1 branch: type: string enum: - left - right required: - from - to additionalProperties: false maxItems: 1000 default: [] dryRun: type: boolean required: - name - nodes 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 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: type: object properties: actionType: type: string mode: type: string enum: - event - manualAudience triggerEventId: type: string audienceId: type: string eventName: type: string 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: type: object properties: actionType: 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: - logicalOperator - conditions 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 enum: - left - right required: - from - to emailIds: type: array items: type: string minLength: 1 maxLength: 64 createdBy: type: string 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 ApiErrorEnvelope: type: object properties: error: type: object properties: code: type: string minLength: 1 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 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 ````