> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tented.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set the audience

> Attach the audience, replacing any previous one. Use an existing list, an inline static list of contact IDs, or an inline dynamic segment defined by rules. Only editable while the blast is a draft (`409 campaign_not_editable` otherwise).



## OpenAPI

````yaml /api-reference/openapi.json put /v1/email-blasts/{blastId}/audience
openapi: 3.1.0
info:
  title: Tented API
  version: 1.0.0
  description: >-
    The Tented public API: generate, publish, and manage AI-built web pages
    (tents), and run the email platform — contacts, reusable emails, one-time
    blasts, and triggered flows.


    ## Authentication

    Authenticate every request with a workspace API key: `Authorization: Bearer
    <api-key>`. Keys are created in **Workspace Settings → API Keys** and are
    scoped to a single workspace.


    ## Asynchronous work

    Tent generation, bulk creation, and email AI generation return `202
    Accepted` immediately. Poll the corresponding status endpoint (`GET
    /v1/tents/{tentId}`, `GET /v1/bulk-jobs/{bulkJobId}`, `GET
    /v1/emails/{emailId}/generations/{generationId}`) — no more than every 10
    seconds.


    ## Pagination

    Email listings use cursor pagination (`cursor`/`next_cursor`). Blast, flow,
    and member listings use page pagination (`page`/`limit` with a `pagination`
    object in the response).


    ## Conventions

    Request and response fields are snake_case, with two exceptions: analytics
    query parameters (`tentIdOrAlias`, `daysBack`) and segment rule trees
    (camelCase keys such as `listId` and `timeWindow`).
  contact:
    name: Tented Support
    email: support@tented.ai
servers:
  - url: https://api.tented.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Tents
    description: >-
      Create, edit, publish, and manage AI-generated pages, including asset
      uploads and bulk creation.
  - name: Analytics
    description: Traffic analytics for single tents and the whole workspace.
  - name: Contacts
    description: >-
      Batch create, update, and delete contacts. Up to 25 items per request with
      per-item results.
  - name: Emails
    description: >-
      Reusable email content: AI generation, direct HTML edits, plain-text
      control, and approval.
  - name: Email Blasts
    description: >-
      One-time sends to an audience: compose, schedule, track engagement, export
      recipients.
  - name: Triggered Flows
    description: >-
      Multi-step automations that enroll contacts on triggers and move them
      through a step graph.
  - name: Contact Imports
  - name: Contact Fields
  - name: Contact Lists
  - name: Email Templates
  - name: Tent Templates
    description: >-
      Reusable, AI-editable tent layouts. Create from HTML or an existing tent,
      iterate with AI, approve, and clone. Approved tent templates seed new
      tents.
