Skip to content

docs: describe the General API operations and parameters - #31537

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes 11 General API routes and improves the request body of POST /api/v2/csp/reports and the user path parameter of the token config route, so the REST API reference page for each route has more than a title.
The reference renders from swagger.json, and these routes 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=11 problems=0 thin_params_left=0
$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
$ make lint/emdash
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.464s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.403s
OK: no emdash or endash characters found.

A JSON diff of swagger.json against origin/main changes only description values: 13 in total, all on routes in this PR or their parameters, and no other value differs.

doc-check self-check

Ran the doc-check skill in author self-check mode on the branch diff, one persona at a time: Fact Checker, Continuity Editor, Copy Editor, then Skeptic on what survived. The other personas (Cartographer, Newcomer, Reader Advocate, Architect) didn't run.

  • Fact Checker, Continuity Editor, and Copy Editor returned no blocking findings.
  • Skeptic rejected 2: a non-breaking space in 64 KiB (the rule skips the API reference), and sentences over 25 words (targets, not ceilings).
Claims checked against the code
Route Claim Evidence
GET /api/v2/, GET /api/v2/buildinfo, GET /api/v2/updatecheck Don't require a session token coderd/coderd.go:1471, :1477, :1507 (registered outside any auth middleware), coderd/coderdtest/swaggerparser.go:365-367 (assertSecurityDefined exempts them)
POST /api/v2/csp/reports Doesn't require a session token coderd/coderd.go:1473 (no auth middleware)
POST /api/v2/csp/reports Body can't exceed 64 KiB, and the report is logged at debug level coderd/csp.go:18, :41, :65
GET /api/v2/deployment/config Requires permission to read the deployment configuration, which the Owner and Auditor roles have coderd/deployment.go:23, coderd/rbac/roles.go:495 (Auditor), Owner has all permissions except a list that excludes neither resource (coderd/rbac/roles.go:422)
GET /api/v2/deployment/config Returns values without secrets and options, whose entries describe each setting coderd/deployment.go:28, :38
GET /api/v2/deployment/stats Requires permission to read deployment stats, which the Owner and Auditor roles have, and returns 400 while stats are still processing coderd/deployment.go:53, :61, coderd/rbac/roles.go:494
GET /api/v2/deployment/ssh Any authenticated user can call it coderd/coderd.go:1486-1487 (apiKeyMiddleware), coderd/deployment.go:94 (no Authorize call)
GET /api/v2/deployment/user-secrets/capabilities Any authenticated user can call it, and file_path_delivery_enabled reflects the deployment's user secret file path setting coderd/usersecrets.go:131-135, :53
GET /api/v2/experiments Returns the experiments enabled for you, and user-scoped rules can differ per user coderd/experiments.go:37, coderd/experiments/evaluator.go:61-84
GET /api/v2/experiments/available Returns the safe experiments in safe coderd/experiments.go:50-52
GET /api/v2/updatecheck Reports the running version as current when update checking is off or hasn't succeeded coderd/updatecheck.go:33-46
GET /api/v2/users/{user}/keys/tokens/tokenconfig Users with the Owner role get the maximum admin token lifetime, everyone else the maximum token lifetime coderd/apikey.go:575-583
GET /api/v2/users/{user}/keys/tokens/tokenconfig user accepts an ID, username, or me coderd/coderd.go:1758 (ExtractUserParam)
Writing rules applied
  • One to three sentences per route, present tense, first sentence starts with a verb and stands alone on the endpoint card.
  • Permissions name the built-in roles, traced through api.Authorize calls, middleware, and coderd/rbac/roles.go.
  • Routes without a session token say so, and routes with another credential name it.
  • Streams say that the route upgrades to a WebSocket or sends server-sent events, and what each message carries.
  • Full API paths and literals (fields, parameters, values) are in backticks.
  • Shared parameter wording is copied exactly only where the code matches it.
  • No em dashes, en dashes, semicolons, or raw angle brackets and braces outside backticks.
Annotation bugs noticed, not changed here
  • POST /api/v2/csp/reports lists @Security CoderSessionToken, but the route has no auth middleware.
  • GET /api/v2/experiments/available documents an array of codersdk.Experiment, but the handler returns a codersdk.AvailableExperiments object with a safe array.

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. This adds one to each General route and improves the
parameter descriptions.

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