docs(chat): reconcile the resume-stream contract with what the route returns
Row 4 of chat#1923. Three drifts between the published contract and the shipped route, all found by live preview testing of api#809.
1. The error schema was wrong for every 4xx
ChatStreamErrorResponse declared { status, message } with message required. The route returns error, plus missing_fields on validation failures:
{"status":"error","missing_fields":["startIndex"],"error":"startIndex must be a non-negative integer"}
{"status":"error","error":"Forbidden"}
Both observed live. The schema is pre-existing and backs 401/403/404 as well as the 400 — so every documented error body on this endpoint was inaccurate, not just the one added recently.
2. account_id was undocumented
The admin override shipped in api#809. Documented with the authorisation rule, because the interesting part is that it is validated, not trusted: an organization key may pass a member account's id, a personal key passing anyone else's gets 403 Access denied to specified account_id. Verified live on both paths.
3. x-workflow-stream-tail-index was undocumented
It ships on the 200. The description states the semantic explicitly, because getting it wrong cost a round of rework downstream:
the last chunk known to the stream at the moment this read was opened… a read that stays open past that point will deliver chunks beyond it — so this is a base for computing absolute positions, not a record of where the response ended.
Concretely: a read advertising tail: 9 went on to deliver 22 chunks. Headers are sent before the body, so no header can ever report where a stream ended. A client resuming precisely must count what it receives on top of this value — which is what chat#1924 ended up doing.
Verification
- File parses; params resolve to
[chatId(path), account_id(query), startIndex(query)]; 200 headers to[x-workflow-run-id, x-workflow-stream-tail-index]; error schema requires[status, error]. 25 insertions, 2 deletions— the 2 deletions are themessagefield being corrected toerror.- Applied via anchored text edits:
research.jsondoes not round-trip throughjson.dumpsbyte-for-byte, so a rewrite would bury the change in a spurious diff.
Local Mintlify render check to follow before merge.
Refs chat#1923
🤖 Generated with Claude Code
Summary by cubic
Aligns the chat resume-stream OpenAPI docs with the actual route and makes the tail-index header visible in the rendered docs. Addresses chat#1923.
- Bug Fixes
- Error schema: require
error, removemessage, add optionalmissing_fieldsfor 400 validation errors (applies to 400/401/403/404). - Query param: document
account_idoverride and auth rules (org keys can pass member IDs; personal keys using another account get 403). - Response: add
x-workflow-stream-tail-indexand name it in the 200 description so it renders; clarify it reflects the tail at read open and clients should offset from this value.
- Error schema: require
Summary by CodeRabbit
- Documentation
- Documented optional cross-account access for chat streams using an account identifier.
- Added documentation for the workflow stream tail index response header.
- Updated chat stream error responses to use
errorand optionally include missing field details.