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

# Create audience

> Create an audience in a page. Provide `personId` to link the audience to an existing person; the audience is then addressable by that person's route key. Linking can only be set at creation time — updating an audience cannot change its person link.



## OpenAPI

````yaml /services/external-actor-gateway-service/openapi.yaml post /v0/pages/{page_id}/audiences
openapi: 3.1.0
info:
  contact:
    email: api-support@tryarchitect.com
    name: Architect
    url: https://tryarchitect.com
  description: >-
    The Customer API lets you manage pages, audiences, persons, accounts, page
    links, analytics, and webhook subscriptions.


    ## Authentication

    Send your API key in the `x-api-key` header on every request.


    ## Terminology

    - **Page**: a top-level customer experience container.

    - **Audience**: a targeted experience that belongs to a Page.

    - **Version**: a generated or editable Audience state, including drafts and
    published versions.

    - **Person**: an individual contact record.


    ## Pagination

    Collection endpoints use `limit` and `cursor`. When another page is
    available, pass the returned `nextCursor` value back as `cursor`. When there
    are no more results, `nextCursor` is `null`.


    ## Webhooks

    Create subscriptions with `POST /v0/webhook_subscriptions`. The
    `signingSecret` is returned only once, when the subscription is created, so
    store it securely.


    Webhook deliveries are sent as `POST` requests with these headers:

    - `X-Webhook-Signature-256`: HMAC-SHA256 of the raw request body, prefixed
    with `sha256=`

    - `X-Webhook-Timestamp`: Unix timestamp in milliseconds used when the
    signature was generated


    Webhook deliveries are at-least-once. Use `eventId` for idempotency and
    return a `2xx` response quickly after persisting work.


    Example delivery body:

    ```json

    {
      "timestamp": "2024-01-15T10:30:00.000Z",
      "eventId": "event_01j5k9m7n8p9q2r3s4t5v6w7x8",
      "payload": {
        "type": "page.version.created",
        "pageId": "page_01j5k9m7n8p9q2r3s4t5v6w7x8",
        "versionId": "<audience_version_id>",
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    }

    ```


    Version webhook event names currently use the internal `page.version.*`
    namespace. In Customer API terms, these correspond to Audience version
    lifecycle events.
  title: Architect - Customer API
  version: 0.0.1
servers:
  - description: Production environment
    url: https://api.tryarchitect.com
  - description: Beta environment
    url: https://api.beta.tryarchitect.com
  - description: Local environment
    url: http://localhost:25001
security:
  - apiKey: []
tags:
  - name: Pages
    description: Page management operations
  - name: Analytics
    description: Analytics and session read operations
  - name: Audiences
    description: Audience management operations
  - name: Audience Versions
    description: Audience version management operations
  - name: Audience Messages
    description: Audience message editing operations
  - name: Page Link Blocks
    description: Shared footer and navigation link block management operations
  - name: Page Links
    description: Page link management operations
  - name: Tenant Domains
    description: Tenant domain discovery operations
  - name: Assets
    description: Asset management operations
  - name: Persons
    description: Person management operations
  - name: Person Logs
    description: Person log ingestion operations
  - name: Accounts
    description: Account management operations
  - name: Account Activity
    description: Merged account and linked person activity operations
  - name: Account Logs
    description: Account log ingestion operations
  - name: Webhook Subscriptions
    description: Webhook subscription management operations
paths:
  /v0/pages/{page_id}/audiences:
    post:
      tags:
        - Audiences
      summary: Create audience
      description: >-
        Create an audience in a page. Provide `personId` to link the audience to
        an existing person; the audience is then addressable by that person's
        route key. Linking can only be set at creation time — updating an
        audience cannot change its person link.
      operationId: createAudience
      parameters:
        - $ref: '#/components/parameters/PageIdPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAudienceRequest'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/PostAudienceResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
