> ## 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.

# List templates

> Lists public email templates under `{ data, pagination }`. Each row is FULL, it carries the rendered `html` + `previewImage` plus the display metadata (`title`, `category`, `brand`, `updatedAt`), so you never need a follow-up get-one round-trip. Supports exact `?brand=` and `?category=` filters and a lightweight `?semantic=` text filter. Templates are organization-wide references (use one as `referenceEmailId` on `POST /v1/emails`).



## OpenAPI

````yaml /api-reference/openapi-public-v1.yaml get /v1/templates
openapi: 3.1.0
info:
  title: Brew Public API v1
  version: 1.0.0
  description: >-
    Generated from the Brew app Zod contracts (`lib/<domain>/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: `{ <idField>, 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/templates:
    get:
      tags:
        - Templates
      summary: List templates
      description: >-
        Lists public email templates under `{ data, pagination }`. Each row is
        FULL, it carries the rendered `html` + `previewImage` plus the display
        metadata (`title`, `category`, `brand`, `updatedAt`), so you never need
        a follow-up get-one round-trip. Supports exact `?brand=` and
        `?category=` filters and a lightweight `?semantic=` text filter.
        Templates are organization-wide references (use one as
        `referenceEmailId` on `POST /v1/emails`).
      operationId: listTemplates
      parameters:
        - schema:
            type: string
            minLength: 1
          required: false
          name: brand
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: category
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: semantic
          in: query
        - schema:
            anyOf:
              - type: number
              - type: string
          required: false
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 512
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: A page of templates matching the filters.
          headers:
            x-request-id:
              schema:
                type: string
                description: >-
                  Unique request identifier. Share this with support when
                  debugging a request.
                example: req_8cac13fd94e6420cacdd75a1aa403a28
              required: true
              description: >-
                Unique request identifier. Share 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/TemplatesListResponse'
              example:
                data:
                  - emailId: seed-vercel-newsletter
                    title: Vercel Newsletter
                    category: newsletter
                    brand: vercel.com
                    html: <!DOCTYPE html><html><body>…</body></html>
                    previewImage: https://storage.example.com/templates/seed.png
                    updatedAt: '2026-04-08T00:00:00.000Z'
                pagination:
                  limit: 100
                  cursor: null
                  hasMore: 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`, which is always resolved from the API
            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.
          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: brand
        '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:
    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
            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
    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

````