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.

OpenAPI spec

The full machine-readable spec is published at https://api.buzzabout.ai/openapi.json — this is the same document that powers the playground on every endpoint page in these docs. Codegen-friendly; rebuilt on each release.

A hosted Swagger UI lives at https://api.buzzabout.ai/docs for quick exploration outside the docs site.

Authentication

Every request needs an x-api-key header:

x-api-key: bz_live_...

See authentication for key lifecycle and team semantics.

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 returns an empty body — used for soft-deletes, pause/resume, and other no-content writes.

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 carries an account_id (shared with the rest of the team) plus a user_id (the acting seat):

• Account-shared resources — datasets, mentions, audience datasets, audience profiles, tracking agents, pattern detections, custom parameters — are visible to every key on the account.
• Chats are user-owned: only the seat that created a chat can read it. Cross-seat lookups return 404. See Chats.
• Resource ids on inputs must reference resources owned by the calling account — otherwise the endpoint returns 404 instead of 403 (existence is hidden).
• Global mentions and audience-profiles endpoints implicitly scope to your account; passing dataset_ids / audience_dataset_ids only narrows further.

Endpoint groups

Next steps

• Reference types — how assistant references[] and inline post links resolve.
• Rate limits — the per-route quotas.
• Pricing — per-result credit costs.