Skip to content

docs: describe the Chats API operations and parameters - #31532

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-chats
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-chats

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes the 21 published Chats routes for chats, messages, queued messages, files, and per-user AI provider keys, and improves the parameters on them.
The REST API reference renders these routes from swagger.json, and they had no description.
It leaves the annotation blocks of the routes that #30125 documents (/api/v2/chats/watch, /stream, /stream/git) and the frozen Content-Disposition header on POST /api/v2/chats/{chat}/workspace-files alone.

Merge notes

This PR doesn't touch #31473's exemption lists.
If #31473 merges first, TestEndpointsDocumented names each route on this PR to remove from those lists.

Existing text fixed on routes in scope:

  • GET /api/v2/chats limit said Page limit and after_id said After ID. The handler defaults limit to 50 and after_id is a chat ID.
  • GET /api/v2/chats/{chat}/messages and GET /api/v2/chats/{chat}/attachments described cursors with a raw < or >, which breaks the Markdown and MDX renderers. They now say "lower ID" and "higher ID".
  • user on the AI provider key routes is now the shared User ID, username, or me wording.

Verification

$ python3 check_routes.py <route list>
summary: need=21 problems=0 thin_params_left=21
$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.395s
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.380s

The swagger.json diff against origin/main changes only description values: 21 descriptions added and 23 parameter descriptions rewritten on 22 operations.
The route list regenerated from 5c691c82c9 is identical to the shared one.
The remaining THIN lines are all UUID-only path IDs (chat, file, aiProvider), which the brief treats as complete.

Claims checked against the code
Route Claim Evidence
GET /api/v2/chats Returns pinned chats first, then by most recent update coderd/database/queries/chats.sql:627 (GetChats, ORDER BY pin order then updated_at)
GET /api/v2/chats limit defaults to 50, and offset and after_id are the pagination cursors coderd/database/queries/chats.sql:860, coderd/exp_chats.go:475
GET /api/v2/chats Default filter is non-archived chats the caller owns, source:shared_with_me includes shared chats coderd/searchquery/search.go:581
GET /api/v2/chats Each result is a root chat with subagent chats in children coderd/database/queries/chats.sql (parent_chat_id IS NULL in GetChats), coderd/exp_chats.go:471
GET /api/v2/chats Returns only chats you can read coderd/database/dbauthz/dbauthz.go:4009
GET /api/v2/chats/by-workspace Returns the latest non-archived chat per workspace, at most 25 workspace IDs, empty value returns an empty object coderd/exp_chats.go:408, coderd/database/queries/chats.sql:2465, coderd/exp_chats.go:428
GET /api/v2/chats/by-workspace Leaves out workspaces with no readable chat coderd/database/dbauthz/dbauthz.go:4028 (post-filter)
POST /api/v2/chats organization_id is required coderd/exp_chats.go:1348
POST /api/v2/chats owner_id for another user needs permission to create API keys for that user, which the Owner role has coderd/exp_chats.go:1395, coderd/rbac/roles.go:414, codersdk/chats.go:888
POST /api/v2/chats, POST /api/v2/chats/{chat}/messages inline_mcp_servers needs the chat-inline-mcp-servers experiment coderd/exp_chats.go:1519, coderd/exp_chats.go:3260, codersdk/deployment.go:5515
POST /api/v2/chats/files Maximum size 10 MiB codersdk/chats.go:57, coderd/exp_chats.go:6964
POST /api/v2/chats/files organization is required, and the caller needs permission to create chats in it coderd/exp_chats.go:6923, coderd/exp_chats.go:6937
POST /api/v2/chats/files A file name in Content-Disposition is required coderd/exp_chats.go:6990
GET /api/v2/chats/files/{file} Readable when you uploaded it or you can read a chat it is attached to coderd/database/dbauthz/dbauthz.go:3500
GET /api/v2/chats/{chat} Embeds subagent chats for a root chat, and returns pinned context resources that the list leaves out coderd/exp_chats.go:1926, coderd/exp_chats.go:1886, codersdk/chats.go:337
PATCH /api/v2/chats/{chat} Only the owner can change read and workspace_id coderd/exp_chats.go:2789, coderd/exp_chats.go:2798
PATCH /api/v2/chats/{chat} Archiving needs an idle or error chat, otherwise a conflict coderd/exp_chats.go:2951, coderd/exp_chats.go:2956
PUT /api/v2/chats/{chat}/context Re-pins the chat to the agent's latest context snapshot and clears the dirty marker coderd/x/chatd/context_hydration.go:254, codersdk/chats.go:337
GET /api/v2/chats/{chat}/diff origin and branch are set together or both omitted coderd/exp_chats.go:4257
GET /api/v2/chats/{chat}/diff diff is empty without a matching git provider or an owner token coderd/exp_chats.go:4631
POST /api/v2/chats/{chat}/interrupt Active runs move to interrupting, requires-action chats get their tool calls canceled, idle chats return 409 coderd/x/chatd/chat_mutations.go:713, coderd/exp_chats.go:3968
GET /api/v2/chats/{chat}/messages Newest first, limit 1 to 200 with default 50, after_id alone polls oldest first, queued messages only without a cursor coderd/exp_chats.go:1987, coderd/exp_chats.go:2006, coderd/exp_chats.go:2059
POST /api/v2/chats/{chat}/messages Only the chat owner can send, and busy_behavior defaults to queue with interrupt as the alternative coderd/exp_chats.go:3210, coderd/exp_chats.go:3285, codersdk/chats.go:998
PATCH /api/v2/chats/{chat}/messages/{message} Owner only, user messages only, later messages are discarded coderd/exp_chats.go:3453, coderd/exp_chats.go:3546, coderd/x/chatd/chat_mutations.go:276
DELETE /api/v2/chats/{chat}/queue/{queuedMessage} Removes a queued message coderd/exp_chats.go:3621
POST /api/v2/chats/{chat}/queue/{queuedMessage}/promote Owner only, interrupts a running chat first, 202 response coderd/exp_chats.go:3677, coderd/exp_chats.go:3738, coderd/x/chatd/chat_mutations.go:558
POST /api/v2/chats/{chat}/reconcile-invalid Moves an invalid-state chat to an error state, keeps queued messages, cancels pending tool calls, 409 when the chat is not invalid coderd/x/chatd/chat_mutations.go:880, coderd/exp_chats.go:4155
POST /api/v2/chats/{chat}/title/propose Owner only, does not save the title coderd/exp_chats.go:4197, coderd/x/chatd/chatd.go:1055
POST /api/v2/chats/{chat}/tool-results Owner only, rejected when caller-supplied tools are disabled, 409 when the chat is not waiting coderd/exp_chats.go:9377, coderd/exp_chats.go:9393, coderd/exp_chats.go:9440
GET /api/v2/users/{user}/ai-provider-keys Reading another user's configuration needs read on that user's personal data, which the Owner and User Admin roles have coderd/database/dbauthz/dbauthz.go:5507, coderd/rbac/roles.go:414, coderd/rbac/roles.go:541
PUT /api/v2/users/{user}/ai-provider-keys/{aiProvider} 403 when --ai-gateway-allow-byok is off, fails when the provider is disabled, API key can't be empty or padded coderd/exp_chats.go:8087, coderd/exp_chats.go:8109, coderd/exp_chats.go:8128, codersdk/deployment.go:2118
PUT, DELETE /api/v2/users/{user}/ai-provider-keys/{aiProvider} Changing another user's key needs update on that user's personal data, which the Owner and User Admin roles have coderd/database/dbauthz/dbauthz.go:9852, coderd/database/dbauthz/dbauthz.go:2786, coderd/rbac/roles.go:541
{user} routes Path accepts ID, username, or me coderd/coderd.go:1758 (ExtractUserParam)
doc-check self-check