paths:
  /v1/email-blasts/{blastId}/audience:
    put:
      tags:
        - Email Blasts
      summary: Set the audience
      description: >-
        Attach the audience, replacing any previous one. Use an existing list,
        an inline static list of contact IDs, or an inline dynamic segment
        defined by rules. Only editable while the blast is a draft (`409
        campaign_not_editable` otherwise).
      operationId: set-blast-audience
      parameters:
        - name: blastId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Blast ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    source:
                      type: string
                      enum:
                        - existing
                      description: Use an existing list.
                    list_id:
                      type: string
                      format: uuid
                      description: List to attach.
                  required:
                    - source
                    - list_id
                  description: Attach an existing list.
                - type: object
                  properties:
                    source:
                      type: string
                      enum:
                        - inline
                      description: Create a list inline.
                    kind:
                      type: string
                      enum:
                        - static
                      description: Static membership.
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: List name.
                    description:
                      type:
                        - string
                        - 'null'
                      description: List description.
                      maxLength: 1000
                    contact_ids:
                      type: array
                      items:
                        type: string
                        format: uuid
                      maxItems: 500
                      description: Contacts to include (up to 500 per request).
                  required:
                    - source
                    - kind
                    - contact_ids
                  description: Create a static list inline from contact IDs.
                - type: object
                  properties:
                    source:
                      type: string
                      enum:
                        - inline
                      description: Create a list inline.
                    kind:
                      type: string
                      enum:
                        - dynamic
                      description: Dynamic membership.
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: List name.
                    description:
                      type:
                        - string
                        - 'null'
                      description: List description.
                      maxLength: 1000
                    rules:
                      $ref: '#/components/schemas/RuleNode'
                  required:
                    - source
                    - kind
                    - rules
                  description: >-
                    Create a dynamic segment inline. Membership is computed
                    continuously from the rules.
      responses:
        '200':
          description: Audience attached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blast'
        '400':
          description: >-
            Bad request — invalid parameters or request body. Validation
            failures include `details.issues` with per-field messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing, malformed, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Not found — the resource does not exist in the workspace tied to
            your API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict — see `error_code` for the specific reason.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RuleNode:
      oneOf:
        - $ref: '#/components/schemas/RuleGroup'
        - $ref: '#/components/schemas/RuleCondition'
      description: >-
        A rule tree node: either a group of nested conditions or a single
        condition. NOTE: rule trees use camelCase keys (`listId`,
        `fieldDefinitionId`, `timeWindow`), unlike the rest of the API.
    Blast:
      type: object
      properties:
        blast_id:
          type: string
          format: uuid
          description: Blast ID.
        type:
          type: string
          description: Always `email_blast`.
        name:
          type: string
          description: Blast name.
        description:
          type:
            - string
            - 'null'
          description: Description.
        status:
          type: string
          enum:
            - draft
            - scheduled
            - sending
            - sent
            - failed
            - cancelled
            - archived
          description: Lifecycle state.
        audience_list_id:
          type:
            - string
            - 'null'
          description: List backing the audience.
        audience_source:
          type:
            - string
            - 'null'
          description: '`existing` or `inline`.'
        audience:
          type:
            - object
            - 'null'
          properties:
            list_id:
              type: string
              format: uuid
              description: List ID.
            source:
              type: string
              description: '`existing` or `inline`.'
            name:
              type: string
              description: List name.
            kind:
              type: string
              description: '`static` or `dynamic`.'
            member_count:
              type: integer
              description: Current member count.
          description: Attached audience, or `null` when not set.
        email_id:
          type:
            - string
            - 'null'
          description: Email attached to the blast.
        email_source:
          type:
            - string
            - 'null'
          description: '`existing` or `inline`.'
        email:
          type:
            - object
            - 'null'
          properties:
            email_id:
              type: string
              format: uuid
              description: Email ID.
            source:
              type: string
              description: '`existing` or `inline`.'
            name:
              type: string
              description: Email name.
            status:
              type: string
              description: '`draft` or `approved`.'
            subject:
              type:
                - string
                - 'null'
              description: Subject line.
            current_version:
              type: integer
              description: Latest version.
            approved_version:
              type:
                - integer
                - 'null'
              description: Approved version, or `null`.
          description: Attached email summary, or `null` when not set.
        operational:
          type: boolean
          description: >-
            True for operational/transactional sends: unsubscribed contacts are
            not suppressed and the unsubscribe footer is skipped.
        scheduled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Scheduled send time (UTC).
        approved_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the attached email was approved for this blast.
        approved_email_version:
          type:
            - integer
            - 'null'
          description: Email version locked in for the send.
        sent_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the send completed.
        send_mode:
          type:
            - string
            - 'null'
          description: '`scheduled` or `send_now`.'
        details:
          $ref: '#/components/schemas/BlastDetails'
        approval_readiness:
          $ref: '#/components/schemas/ApprovalReadiness'
        created_at:
          type: string
          format: date-time
          description: Creation time.
        updated_at:
          type: string
          format: date-time
          description: Last update.
      required:
        - blast_id
        - type
        - name
        - status
      description: >-
        An email blast. `approval_readiness` is included only while the blast is
        a draft.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: >-
            Stable machine-readable error code (present on email, blast, flow,
            and related endpoints, e.g. `campaign_not_ready`,
            `generation_in_progress`).
        message:
          type: string
          description: Additional human-readable context (present on some tent endpoints).
        code:
          type: string
          description: >-
            Machine-readable code used by tent creation errors (e.g.
            `INVALID_PROMPT_INTENT`).
        details:
          type: object
          additionalProperties: true
          description: >-
            Additional error context. Validation errors include `issues`: an
            array of `{ path, message }` objects.
        limit:
          type: integer
          description: Plan limit that was hit (present on `429` publish-limit errors).
        current:
          type: integer
          description: >-
            Current usage against the limit (present on `429` publish-limit
            errors).
      required:
        - error
      description: >-
        Error response. All errors include `error`; the other fields vary by
        endpoint group.
    RuleGroup:
      type: object
      properties:
        kind:
          type: string
          enum:
            - group
          description: Set to `group` (default when `conditions` is present).
        operator:
          type: string
          enum:
            - and
            - or
          default: and
          description: How child conditions combine.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/RuleNode'
          description: >-
            Child nodes. Groups nest up to 5 levels; a tree may contain at most
            100 nodes.
      required:
        - conditions
    RuleCondition:
      type: object
      properties:
        kind:
          type: string
          enum:
            - condition
          description: >-
            Set to `condition` (default when `operator` is present without
            `conditions`).
        source:
          type: string
          enum:
            - contact
            - custom_field
            - activity
            - list_membership
            - email_step
          default: contact
          description: What the condition tests.
        field:
          type: string
          description: >-
            Standard contact field in camelCase (e.g. `leadStatus`,
            `tentedScore`, `createdAt`). Used with `source: contact`.
        fieldDefinitionId:
          type: string
          format: uuid
          description: 'Active custom-field definition ID. Used with `source: custom_field`.'
        activityType:
          type: string
          description: >-
            Activity type (e.g. `form_submission`). Used with `source:
            activity`.
        listId:
          type: string
          format: uuid
          description: 'Static list ID. Used with `source: list_membership`.'
        nodeId:
          type: string
          description: >-
            `step_id` of an earlier `send_email` step. Used with `source:
            email_step` (flows only).
        metric:
          type: string
          enum:
            - sent
            - delivered
            - opened
            - clicked
            - bounced
            - unsubscribed
          description: 'Email engagement metric. Used with `source: email_step`.'
        operator:
          type: string
          description: >-
            Comparison operator. Strings: `equals`, `not_equals`, `contains`,
            `not_contains`, `starts_with`, `ends_with`. Numbers/dates: `equals`,
            `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`,
            `less_than_or_equal`. Booleans: `is_true`, `is_false`. Any:
            `is_empty`, `is_not_empty`. Membership: `is_member`,
            `is_not_member`. Activity: `has_activity`, `has_no_activity`.
            Shorthand aliases (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`,
            `member_of`) are accepted.
        value:
          description: Comparison value, when the operator takes one.
        timeWindow:
          type: object
          properties:
            amount:
              type: integer
              minimum: 1
              maximum: 1000
              description: Window size.
            unit:
              type: string
              enum:
                - hour
                - day
                - week
                - month
                - year
              description: Window unit.
          description: Optional look-back window for activity conditions.
      required:
        - operator
    BlastDetails:
      type: object
      properties:
        blast_recipient_count:
          type: integer
          description: Contacts targeted.
        blast_qualified_count:
          type: integer
          description: Contacts that qualified at send time.
        blast_sent_count:
          type: integer
          description: Messages sent.
        blast_failed_count:
          type: integer
          description: Messages that failed to send.
        blast_blocked_count:
          type: integer
          description: Contacts suppressed (e.g. unsubscribed).
        blast_audience_truncated:
          type: boolean
          description: Whether the audience was truncated.
        blast_delivered_count:
          type: integer
          description: Messages delivered.
        blast_opened_count:
          type: integer
          description: Unique opens.
        blast_clicked_count:
          type: integer
          description: Unique clicks.
        blast_bounced_count:
          type: integer
          description: Bounces.
        blast_spam_count:
          type: integer
          description: Spam complaints.
        blast_unsubscribed_count:
          type: integer
          description: Unsubscribes attributed to the blast.
      description: Send and engagement counters.
    ApprovalReadiness:
      type: object
      properties:
        ready:
          type: boolean
          description: Whether the blast can be scheduled or sent.
        missing:
          type: array
          items:
            type: string
          description: Blocking requirements, e.g. `email_approval`, `schedule`.
        warnings:
          type: array
          items:
            type: string
          description: Non-blocking issues, e.g. `empty_static_audience`.
      description: >-
        Readiness summary included on draft blasts and on `campaign_not_ready`
        errors.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, e.g. `Authorization: Bearer tented_...`. Create keys
        in Workspace Settings → API Keys.

````