docs(chat): add startIndex to GET /api/chat/{chatId}/stream

Merged
SW
4mo ago
+20-0

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

startIndexoptional 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).
400startIndex 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-stream is already present in docs.json nav (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 startIndex query param (integer, minimum: 0): zero-based index of the first chunk to return. Omit to stream from the beginning.
    • Adds 400 when startIndex is provided but not a non-negative integer (uses ChatStreamErrorResponse).
    • Response codes documented: 200, 204, 400, 401, 403, 404.