buzzabout docsChats
Two read endpoints — chat metadata and paginated message history for a single chat.
Chats are user-owned: each chat carries a user_id matching the seat
that created it. Reading is scoped to the same seat that created
the chat — other team members (including the team owner) get a 404
when looking up another seat's chat.
Team-member semantics
Each API key carries both account_id (resource scope, shared
across the team) and user_id (acting seat). Account-shared
resources — datasets, mentions, tracking agents, custom parameters —
are readable by every key on the account. Chats are the exception:
they are private to the creating seat.
Pricing
Free — no credits charged. The cost lives on the
POST /v1/ask turn that created the chat. See
Pricing.
Endpoints
Authorization
ApiKeyAuth Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).
In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/chats/string"{
"status": "info",
"data": {
"created_at": 1717200000,
"id": "ch_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
"name": "Reddit teardown — Aug"
}
}{
"status": "info",
"error_code": "chat_not_found",
"detail": "string",
"transient": true
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Authorization
ApiKeyAuth Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).
In: header
Path Parameters
Query Parameters
251 <= value <= 100Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/chats/string/messages"{
"status": "info",
"data": [
{
"id": "string",
"role": "user",
"text": "string",
"context": {
"dataset_ids": [
"string"
],
"collection_ids": [
0
],
"post_refs": [
{
"id": "string",
"source": "reddit"
}
],
"prompt": {
"id": "string"
},
"research_filters": {
"sources": [
"string"
],
"time": "string",
"date_range": {},
"language": "string",
"country_code": "string",
"depth": 1,
"preview_id": "string"
}
},
"created_at": 0
}
],
"has_next": true,
"cursor": "string"
}{
"status": "info",
"error_code": "chat_not_found",
"detail": "string",
"transient": true
}{
"status": "info",
"error_code": "invalid_cursor",
"detail": "string",
"transient": true
}Chat metadata
GET /v1/chats/{id} returns the bare bones:
idname(nullable; the assistant assigns one after the first few turns)tracking_agent_id(set when the chat belongs to a tracking agent's dedicated dialogue, otherwisenull)created_at
Heavier fields the in-app UI uses (summary, blocks, read,
include_comments, include_blocks, short_preview_message) are
intentionally absent from the public surface.
Messages
GET /v1/chats/{id}/messages is cursor-paginated. Default
limit=25, max 100. Returned ascending by created_at so the
oldest message is first — render top-to-bottom without re-sorting.
Each row carries:
// user
{ "id": "...", "role": "user", "text": "...", "context": {...}, "created_at": "..." }
// assistant
{ "id": "...", "role": "assistant", "text": "...", "references": [...], "created_at": "..." }Assistant text is always markdown (the public surface enforces
output_format=markdown per turn). Citations follow the
reference types conventions — typed pointers
in references[], inline post links in text.
Creating chats
Chats are created implicitly via POST /v1/ask.
There is no dedicated create endpoint on the public surface.
Next steps
- Ask — create or continue a chat.
- Reference types — how assistant references resolve to underlying resources.
- Tracking agents — agent-owned
chats live under
tracking_agent_id.