API overview

The Buzzabout REST API is a thin layer over the same primitives the web app uses. Everything you can do in the product, you can do through this API.

Base URL

https://api.buzzabout.ai

All endpoints live under /v1. Examples in these docs use absolute URLs so they're easy to copy.

Authentication

Every request needs an x-api-key header:

x-api-key: bz_live_...

See authentication for key lifecycle, OAuth, and headless MCP.

Content type

JSON in, JSON out. Send Content-Type: application/json on any request that has a body.

Response envelope

Every response is wrapped in a discriminated envelope. The top-level status field tells you which shape you got:

{
  "status": "success",
  "data": { "...": "..." }
}

{
  "status": "success",
  "data": [ { "...": "..." }, { "...": "..." } ],
  "has_next": true,
  "cursor": "eyJjcmVhdGVkX2F0IjogMTcxNDU2NDg5MCwgImlkIjogImRzXzAxSCJ9"
}

{
  "status": "client_error",
  "error_code": "dataset_not_found",
  "detail": "Dataset not found",
  "transient": false
}

status collapses the HTTP status class:

Successful 2xx responses always carry a data field. Error responses carry error_code, detail, and transient (when true, retrying the same request later may succeed).

A 204 No Content (used for DELETE /v1/datasets/{id} and DELETE /v1/audience_datasets/{id}) returns an empty body.

Pagination

List endpoints use cursor-based pagination. Pass limit and cursor:

The response includes has_next: bool and cursor: string \| null. When has_next is false, the cursor is null and the page is the last one.

Cursors are sort-aware on mentions / audience_profiles. If you change the sort field between calls, request a fresh page (don't pass the old cursor — it'll fail validation).

Errors

The error_code is stable — match on it, not on the human-readable detail.

Account scoping

Every API key is tied to one account. All read and write paths are scoped to that account:

• Resources you create (datasets, audience datasets) belong to your account; nobody else can see or modify them.
• Resource ids on inputs (e.g. dataset_ids, audience_dataset_ids, source_dataset_id) must reference resources you own — otherwise the endpoint returns a 404 instead of a 403 (existence is hidden).
• The global mentions and audience-profiles endpoints implicitly scope to your account; passing dataset_ids / audience_dataset_ids is optional and only narrows further.

Endpoint groups