components:
  parameters:
    PageIdPath:
      in: path
      name: page_id
      description: page_id parameter
      required: true
      schema:
        type: string
  schemas:
    CreateAudienceRequest:
      type: object
      properties:
        actionFormIdOverride:
          type: string
        actionFormInstructionsOverride:
          type: string
        actionUrlOverride:
          $ref: '#/components/schemas/Url'
        customName:
          type: string
          minLength: 1
        metadataOverride:
          $ref: '#/components/schemas/Metadata1'
        personId:
          type: string
          minLength: 1
          description: >-
            Optional person to link this audience to. When set, the audience is
            created linked to the person so that it is addressable by the
            person's route key and appears under the person. The person must
            already exist for the authenticated tenant.
        publishBehavior:
          default: publish
          type: string
          enum:
            - draft
            - publish
        supplementaryContext:
          type: string
          minLength: 1
      required:
        - publishBehavior
      additionalProperties: false
    Url:
      type: string
      format: uri
      description: URL to open when action is triggered
    Metadata1:
      type: object
      properties:
        title:
          type: string
          maxLength: 70
        description:
          type: string
          maxLength: 160
        keywords:
          type: array
          items:
            type: string
        author:
          type: string
          maxLength: 100
        robots:
          type: array
          items:
            type: string
            enum:
              - index
              - noindex
              - follow
              - nofollow
              - noarchive
              - nosnippet
              - noimageindex
              - none
        canonicalUrl:
          $ref: '#/components/schemas/Url'
        ogTitle:
          type: string
          maxLength: 60
        ogDescription:
          type: string
          maxLength: 110
        ogType:
          type: string
          enum:
            - website
            - article
            - product
            - profile
        ogImage:
          $ref: '#/components/schemas/OgImage'
        ogImageAlt:
          type: string
          maxLength: 420
        ogSiteName:
          type: string
          maxLength: 100
        ogUrl:
          $ref: '#/components/schemas/Url'
        twitterCard:
          type: string
          enum:
            - summary
            - summary_large_image
            - app
            - player
        twitterTitle:
          type: string
          maxLength: 70
        twitterDescription:
          type: string
          maxLength: 200
        twitterImage:
          $ref: '#/components/schemas/OgImage'
        twitterImageAlt:
          type: string
          maxLength: 420
        twitterSite:
          $ref: '#/components/schemas/TwitterSite'
        twitterCreator:
          $ref: '#/components/schemas/TwitterSite'
        themeColor:
          $ref: '#/components/schemas/ThemeColor'
      additionalProperties: false
    PostAudience:
      type: object
      properties:
        actionFormIdOverride:
          anyOf:
            - type: string
            - type: 'null'
        actionFormInstructionsOverride:
          anyOf:
            - type: string
            - type: 'null'
        actionUrlOverride:
          anyOf:
            - type: string
            - type: 'null'
        archivedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        audienceId:
          type: string
        computedName:
          type: string
        createdAt:
          $ref: '#/components/schemas/UnnamedSchema'
        customName:
          anyOf:
            - type: string
            - type: 'null'
        effectiveMetadata:
          $ref: '#/components/schemas/Metadata'
        effectiveName:
          type: string
        flags:
          type: array
          items:
            type: string
            enum:
              - home_page
        isNewPageAgent:
          type: boolean
        latestVersion:
          anyOf:
            - $ref: '#/components/schemas/PostVersion'
            - type: 'null'
        metadataOverride:
          $ref: '#/components/schemas/Metadata'
        pageId:
          type: string
        personId:
          anyOf:
            - type: string
            - type: 'null'
        personRouteKey:
          anyOf:
            - type: string
            - type: 'null'
        publishedVersion:
          anyOf:
            - $ref: '#/components/schemas/PostVersion'
            - type: 'null'
        status:
          type: string
          enum:
            - archived
            - cancelled
            - draft
            - pending
            - processing
            - published
            - queued
        supplementaryContext:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - actionFormIdOverride
        - actionFormInstructionsOverride
        - actionUrlOverride
        - archivedAt
        - audienceId
        - computedName
        - createdAt
        - customName
        - effectiveName
        - flags
        - isNewPageAgent
        - latestVersion
        - pageId
        - personId
        - personRouteKey
        - publishedVersion
        - status
        - supplementaryContext
      additionalProperties: false
    Error:
      properties:
        code:
          enum:
            - UNAUTHORIZED
            - FORBIDDEN
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - RATE_LIMITED
            - INTERNAL
            - SERVICE_UNAVAILABLE
          examples:
            - VALIDATION_ERROR
            - UNAUTHORIZED
            - NOT_FOUND
          type: string
        detail:
          examples:
            - Authentication is required
            - Audience not found
            - Default topic titles cannot be updated
          type: string
        details:
          description: >-
            Optional structured details about the error, such as validation
            issues or rate-limit metadata.
          examples:
            - - field: body
                issues:
                  - code: validation_failed
                    message: 'name: Name is required'
                    path:
                      - name
            - limit: 100
              remaining: 0
              resetTime: 1713225600000
              retryAfter: 60
          oneOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - additionalProperties: true
              type: object
        requestId:
          examples:
            - req_01j5k9m7n8p9q2r3s4t5v6w7x8
          type: string
        status:
          example: 400
          type: number
        title:
          examples:
            - Bad Request
            - Unauthorized
            - Not Found
          type: string
        type:
          examples:
            - https://api.tryarchitect.com/errors/validation_error
            - https://api.tryarchitect.com/errors/not_found
          type: string
      required:
        - code
        - detail
        - requestId
        - status
        - title
        - type
      type: object
    OgImage:
      type: object
      properties:
        type:
          type: string
          const: file
        fileId:
          type: string
      required:
        - type
        - fileId
      additionalProperties: false
    TwitterSite:
      type: string
      pattern: ^@[A-Za-z0-9_]{1,15}$
    ThemeColor:
      type: string
      pattern: ^#[0-9A-Fa-f]{6}$
    UnnamedSchema:
      type: string
      format: date-time
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
    Metadata:
      type: object
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
        description:
          anyOf:
            - type: string
            - type: 'null'
        keywords:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        author:
          anyOf:
            - type: string
            - type: 'null'
        robots:
          anyOf:
            - type: array
              items:
                type: string
                enum:
                  - index
                  - noindex
                  - follow
                  - nofollow
                  - noarchive
                  - nosnippet
                  - noimageindex
                  - none
            - type: 'null'
        canonicalUrl:
          anyOf:
            - type: string
            - type: 'null'
        ogTitle:
          anyOf:
            - type: string
            - type: 'null'
        ogDescription:
          anyOf:
            - type: string
            - type: 'null'
        ogType:
          anyOf:
            - type: string
              enum:
                - website
                - article
                - product
                - profile
            - type: 'null'
        ogImageUrl:
          anyOf:
            - type: string
            - type: 'null'
        ogImageFileId:
          anyOf:
            - type: string
            - type: 'null'
        ogImageAlt:
          anyOf:
            - type: string
            - type: 'null'
        ogSiteName:
          anyOf:
            - type: string
            - type: 'null'
        ogUrl:
          anyOf:
            - type: string
            - type: 'null'
        twitterCard:
          anyOf:
            - type: string
              enum:
                - summary
                - summary_large_image
                - app
                - player
            - type: 'null'
        twitterTitle:
          anyOf:
            - type: string
            - type: 'null'
        twitterDescription:
          anyOf:
            - type: string
            - type: 'null'
        twitterImageUrl:
          anyOf:
            - type: string
            - type: 'null'
        twitterImageFileId:
          anyOf:
            - type: string
            - type: 'null'
        twitterImageAlt:
          anyOf:
            - type: string
            - type: 'null'
        twitterSite:
          anyOf:
            - type: string
            - type: 'null'
        twitterCreator:
          anyOf:
            - type: string
            - type: 'null'
        themeColor:
          anyOf:
            - type: string
            - type: 'null'
      additionalProperties: false
    PostVersion:
      type: object
      properties:
        archivedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        audienceId:
          type: string
        becameDraftAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        cancelledAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/UnnamedSchema'
        isNewPageAgent:
          type: boolean
        obsoleteAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        publishedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        queueDurationMs:
          anyOf:
            - type: number
            - type: 'null'
        queuedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        status:
          type: string
          enum:
            - archived
            - cancelled
            - draft
            - pending
            - processing
            - published
            - queued
        supplementaryContext:
          anyOf:
            - type: string
            - type: 'null'
        versionId:
          type: string
        versionNumber:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
      required:
        - archivedAt
        - audienceId
        - becameDraftAt
        - cancelledAt
        - createdAt
        - isNewPageAgent
        - obsoleteAt
        - publishedAt
        - queueDurationMs
        - queuedAt
        - status
        - supplementaryContext
        - versionId
        - versionNumber
      additionalProperties: false
  responses:
    PostAudienceResponse:
      description: Audience created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostAudience'
    ValidationError:
      content:
        application/json:
          examples:
            default:
              value:
                code: VALIDATION_ERROR
                detail: 'body - name: Name is required; email: Invalid email address'
                details:
                  - field: body
                    issues:
                      - code: validation_failed
                        message: 'name: Name is required'
                        path:
                          - name
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 400
                title: Bad Request
                type: https://api.tryarchitect.com/errors/validation_error
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The request could not be processed because the path, query string, or
        JSON body was invalid.
    UnauthorizedError:
      content:
        application/json:
          examples:
            default:
              value:
                code: UNAUTHORIZED
                detail: Authentication is required
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 401
                title: Unauthorized
                type: https://api.tryarchitect.com/errors/unauthorized
          schema:
            $ref: '#/components/schemas/Error'
      description: The request did not include valid authentication credentials.
    ForbiddenError:
      content:
        application/json:
          examples:
            default:
              value:
                code: FORBIDDEN
                detail: Multi-tenant API keys are not supported
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 403
                title: Forbidden
                type: https://api.tryarchitect.com/errors/forbidden
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The caller is authenticated but does not have access to the requested
        tenant or operation.
    NotFoundError:
      content:
        application/json:
          examples:
            default:
              value:
                code: NOT_FOUND
                detail: Audience not found
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 404
                title: Not Found
                type: https://api.tryarchitect.com/errors/not_found
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The referenced resource does not exist, is not owned by the requested
        parent, or is not visible to the authenticated tenant.
    ConflictError:
      content:
        application/json:
          examples:
            default:
              value:
                code: CONFLICT
                detail: Default topic titles cannot be updated
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 409
                title: Conflict
                type: https://api.tryarchitect.com/errors/conflict
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The request conflicts with current resource state, lifecycle rules, or
        uniqueness constraints.
    RateLimitError:
      content:
        application/json:
          examples:
            default:
              value:
                code: RATE_LIMITED
                detail: Rate limit exceeded
                details:
                  limit: 100
                  remaining: 0
                  resetTime: 1713225600000
                  retryAfter: 60
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 429
                title: Too Many Requests
                type: https://api.tryarchitect.com/errors/rate_limited
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The authenticated caller has exceeded the current request rate limit
        window.
    InternalServerError:
      content:
        application/json:
          examples:
            default:
              value:
                code: INTERNAL
                detail: An unexpected error occurred
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 500
                title: Internal Server Error
                type: https://api.tryarchitect.com/errors/internal
          schema:
            $ref: '#/components/schemas/Error'
      description: The server encountered an unexpected error while processing the request.
    ServiceUnavailableError:
      content:
        application/json:
          examples:
            default:
              value:
                code: SERVICE_UNAVAILABLE
                detail: The service is temporarily unavailable
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 503
                title: Service Unavailable
                type: https://api.tryarchitect.com/errors/service_unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The service is temporarily unavailable. Retry the request after a short
        delay.
  securitySchemes:
    apiKey:
      description: API key authentication for the External Actor Gateway
      in: header
      name: x-api-key
      type: apiKey

````

## Related topics

- [Create audience version](/docs/api-reference/audience-versions/create-audience-version.md)
- [Changelog](/docs/changelog.md)
- [Create page link](/docs/api-reference/page-links/create-page-link.md)
- [MCP Integration](/docs/overview/integrations/mcp-overview.md)
- [Create webhook subscription](/docs/api-reference/webhook-subscriptions/create-webhook-subscription.md)