Annotations and Citations

Responses streaming includes annotations you can use to build rich, trustworthy UIs. This page explains what to expect and how to render them.

What are annotations?

Annotations attach metadata to output text so you can:

• Render citation markers that refer to source material.
• Attribute content to tool outputs.
• Highlight the context that the model used when answering.

You will see annotations packaged alongside output_text items in the stream and the final response object.

Rendering citations

When citations are available, you’ll receive both text deltas and a growing annotations array for the current content part. A simple approach is to display bracketed indices [1], [2], etc., and show a references panel mapping each index to metadata (e.g., filename, URL, or other reference info available in annotations).

Pseudocode:

if (event.type === 'response.output_text.delta') {
  ui.appendText(event.delta);
}

if (event.type === 'response.output_text.delta' || event.type === 'response.output_text.done') {
  const annotations = currentContent.annotations; // track from events
  renderReferences(annotations);
}

Context inputs

If you pass background material as messages with name set to "context" (for example, input_text items marked as context), annotations can help you distinguish what came from user-supplied context. This is useful when mixing private notes with retrieved sources.

Example input snippet:

{
  "type": "message",
  "role": "user",
  "name": "context",
  "content": [
    { "type": "input_text", "text": "Roadmap excerpt...", "name": "context" }
  ]
}

Tool outputs

When tools such as File Search or MCP tools are used, output may include markers that allow you to link final answers back to tool-generated material. Treat these similarly to citations: present a reference list and let users navigate between text and source snippets.

UI guidelines

• Keep the main answer readable; place references in a sidebar or footnotes section.
• Let users expand a citation to preview the corresponding source text or resource.
• Provide clear labels for user-provided context vs retrieved sources.
• Preserve streaming interactivity by appending text deltas immediately, then updating references incrementally.