Reference types

Assistant messages and tracking-agent alerts return text alongside a references[] array — a flat list of typed pointers into buzzabout resources. Six entries point to entities the assistant produced or referenced (datasets, patterns, …); a seventh, post, captures every inline post citation in the assistant's prose.

This page enumerates both shapes and the endpoint you call to resolve each one.

Entity references

Each entity entry in references[] is:

{
  "type": "<one of the six entity types below>",
  "id":   "<ksuid or canonical id>"
}

No inline payload — clients fetch the underlying resource on demand. In practice an assistant turn returns ≤3 entity references; the round-trip cost is negligible and the contract stays stable as the underlying resources grow.

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.

Post references

Every unique post the assistant cites surfaces as a structured post entry in references[] — not as inline markdown:

{
  "type":        "post",
  "source":      "tiktok",
  "id":          "7392184932",
  "citation":    1,
  "start_index": 4,
  "end_index":   7
}

In the returned text, each [label](post:source:id) markdown link is rewritten to a bracketed numeric marker — [1], [2], … — academic-citation style. Numbering is per-message and assigned in first-appearance order over unique (source, id) tuples: the first unique post cited gets 1, the second unique post gets 2, and so on. Re-citing the same post in the same message re-uses its number — every occurrence of that post in the prose shows the same [N] marker, and the post appears once in references[].

The half-open start_index / end_index pair points at the first [N] occurrence in the rewritten text: slicing text[start_index:end_index] returns exactly f"[{citation}]" (e.g. "[1]"). To locate every occurrence of a citation, string-search the text for the literal bracketed marker.

Example: an assistant turn that cites a TikTok post twice and a Reddit post once produces this shape:

text:       "See [1] and [2]. As [1] also notes…"
references: [
  { "type": "post", "source": "tiktok", "id": "7392184932", "citation": 1, "start_index": 4,  "end_index": 7 },
  { "type": "post", "source": "reddit", "id": "t3_1oqliu8", "citation": 2, "start_index": 12, "end_index": 15 }
]

To resolve (source, id) back to a full mention payload, call 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.

Where this surface appears

• POST /v1/ask (and the same surface via MCP) — assistant turns. The reply text and references[] come back via GET /v1/chats/{chat_id}/messages/{message_id} once the turn settles.
• 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's text carries inline post citations as post references and, for cross-dataset patterns, a pattern entity reference.

tracking_agent is not a reference type — agents are entities you manage, not citations the assistant produces.

Next steps

• Mentions — post_refs lookup path for resolving cited posts back to the full mention shape.
• Patterns — what's behind a pattern reference once you expand it.
• POST /v1/ask — where references first appear in a typical agent loop.