Audiences API

The Audiences API returns the audience profiles configured for the caller's company. Audiences are used by AutoGenerator and other generation endpoints to tailor content tone, depth, and structure.

Full schemas and try-it-out forms live in the interactive API Reference.

Authentication

All endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

See Getting Started → Authentication.

Response envelope

Every endpoint returns the canonical envelope: { "success": true, "data": { ... } } on success or the standard error envelope on error.

Endpoint summary

Method	Path	Description	Sync/Async
GET	/api/v1/audiences	List audience profiles	Sync
POST	/api/v1/audiences/search	Search audience profiles	Sync

All endpoints are in the auto_generator rate-limit category. See Developer Guide → Usage quotas and rate limits.

---

GET /api/v1/audiences — List audiences

Returns the audiences configured for the caller's company. Pagination is not yet implemented; the full list is returned.

Query parameters

Parameter	Type	Required	Description
feature	string	no	Filter by feature scope.
id	string	no	Filter to a single audience by id.
sort	string	no	Sort expression (for example name:asc).

Example

curl "https://api.prezent.ai/api/v1/audiences?sort=name:asc" \
  -H "Authorization: Bearer $API_KEY"

Success response (200)

{
  "success": true,
  "data": {
    "items": [
      { "id": "aud_exec", "name": "Executives" },
      { "id": "aud_sales", "name": "Sales team" }
    ],
    "next_cursor": null
  }
}

next_cursor is currently always null (cursor-based pagination is on the roadmap).

---

POST /api/v1/audiences/search — Search audiences

Free-text and field-filtered search across audience profiles.

Query parameters

Parameter	Type	Required	Description
feature	string	no	Filter by feature scope.

Request body

Field	Type	Required	Description
query	string	no	Free-text search query.
id	string	no	Filter to a single audience by id.
sort	string	no	Sort expression.
filterBy	object	no	Field-level filter.
filterByCollection	object	no	Collection-level filter.
fields	array of string	no	Subset of fields to return.
extraFields	array of string	no	Additional fields to include beyond defaults.
limit	integer	no	Maximum number of results (default 15).

Example

curl -X POST https://api.prezent.ai/api/v1/audiences/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "executive", "limit": 10 }'

Success response (200)

{
  "success": true,
  "data": {
    "items": [
      { "id": "aud_exec", "name": "Executives" }
    ],
    "next_cursor": null
  }
}

---

Errors

Common error codes:

• 400 — INVALID_INPUT.
• 401 — INVALID_API_KEY, EXPIRED_API_KEY, UNAUTHORIZED.
• 404 — ENDPOINT_NOT_FOUND.
• 429 — RATE_LIMIT_EXCEEDED, THROTTLED.
• 500 / 503 / 504 — standard server-side codes.

See the full catalog in Developer Guide → Error codes.