feat(guides): add deep linked citations migration guide #241
Conversation
Add documentation for customers using custom frontends to adopt deep-linked (direct-quote) citations in their Chat API implementations. The guide covers: - Overview of deep-linked citations feature - Prerequisites (Agentic Loop, supported LLM configs) - Response format changes (new referenceRanges[].snippets[] field) - Minimal migration (backward compatibility) - Full migration with code examples (TypeScript/React) - Fetching document content via /getdocuments API - UX guidelines and limitations - Migration checklist 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Move deep-linked citations guide from Chat to a new Migration Guides category under Guides, providing a dedicated section for migration documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `snippets[]` | **New**: An array of direct-quote snippets from the source document that support the statement. | | ||
| | `snippet.text` | The quoted text from the source document. | | ||
| | `snippet.pageNumber` | Optional page number where the snippet appears. | |
There was a problem hiding this comment.
The new guide tells integrators that referenceRanges[].snippets[] include snippet.pageNumber and recommends regenerating client types to pick it up, but the published SearchResultSnippet schema (e.g., openapi/client/split-apis/chat-api.yaml) does not define a pageNumber property at all—rg "pageNumber" openapi returns no matches—so generated clients will not expose this field and the sample code/type hints here will fail. Please drop or update the pageNumber reference until the API schema actually includes it.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Thanks for the review, but this feedback is incorrect — the pageNumber field does exist in the SearchResultSnippet schema.
Evidence:
-
Generated Java Client (SearchResultSnippet.java):
public static final String SERIALIZED_NAME_PAGE_NUMBER = "pageNumber"; @SerializedName(SERIALIZED_NAME_PAGE_NUMBER) private Integer pageNumber;
-
Generated Go Model (model_search_result_snippet.go):
PageNumber int32 `json:"pageNumber,omitempty"`
-
PR that added this field: #176488 - Add page number field to rest_api.SearchResultSnippet
-
Unit tests confirm usage:
TestGetSnippetsFromResult_WithPageNumberandTestGetSnippetsToAttach_WithPageNumbers
The rg "pageNumber" openapi search may have run against a limited subset of files. The field is legitimately part of the schema and actively used in production.
david-hamilton-glean
left a comment
david-hamilton-glean
left a comment
There was a problem hiding this comment.
This looks great. Thanks @chris-freeman-glean. There's some feedback inline but the most important one is to get some 👀 from the endpoint owners.
There was a problem hiding this comment.
@chris-freeman-glean if you haven't already, let's get this reviewed by folks who own the endpoint.
- Add release version info (Q4 2025, REST API in Beta) - Make Agentic Loop prerequisite actionable (set agentConfig.agent) - Specify supported LLM models (OpenAI/Claude, not Gemini) - Restructure JSON example with elision for readability - Fix table path consistency (prefix all with referenceRanges[]) - Fix voice consistency in Full Migration section - Remove redundant Backward Compatibility section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Summary
Content Overview
The guide covers:
referenceRanges[].snippets[]fieldTest plan
pnpm startand verify the page loads at/guides/chat/deep-linked-citations🤖 Generated with Claude Code