Audiences API

Define audience segments with rule-based targeting. Audiences control which end users see specific flows, surveys, and other content. All endpoints require JWT authentication.

List Audiences

curl "https://api.breakground.io/api/audiences?page=1&limit=20&search=power" \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Param	Type	Default	Description
page	string	1	Page number
limit	string	20	Results per page
search	string	—	Filter audiences by name

Response:

{
  "data": [
    {
      "id": "aud-1234-...",
      "name": "Power Users",
      "description": "Users with 10+ sessions who are admins",
      "ruleTree": { "logicalOperator": "AND", "rules": [] },
      "tenantId": "t1-...",
      "createdAt": "2026-01-05T10:00:00.000Z",
      "updatedAt": "2026-02-20T14:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 8, "totalPages": 1 }
}

Create Audience

curl -X POST https://api.breakground.io/api/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Power Users",
    "description": "Admins with high session counts",
    "ruleTree": {
      "logicalOperator": "AND",
      "rules": [
        { "field": "traits.sessionCount", "operator": "gte", "value": 10 },
        { "field": "role", "operator": "eq", "value": "admin" }
      ]
    }
  }'

Required fields: name, ruleTree. Optional: description.

The ruleTree is a recursive structure. Each node can contain field/operator/value for a leaf rule, or logicalOperator with nested rules for group conditions. Supported operators include: eq, neq, gt, lt, gte, lte, contains, not_contains, in, not_in, exists, not_exists, regex, starts_with, ends_with.

Get Audience

curl https://api.breakground.io/api/audiences/:id \
  -H "Authorization: Bearer $TOKEN"

Returns the full audience definition including its rule tree.

Update Audience

curl -X PATCH https://api.breakground.io/api/audiences/:id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Enterprise Admins", "ruleTree": { "field": "role", "operator": "eq", "value": "admin" } }'

All fields are optional. Only provided fields are modified (partial update).

Delete Audience

curl -X DELETE https://api.breakground.io/api/audiences/:id \
  -H "Authorization: Bearer $TOKEN"

Soft-deletes the audience (sets deletedAt). The request is rejected with AUDIENCE_IN_USE / HTTP 409 if any flow, tooltip, beacon, survey, journey, task list, NPS survey, announcement, self-help widget, or experiment still references the audience — remove those references first. A deleted audience can be brought back via POST /api/audiences/:id/restore.

Evaluate Audience

curl -X POST https://api.breakground.io/api/audiences/:id/evaluate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-42",
    "traits": { "plan": "enterprise", "sessionCount": 25 },
    "role": "admin",
    "device": { "type": "desktop", "browser": "Chrome" }
  }'

Tests whether a user context matches the audience rules. Returns a boolean matches result along with the count of matched and total rules.

Response:

{
  "data": {
    "matches": true,
    "audienceId": "aud-1234-...",
    "context": { "userId": "user-42", "role": "admin" },
    "matchedRules": 2,
    "totalRules": 2
  }
}