Ask (assistant)

POST /v1/ask is the REST counterpart of the buzzabout__ask MCP tool. Hand it a prompt, optionally a chat_id to continue an existing conversation, optionally scoping to particular datasets, and it returns the assistant's reply.

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"
  }
}

{
  "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 response carries:

• text — markdown body, including inline post citations as [label](post:source:id) links (see Reference types).
• references[] — a flat list of typed pointers ({ type, id }) into buzzabout resources (patterns, datasets, research previews, pattern-detection runs, etc.).
• chat_id + message_id — the assistant chose a chat for this turn. Pass chat_id back on the next call to continue the same conversation.

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

# First turn
RESPONSE=$(curl -X POST https://api.buzzabout-staging.com/v1/ask \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Find the top hooks for cold brew posts" }')

CHAT_ID=$(echo "$RESPONSE" | jq -r .data.chat_id)

# Second turn -- continues the same chat
curl -X POST https://api.buzzabout-staging.com/v1/ask \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"Now compare the top hooks on Reddit vs TikTok\",
    \"chat_id\": \"$CHAT_ID\"
  }"

Scoping with context

The optional context field accepts arrays of dataset_ids and audience_dataset_ids. The assistant will prioritise those resources when reasoning.

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.
• buzzabout__ask (MCP) — same shape, MCP transport.