Audiences
Audiences describe who content serves. Each profile may reference an article writing style, products and existing Brand Knowledge documents. Shared style rules take precedence over audience guidance. Product references do not select products or extend their capabilities.
All endpoints require a Bearer API key and brand access. Reads require read:basic. Writes require write:brand_profile, API writes enabled for the workspace and an Idempotency-Key header.
| Method | Path | Body |
|---|---|---|
| GET | /v1/brands/{brand_id}/audiences | None. Supports limit and cursor. |
| POST | /v1/brands/{brand_id}/audiences | { "fields": { "name": "Operations teams", "description": "Teams evaluating workflow software." } } |
| PATCH | /v1/brands/{brand_id}/audiences/{audience_id} | { "revision": 2, "fields": { ... } } |
| POST | /v1/brands/{brand_id}/audiences/{audience_id}/archive | { "revision": 2 } |
| POST | /v1/brands/{brand_id}/audience-default | { "audience_id": "uuid" }, or null to clear |
| POST | /v1/brands/{brand_id}/audience-generation | { "request_key": "uuid" } |
Query parameters
The GET endpoint accepts these parameters. Writes accept none.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Maximum rows to return, from 1 to 100. Default 20. |
cursor | string | optional | Opaque next_cursor from the previous response. |
Response
The list returns active profiles in data. Its meta includes default_audience_id, general_description and generation (status, request ID and inserted count). Create and update return { "audience": { ... } } within data.
{
"data": [],
"meta": { "default_audience_id": null, "general_description": "", "generation": null },
"pagination": { "next_cursor": null, "has_more": false }
}Updates replace all editable fields and associations. Read the current profile first, preserve fields you want to keep and supply its revision. Stale revisions return a conflict. References must belong to this brand. Archived profiles cannot be selected for new work.
Field within fields | Limit or behavior |
|---|---|
name | Required, 1 to 120 characters |
description | Required, 1 to 10,000 characters |
goals, pain_points, buying_questions, knowledge_level, guidance | Optional strings, up to 10,000 characters each |
custom_fields | Ordered array of up to five { "label": "...", "value": "..." } entries. Unique labels up to 60 characters; values up to 10,000 each. |
preferred_style_id | Article style UUID or null |
product_ids | Up to 20 product UUIDs |
Text limits apply independently to each field, with no shared character budget. Audience create and update requests allow up to 1 MB of JSON. Descriptions, guidance and custom fields are reference data. They cannot override system constraints or explicit style rules.
Generation runs in the background and appends up to five distinct, supported profiles. It may produce none when sources are insufficient. Poll the list endpoint for generation.status, including pending, running, completed, empty, failed or skipped. Reuse request_key when retrying delivery; use a new key to request another generation attempt. Generation preserves edits and defaults.
Removing an audience archives it, preserves historical snapshots and clears it as the brand default. Saved selections referencing unavailable audiences fall back to General brand audience. No default is required or assigned automatically.
Content workflows distinguish { "mode": "brand_default" }, { "mode": "general" } and { "mode": "selected", "primary_id": "uuid", "secondary_ids": [] }. Up to two secondary audiences can contribute relevant concerns. The primary audience controls emphasis and may supply an article style. Social identities retain their channel voice and language.