API
Audiences API
Create, preview, and suggest live segments.
Audiences are live rule trees, not static lists.
Endpoints: listProjectAudiences, createAudience, getProjectAudience, updateAudience, deleteAudience, previewAudience, getAudienceReach, createAudienceSuggestions
Scope: read to list, show and read reach; write to preview, create, update, delete and suggest (preview is a POST).
MCP and CLI: list_audiences, get_audience (includeReach), preview_audience, create_audience, update_audience, delete_audience, suggest_audiences — or audryo audiences list|show|preview|create|update|delete|suggest.
Definition shape
Conditions are a declarative AST: groups with and / or, children that are attribute, event, tag or mailing-list rules, or nested groups. At most 25 rules and 3 group levels. An empty conditions list matches every contact:
{ "operator": "and", "conditions": [] }{ "operator": "and", "conditions": [
{ "type": "attribute", "field": "premium", "operator": "equals", "value": false },
{ "type": "event", "name": "signed_up", "operator": "performed" }
] }Creating an audience requires at least one contact in the project. Deleting one that a journey or active campaign still uses returns 409 record_not_destroyed.
Always preview (previewAudience) before you save a production audience. A typo that matches zero people is cheaper to catch here than in a live Journey.
Suggestions
createAudienceSuggestions asks Audryo to propose segments from confirmed data and supported claims from the active Foundation revision. Each suggestion includes rationale and estimated size. Applying one still creates a normal, editable audience — nothing activates a Journey.
Idempotency: send Idempotency-Key on suggestion requests (LLM-backed).
Reach
getAudienceReach is the current membership count (and sample) for a saved audience. It moves as contacts and events change; you do not re-sync the audience itself.