> ## 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. # Brand overview (totals, rates, timeseries) > Windowed brand overview — the EXACT read behind the app's /analytics metric cards + chart (same per-recipient dedup and machine-click/open exclusion rules), so API/MCP numbers can never disagree with the page. Defaults to the last 7 days. Optional filters, all of which COMPOSE freely: `source` (csv of send sources), `automationId`, `emailId`, `audienceId` (csv, ≤20), `triggerEventId` (csv, ≤10 — integration trigger-events, resolved to their wired automations), `domain` (sending domain), and `recipient` (csv of recipient rules — same grammar and name as `GET /v1/analytics/events`). A single filter is answered from pre-aggregated rollup rows; any combination (and anything with `domain` or `recipient`, neither of which has a rollup dimension) is answered by aggregating raw events instead — exact, but capped, so watch `truncated` on wide windows. Returns `{ totals, rates, buckets, granularity, timeZone, range, truncated }` — `truncated: true` means the window exceeded the scan budget; narrow the range. Requires the `emails` scope. ## OpenAPI ````yaml /api-reference/openapi-public-v1.yaml get /v1/analytics/overview 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 A credential is scoped either to ONE BRAND or to the whole ORGANIZATION. A brand-scoped credential resolves its brand automatically — send nothing. An organization-scoped credential must name the brand per request with the `X-Brand-Id` header; omitting it returns `400 BRAND_ID_REQUIRED`, because there is deliberately no default brand. Discover ids with `GET /v1/brands`. **No public endpoint accepts a `brandId` field** in its request body or query string — sending one returns `400 INVALID_REQUEST`. `X-Brand-Id` is a header, and the only way to name a brand. Resources that exist in a different brand surface as `404` (never `403`), so the API does not leak cross-brand existence; the same is true of an `X-Brand-Id` naming a brand outside your organization. `GET /v1/templates` is organization-wide. `/v1/brands` manages brands themselves and is organization-level, so it takes no `X-Brand-Id`. ## 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` with `test: true` 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: 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 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: 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. `POST` body `brandId` is the new key's binding (the only v1 body field named `brandId`). Organization-wide keys need an org-admin session or an organization-scoped credential. - name: Meta description: >- Public discovery surface (no auth): the machine-readable API catalog (`/v1/help`). paths: /v1/analytics/overview: get: tags: - Analytics summary: Brand overview (totals, rates, timeseries) description: >- Windowed brand overview — the EXACT read behind the app's /analytics metric cards + chart (same per-recipient dedup and machine-click/open exclusion rules), so API/MCP numbers can never disagree with the page. Defaults to the last 7 days. Optional filters, all of which COMPOSE freely: `source` (csv of send sources), `automationId`, `emailId`, `audienceId` (csv, ≤20), `triggerEventId` (csv, ≤10 — integration trigger-events, resolved to their wired automations), `domain` (sending domain), and `recipient` (csv of recipient rules — same grammar and name as `GET /v1/analytics/events`). A single filter is answered from pre-aggregated rollup rows; any combination (and anything with `domain` or `recipient`, neither of which has a rollup dimension) is answered by aggregating raw events instead — exact, but capped, so watch `truncated` on wide windows. Returns `{ totals, rates, buckets, granularity, timeZone, range, truncated }` — `truncated: true` means the window exceeded the scan budget; narrow the range. Requires the `emails` scope. operationId: getAnalyticsOverview 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 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/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: >- The request body or query string was invalid (unknown key, wrong type, or missing required field). Strict schemas reject unknown keys — including `brandId`: a brand is named with the `X-Brand-Id` HEADER (organization-scoped credentials) or resolved from the credential itself (brand-scoped ones), never as a body or query 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' example: error: code: INVALID_REQUEST type: invalid_request message: Request validation failed. suggestion: Fix the field reported in `param` and retry. docs: https://docs.brew.new/api-reference/api/errors param: from '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 `emails` 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: emails '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: 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 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 ````