Ask (assistant)

POST /v1/ask hands a message to the buzzabout assistant. Optionally continue an existing chat via chat_id and scope the turn to specific datasets — the assistant returns markdown with inline post citations plus a typed list of references. Already wired buzzabout into Claude / Cursor / ChatGPT? You get the same surface through MCP — see Use in your agent.

Endpoint

curl -X POST "https://example.com/v1/ask" \  -H "Content-Type: application/json" \  -d '{    "context": {      "dataset_ids": [        "ds_abc123"      ],      "post_refs": [        {          "id": "t3_1oqliu8",          "source": "reddit"        }      ]    },    "message": "Summarize the top three signals from these datasets in one paragraph."  }'

{
  "status": "info",
  "data": {
    "chat_id": "ch_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
    "message_id": "msg_2NK4ZG2BqkAxK1nT0RZyZbBmZHN",
    "status": "working"
  }
}

{
  "status": "info",
  "error_code": "insufficient_credits_ask",
  "detail": "string",
  "transient": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

{
  "status": "info",
  "error_code": "ai_assistant_unavailable",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "ai_assistant_timeout",
  "detail": "string",
  "transient": true
}

Response shape

The initial 202 Accepted response uses the success envelope and carries chat_id, message_id and status: "working". It does not contain the completed reply text. Poll the message endpoint below for markdown with inline [label](post:source:id) citations and typed references[] (Reference types). Pass chat_id on later turns to continue the conversation; each new turn can consume charged inference.

The output is always markdown. The endpoint enforces output_format=markdown on the assistant — public clients cannot request openui or other in-app block formats.

Continuing a conversation

import httpx

client = httpx.Client(
    base_url="https://api.buzzabout-staging.com",
    headers={"x-api-key": "bz_live_abcdef1234567890abcdef1234567890"},
)

# First turn
turn1 = client.post(
    "/v1/ask",
    json={"message": "Find the top hooks for cold brew posts"},
).raise_for_status().json()["data"]
chat_id = turn1["chat_id"]

# Second turn — continues the same chat
turn2 = client.post(
    "/v1/ask",
    json={
        "message": "Now compare the top hooks on Reddit vs TikTok",
        "chat_id": chat_id,
    },
).raise_for_status().json()["data"]

Both turns are asynchronous — the response carries a message_id you poll via GET /v1/chats/{chat_id}/messages/{message_id} until status transitions to completed.

Scoping with context

The optional context field accepts:

• dataset_ids — list of dataset ids the assistant should treat as in-scope for the turn. When omitted, the assistant may consult any dataset visible to the account.
• post_refs — up to 50 specific posts to pin into the assistant's working context (each { id, source } — see the schema above).

Filters and other narrowing (sentiment-only, date windows, etc.) live inside the message text — the assistant reads them naturally. There is no structured filter field.

Reading the history

Once you have a chat_id, use GET /v1/chats/{id}/messages to page through the full transcript (user + assistant turns, ascending by created_at).

Next steps

• Chats — read message history and chat metadata.
• Reference types — how references[] and the post:source:id markdown scheme resolve.
• Use in your agent — same surface via MCP for Claude / Cursor / ChatGPT users.