docs(chat): reconcile the resume-stream contract with what the route returns

Merged
SW
4mo ago
+26-3

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 the message field being corrected to error.
  • Applied via anchored text edits: research.json does not round-trip through json.dumps byte-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, remove message, add optional missing_fields for 400 validation errors (applies to 400/401/403/404).
    • Query param: document account_id override and auth rules (org keys can pass member IDs; personal keys using another account get 403).
    • Response: add x-workflow-stream-tail-index and name it in the 200 description so it renders; clarify it reflects the tail at read open and clients should offset from this value.

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 error and optionally include missing field details.