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

[sweetmantech]

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-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.

^{Written for commit 6fed74c. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ebf29ee6-46f8-4497-9c44-d06041f3d9d1

📥 Commits

Reviewing files that changed from the base of the PR and between d673296 and 6fed74c.

📒 Files selected for processing (1)

• api-reference/openapi/research.json

---

📝 Walkthrough

Walkthrough

The OpenAPI specification adds an optional startIndex parameter to the chat stream resume endpoint and documents a 400 response for invalid values.

Changes

Chat stream resume

Layer / File(s)	Summary
Indexed stream resume contract api-reference/openapi/research.json	The GET /api/chat/{chatId}/stream endpoint accepts a zero-based, non-negative integer startIndex and documents a 400 response using ChatStreamErrorResponse.

Estimated code review effort: 2 (Simple) | ~5 minutes

Suggested reviewers: arpitgupta1214

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and the affected chat stream endpoint.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/chat-stream-start-index

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}

[sweetmantech]

Verified locally against a Mintlify dev server

npx mintlify@latest dev --port 3111 on this branch (6fed74c), driven through Chrome DevTools. The page builds and renders the new contract.

startIndex renders under Query Parameters

A Query Parameters section now appears — it did not exist before, since chatId was the only parameter — with startIndex typed integer and the full description.

The inline POST /api/chat/runs reference inside the description renders as a code span, and the paragraph breaks survive the \n\n escaping in the JSON.

400 renders with the shared error schema

The response tabs are now 200 / 400 / 401 / 403 / 404, and selecting 400 shows the ChatStreamErrorResponse body — the $ref resolves rather than rendering an empty schema.

Spec diff, before vs after

Parsed from api-reference/openapi/research.json on each side:

	origin/main	this PR
params	['chatId']	['chatId', 'startIndex']
responses	['200','204','401','403','404']	['200','204','400','401','403','404']

Results

Check	Result
Page builds and serves	✅ HTTP 200 at /api-reference/chat/workflow-stream
Title from existing frontmatter	✅ "Resume Chat Stream"
Query Parameters section appears	✅ new section, startIndex integer
Description prose + inline code	✅ renders, paragraphs preserved
Response tabs	✅ 200 / 400 / 401 / 403 / 404
400 body schema	✅ ChatStreamErrorResponse $ref resolves
Sidebar entry	✅ already present under Streaming → "Resume Chat Stream"
Diff shape	✅ 20 insertions, 0 deletions
JSON validity	✅ parses; params and responses resolve as above

Two notes on what is not shown

204 has no response tab. Mintlify only tabs responses that carry content, and a 204 No Content has none by definition. It is present in the spec (see the table above) and unchanged by this PR — the absence of a tab is correct rendering, not a dropped response.

llms.txt was not verified. The local dev server returns the SPA shell for /llms.txt rather than generated text; it is produced at deploy time. The nav entry it derives from (api-reference/chat/workflow-stream in docs.json, line 66) already exists and is unchanged, so no nav work was needed here — but I did not observe the generated output and am not claiming it.