Skip to content

docs: describe the chat configuration API operations and parameters - #31533

Closed
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-chat-configuration
Closed

nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-chat-configuration

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes the 22 chat configuration routes under /api/v2/chats/config and the organization chat routes (system prompt and models), and improves the 15 parameters on them.
The REST API reference renders these routes from swagger.json, and they had no description.

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.

Verification

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

The swagger.json diff against origin/main changes only description values on the 22 operations in scope: 22 descriptions added and 15 parameter descriptions rewritten.
The route list regenerated from 5c691c82c9 is identical to the shared one.

Claims checked against the code
Route Claim Evidence
GET, PUT /api/v2/chats/config/system-prompt Owner only: both read and write need update on deployment configuration coderd/exp_chats.go:5172, coderd/exp_chats.go:5226, coderd/rbac/roles.go:414 (Owner gets all site permissions except the listed ones)
GET, PUT /api/v2/chats/config/plan-mode-instructions Owner only: both need update on deployment configuration coderd/exp_chats.go:5449, coderd/exp_chats.go:5498, coderd/database/dbauthz/dbauthz.go:3809
GET /api/v2/chats/config/personal-model-overrides, GET /api/v2/chats/config/debug-logging Owner and Auditor can read: read on deployment configuration coderd/exp_chats.go:5766, coderd/exp_chats.go:6188, coderd/rbac/roles.go:479, coderd/rbac/roles.go:495
PUT /api/v2/chats/config/personal-model-overrides, debug-logging, debug-retention-days, auto-archive-days, workspace-ttl Owner only: update on deployment configuration coderd/exp_chats.go:5900 (putChatOperationalSetting)
GET /api/v2/chats/config/auto-archive-days, debug-retention-days, workspace-ttl Any authenticated user can read coderd/database/dbauthz/dbauthz.go:3352, coderd/database/dbauthz/dbauthz.go:3385, coderd/database/dbauthz/dbauthz.go:3999
/api/v2/chats/config/auto-archive-days Default 0 disables auto-archive, maximum 3650 days, the unit is days of chat inactivity codersdk/chats.go:1567, coderd/exp_chats.go:6617, coderd/x/chatd/auto_archive.go:68
/api/v2/chats/config/debug-retention-days Default 30, 0 disables the cleanup, maximum 3650 days codersdk/chats.go:1572, coderd/exp_chats.go:6558, coderd/database/dbpurge/dbpurge.go:328
/api/v2/chats/config/workspace-ttl Default 0 means off and the template's autostop applies, accepted range is 0 or 1 minute to 30 days, the value goes on workspaces that chats create codersdk/chats.go:1578, coderd/exp_chats.go:6463, coderd/exp_chats.go:6469, coderd/x/chatd/chattool/createworkspace.go:193
PUT /api/v2/chats/config/debug-logging The setting only gates user opt-in, and users can't change their own setting while --chat-debug-logging-enabled forces logging on coderd/exp_chats.go:6289, coderd/exp_chats.go:6203 (ForcedByDeployment)
PUT /api/v2/chats/config/user-debug-logging 403 unless an administrator enabled user opt-in, 409 while the deployment forces logging on coderd/exp_chats.go:6289, coderd/exp_chats.go:6304
GET, PUT /api/v2/chats/config/user-prompt Applies to the caller's own chats coderd/exp_chats.go:6655, coderd/exp_chats.go:6690, coderd/database/dbauthz/dbauthz.go:5595, coderd/database/dbauthz/dbauthz.go:8851, coderd/x/chatd/chatd.go:2072
PUT system prompt, plan mode instructions, user-prompt, organization system prompt CODER_CHAT_MAX_PROMPT_BYTES limits their size codersdk/deployment.go:4526, coderd/exp_chats.go:7903
/api/v2/chats/config/system-prompt The response carries the built-in default prompt, and include_default_system_prompt decides whether it is included, and omitting it keeps the current value coderd/exp_chats.go:5271, coderd/exp_chats.go:5286, coderd/x/chatd/chatd.go:2030
GET, PUT /api/v2/organizations/{organization}/chats/config/system-prompt The organization instructions follow the deployment prompt in the organization's chats coderd/x/chatd/chatd.go:2057
GET /api/v2/organizations/{organization}/chats/config/system-prompt Read on the organization's chat model configuration, which Owner, Auditor, Organization Admin, and Organization Auditor roles have coderd/exp_chats.go:5333, coderd/database/dbauthz/dbauthz.go:3790, coderd/rbac/roles.go:496, coderd/rbac/roles.go:601, coderd/rbac/roles.go:634
PUT /api/v2/organizations/{organization}/chats/config/system-prompt Update on the organization's chat model configuration, which Owner and Organization Admin roles have coderd/exp_chats.go:5378, coderd/database/dbauthz/dbauthz.go:9611, coderd/rbac/roles.go:601
GET /api/v2/organizations/{organization}/chats/models A scoped API token needs coder:all or chat_model_config:read coderd/exp_chats.go:8330
GET /api/v2/organizations/{organization}/chats/models Returns only the models you can read coderd/database/dbauthz/dbauthz.go:3731
GET /api/v2/organizations/{organization}/chats/models Provider descriptors exclude key material and report per-user availability coderd/exp_chats.go:8256 (chatModelProviderDescriptors, availability)
POST /api/v2/organizations/{organization}/chats/models Create on the organization's chat model configuration, which Owner and Organization Admin roles have coderd/database/dbauthz/dbauthz.go:6557, coderd/rbac/roles.go:601
POST /api/v2/organizations/{organization}/chats/models The first model becomes the default, ai_provider_id, model, and a positive context_limit are required, the provider must exist and be enabled coderd/exp_chats.go:8657, coderd/exp_chats.go:8690, codersdk/chats.go:1963
{organization} routes Path accepts ID, name, or default coderd/httpmw/organizationparam.go (ExtractOrganizationParam), coderd/coderd.go:1569
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, and limit claim in the claims table against the code, including the role lists in coderd/rbac/roles.go. No findings.
  • 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. The organization path wording matches the shared text the other branches use, and no route here uses user, limit, offset, or after_id. "Coder Agents" names the product and "chat" names the object throughout. No findings.
  • 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 1 minute. 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.
Writing rules applied
  • One to three sentences per route, present tense and active voice, first sentence starts with a verb.
  • Permission sentences name the required permission and the built-in roles, each traced to an Authorize call or dbauthz method and coderd/rbac/roles.go.
  • No Premium or experiment claims: none of these routes sits behind RequireFeatureMW or an experiment.
  • Settings say what the value controls, its default, and its limits from the handler and SDK constants.
  • Shared parameter wording for {organization} copied from the brief where the route uses ExtractOrganizationParam.
  • Body parameters say what the body holds instead of "Request body".
  • Exact field names, options, 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.
CI flakes unrelated to this change

test-go-pg (windows-2022) failed TestAPISessionRecoveryWriteDeadline/message in agent/x/agentacp, a package this PR doesn't touch: https://github.com/coder/coder/actions/runs/40926600877/job/123633878773

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

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the chat configuration 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