buzzabout docsReference types
How references[] and the post:source:id markdown scheme work across chats and the assistant.
Assistant messages and tracking-agent alerts return text alongside a
references[] array — a flat list of typed pointers into buzzabout
resources. Posts are handled differently: they are inlined in text as
markdown links using the internal post:source:id scheme.
This page enumerates both surfaces and the endpoint you call to resolve each one.
Shape
Each entry in references[] is:
{
"type": "<one of the six types below>",
"id": "<ksuid or canonical id>"
}No inline payload — clients fetch the underlying resource on demand. In practice an assistant turn returns ≤3 references; the round-trip cost is negligible and the contract stays stable as the underlying resources grow.
The six types
type | Resolution endpoint |
|---|---|
pattern | GET /v1/patterns/{pattern_id} |
research_preview | GET /v1/research_previews/{preview_id} (hidden; resolved via the assistant directly) |
dataset | GET /v1/datasets/{dataset_id} |
audience_dataset | GET /v1/audience_datasets/{audience_dataset_id} |
custom_parameter_run | GET /v1/custom_parameters/{parameter_id}/runs/{run_id} |
pattern_detection_run | GET /v1/pattern_detections/{run_id} |
research_preview is the working pointer to an in-progress assistant
investigation — the assistant resolves it for you in subsequent turns,
so most clients never need to expand it directly.
Posts are inline, not in references[]
When the assistant cites a post, it inlines it in text as a markdown
link using the scheme:
[label](post:source:id)Example:
This pattern shows up across [@samplerexp's review](post:tiktok:7392184932)
and a Reddit thread on [r/coffee](post:reddit:t3_1oqliu8).The host application is responsible for rewriting these links into UI
that fetches the underlying post via
POST /v1/mentions with post_refs:
{
"post_refs": [
{ "source": "tiktok", "id": "7392184932" },
{ "source": "reddit", "id": "t3_1oqliu8" }
]
}The response carries the same Mention shape as a standard list query.
Why posts are different
Posts can appear dozens of times in a single answer, so inlining them
in references[] would balloon the response. Putting them in text
also keeps them adjacent to the prose that cites them, which is what
most LLMs and renderers expect. A future revision may switch to a
cleaner URI scheme — the markdown form remains stable in v1.
Where this surface appears
POST /v1/askandbuzzabout__ask— assistant turns. Both returntext+references+ optional inline post links.GET /v1/chats/{id}/messages— historical assistant messages carry the same shape per row.GET /v1/tracking_agents/{id}/messages— alerts produced by a running tracking agent. Each alert'stextmay include inline post links and, for cross-dataset patterns, apatternreference.
tracking_agent is not a reference type — agents are entities you
manage, not citations the assistant produces.
Next steps
- Mentions —
post_refslookup path for the inline post links. - Patterns — what's behind a
patternreference once you expand it. - POST /v1/ask — where references first appear in a typical agent loop.