docs(chat): add startIndex to GET /api/chat/{chatId}/stream
Contract for the resume route in chat#1923. Docs-first: this lands before the api PR that implements it.
The gap
GET /api/chat/{chatId}/stream is already documented (api-reference/chat/workflow-stream.mdx, spec block in api-reference/openapi/research.json) and cross-referenced from POST /api/chat, POST /api/chat/runs and GET /api/chat/runs/{runId}. What it lacks is any way to say where to resume from — so a reconnecting client can only replay the whole turn from chunk zero.
Worth flagging for whoever picks up the api side: the endpoint is documented but not implemented. api/app/api/chat/[chatId]/ contains only stop/. This is documented-but-missing drift, not the usual reverse.
What this adds
startIndex | optional query param, integer, minimum: 0 — zero-based index of the first chunk to return. Omit for a fresh reader (page load, or watching a headless POST /api/chat/runs run for the first time). |
400 | startIndex present but not a non-negative integer. Reuses the existing ChatStreamErrorResponse schema. |
Documented responses are now 200 / 204 / 400 / 401 / 403 / 404.
Why it's needed
Reproduced on prod 2026-08-02 (chat#1923): a long turn's SSE stream ended at ~123 s with a clean [DONE] and no finish chunk while the workflow ran on to completion. The client received 6 of 13 iterations and froze; everything after was generated and persisted but never delivered. The Workflow SDK documents getReadable({ startIndex }) as "useful for reconnecting after timeouts or network interruptions", and upstream vercel-labs/open-agents ships exactly this parameter on its equivalent route.
Verification
- Edit is purely additive:
20 insertions(+), 0 deletions(-). - Applied via anchored text edits rather than load→dump:
json.dumps(json.load(f), indent=2)does not round-trip this file byte-for-byte (165,132 → 165,567 bytes), so a rewrite would have produced a large spurious diff. - Re-validated after editing: file parses, params resolve to
[chatId(path,string), startIndex(query,integer)], responses to[200, 204, 400, 401, 403, 404]. api-reference/chat/workflow-streamis already present indocs.jsonnav (line 66), so no nav change is needed.
Merge order
docs → api → chat. This PR first; the api route is written against it, and the chat client reconnect depends on the route.
🤖 Generated with Claude Code
Summary by cubic
Adds startIndex to GET /api/chat/{chatId}/stream so clients can resume SSE from a specific chunk instead of replaying the whole turn. Aligns the streaming contract with chat#1923.
- New Features
- Optional
startIndexquery param (integer,minimum: 0): zero-based index of the first chunk to return. Omit to stream from the beginning. - Adds
400whenstartIndexis provided but not a non-negative integer (usesChatStreamErrorResponse). - Response codes documented:
200,204,400,401,403,404.
- Optional