Mode: author self-check on the branch diff.
Nothing was posted to GitHub.
The deterministic checks passed: make lint/emdash, check_routes.py with problems=0, and the swagger tests.

  • Fact Checker: checked every permission, default, limit, and status-code claim in the claims table against the code. Two sentences were fixed: the interrupt description now matches InterruptChat, and the message-edit sentence now says deleted_message_ids holds IDs. The chat diff sentence now lists every case where diff is empty.
  • Copy Editor: replaced "disable" with "turn off", "may" with "can", and "with" meaning "has", per word-choice.md.
  • Continuity Editor: compared the shared parameters with the other tag branches using shared_params.py. user matches on every branch. offset, after_id, and limit on GET /api/v2/chats used chat-specific wording, so they now use the shared wording with the handler's default of 50. sub-agent replaces "subagent" to match the glossary entry "Sub-agent (Coder Agents)". "Coder Agents" names the product and "chat" names the object throughout.
  • Cartographer, Newcomer, Reader Advocate, Architect: no findings. No docs pages changed, so the Newcomer, Reader Advocate, and Architect lenses had nothing to read beyond the annotations.
  • Skeptic: rejected 2 candidate findings. One asked for a non-breaking space between a number and its unit, as in 10 MiB. The rule covers Markdown source under docs/, and &nbsp; in an annotation would render as literal text in swagger.json. The other was a style preference with no rule behind it (the "toggle" wording in the user debug logging description), which never blocks.
  • Left unchanged: line 2088 in exp_chats.go (the cost description) still says "subagent". That text predates this PR and is outside the routes in scope.
Writing rules applied
  • One to three sentences per route, present tense and active voice, first sentence starts with a verb.
  • "Coder Agents" names the product and "chat" names the object, per word-choice.md and the glossary.
  • Permission sentences name the built-in roles and trace to an Authorize call, a dbauthz method, and coderd/rbac/roles.go.
  • Owner-only behavior says "Only the chat owner can", because the handlers check chat.OwnerID in addition to RBAC.
  • Experiments are named in backticks (chat-inline-mcp-servers).
  • No Premium claims: none of these routes sits behind RequireFeatureMW.
  • Body parameters say what the body holds instead of "Request body".
  • Exact field names, status codes, and flags in backticks, and full API paths.
  • No em dashes, en dashes, semicolons in prose, or raw angle brackets and braces outside backticks.
  • Avoided "with" as a stand-in for "has", per word-choice.md.

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

The REST API reference renders these routes from swagger.json, and they
had no description.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

Use the shared pagination wording on GET /api/v2/chats, say "sub-agent" as
the glossary does, and state every case in which the chat diff is empty.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Chats API operations and parameters. The claims table above still covers that commit.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant