Skip to content

docs: describe every published REST API operation and its parameters - #31562

Open
nickvigilante wants to merge 48 commits into
mainfrom
vigilante/docs-1439-fill-in-the-rest-api-descriptions-in-codercoders-swagger
Open

nickvigilante wants to merge 48 commits into
mainfrom
vigilante/docs-1439-fill-in-the-rest-api-descriptions-in-codercoders-swagger

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

Adds a @Description to every route the REST API reference publishes, and rewrites the thin or wrong @Param text on those routes.
On main, 21 of 387 published routes have a description, and 384 of 588 parameters have three words or fewer.
With this PR, 382 routes have a description, and 124 parameters are that short, nearly all of them path IDs such as "Workspace ID".
#30125 describes the other 5 routes.

This PR combines the 35 per-area PRs in the table below, so the change can be reviewed in one place.
It changes swaggo annotations in coderd/ and enterprise/coderd/, the API index page text in scripts/apidocgen/postprocess, the @Security check in the swagger test, comments on a few codersdk limit constants, and the files generated from them, so API behavior doesn't change.
Commits 1 to 40 change only description values in swagger.json.
Commits 41 and 42 also fix security, required, format, and missing parameters where they contradict the new text.
Field comments in codersdk are out of scope, because #31531 rewrites them.

Reviewing

There's one commit per area.
Each commit regenerates the API docs and passed the pre-commit hook on its own, so you can review one area at a time, or hand an area's commit to its code owners.
Each original PR lists the code location behind every permission, license, default, and limit claim in its commit, and the annotation bugs found in that area but not fixed here.

# Area Original PR
1 Users #31528
2 Authorization #31529
3 Organizations #31524
4 Members #31534
5 Builds #31538
6 Workspaces #31539
7 Templates #31540
8 Agents #31536
9 OAuth2 provider #31516
10 AI governance #31542
11 Licenses and appearance #31543
12 Template and workspace controls #31520
13 Groups and workspace quotas #31544
14 Workspace proxies, provisioner keys, and replicas #31525
15 IdP sync #31523
16 SCIM #31517
17 Chats #31532
18 Chat configuration #31533
19 General #31537
20 Notifications #31500
21 Secrets #31545
22 AI Gateway #31527
23 AI Providers #31530
24 Debug #31514
25 Git #31546
26 Insights #31547
27 TemplateBuilder #31548
28 PortSharing #31549
29 Applications #31522
30 Files #31550
31 Prebuilds #31551
32 Audit #31552
33 InitScript #31526
34 Provisioning #31519
35 WorkspaceProxies #31535
36 Chat advisor configuration, new on main This PR
37 Wording across areas This PR
38 Review feedback This PR
39 Chat queued message edit, new on main This PR
40 Permissions without role lists This PR
41 Annotation fixes This PR
42 Second review round This PR
43 Third review round This PR
44 Fourth review round This PR
45 Fifth review round This PR
46 Sixth review round This PR
47 Seventh review round This PR

The last 12 commits are new:

  • GET and PUT /api/v2/chats/config/advisor and PATCH /api/v2/chats/{chat}/queue/{queuedMessage} landed on main after the area PRs were written, so commits 36 and 39 describe them.
  • Commit 37 makes the wording consistent across areas, after a consistency review of the combined text. It gives limit, after_id, and the log-streaming parameters one wording per behavior, and puts "Requires a Premium license." on its own line.
  • Commit 38 fixes what the first Coder Agents review flagged. It corrects the build paging and cancel rules and the workspace TTL text, says that deleting an OAuth2 application or secret revokes its tokens, and gives the AI Gateway, file upload, chat cost, and paginated groups routes a verb-first opening.
  • Commit 40 drops the role lists from the permission sentences, so each one names only the permission, and the API index page links the role table once. It also states the other ways to get access where dbauthz has one: anyone who can update a template can read its files, and template insights check each template in template_ids.
  • Commit 41 removes @Security from the 13 routes registered without apiKeyMiddleware, drops format(uuid) from 42 path parameters that also accept a name, default, me, or primary, marks 12 optional query parameters as not required, and declares 15 query parameters the handlers read.
  • Commit 42 fixes what the second Coder Agents review flagged. It corrects two permission sentences that the role lists had hidden, links the role routes and the API key scopes page from the Permissions section, makes the swagger test fail when a route that takes no session token declares @Security, names the status code wherever a sentence said a call fails, and declares two more query parameters.
  • Commit 43 fixes what the third review flagged, such as saying that the role routes leave out the member and organization-member roles, and naming the status code on the last "Fails" sentences.
  • Commit 44 fixes what the fourth review flagged, such as the entitlements refresh limit and the secrets import limits.
  • Commit 45 fixes what the fifth review flagged, such as the chat family rules for archiving and the secret byte totals counting stored bytes.
  • Commit 46 fixes what the sixth review flagged, such as stating the secret limits on the update route and the 10-minute automatic entitlements refresh.
  • Commit 47 makes the note on the entitlements refresh interval name the handler and its doc comment, which states the interval too.

Merge order

  1. fix: list every enum value the API can return in the Swagger spec #30122, fix: document raw JSON as objects and byte fields as base64 strings #30123, fix: correct invalid and nonexistent Swagger parameters #30124, and fix: document WebSocket routes as 101 responses in the Swagger spec #30125 merge first, in that order. They're small, the review app approved them, and they fix places where the spec is wrong.
  2. This PR merges next, after a rebase. fix: list every enum value the API can return in the Swagger spec #30122 and fix: correct invalid and nonexistent Swagger parameters #30124 change annotation lines next to lines this PR changes, in coderd/provisionerdaemons.go, coderd/provisionerjobs.go, coderd/exp_chats.go, and enterprise/coderd/idpsync.go, and every API docs PR regenerates the same files.
  3. docs: describe API fields without opening with the Go field name #31531, which rewrites field comments, merges after this PR. It changes different source files, so its rebase only regenerates files.
  4. test: require @Description on published API routes #31473 merges last. It makes the swagger tests fail on a published route with no @Description, and empties its exemption lists once this PR and fix: document WebSocket routes as 101 responses in the Swagger spec #30125 are in.

If this PR is approved before the others, it can merge first, and the PRs after it rebase instead.

Verification

  • Each commit: make coderd/apidoc/.gen and the pre-commit hook, which runs make pre-commit (gen, fmt, lint, typos, and a slim build). Commits 1 to 40 also passed a check that swagger.json changed only description values, and the other swagger.json changes in commits 41 and 42 are the 13 security, 12 required, 42 format, and 17 parameter changes listed above.
  • On the last commit, the coderd package tests, TestEndpointsDocumented, TestSDKFieldsFormatted, TestEnterpriseEndpointsDocumented, and the scripts/apidocgen/postprocess tests pass, and make lint/emdash passes. The rebase onto main regenerated the API docs after each of commits 1 to 38 and reran the description-only check.
  • No changed description has a raw <, >, {, or } outside backticks, which would break MDX renderers.
  • The change is Go comments, the swagger test's @Security check, the API index page string, and generated files, and CI runs the swagger tests on Linux, macOS, and Windows. The only site/ change is four generated comment lines in typesGenerated.ts.
Plan and decision log

Context

The REST API reference renders one page per endpoint from coderd/apidoc/swagger.json.
Most pages had only a summary, bare parameter names, and fields with no explanation.
DOCS-1439 audited the gaps and planned one PR per API area, starting with the endpoints behind the core CLI workflows.

Decisions

  • One PR, one commit per area: the 35 area PRs are combined at review request, and each keeps its own commit so its evidence in the original PR still lines up.
  • Annotations only: swagger.json, docs.go, and docs/reference/api/ are regenerated, never edited by hand.
  • Claims checked against the code: each permission sentence names the permission from the handler's api.Authorize call or its dbauthz query. The first plan also named the built-in roles that have each permission, but those lists drifted from coderd/rbac/roles.go and left out organization roles, resource ACL roles, and sharing, so commit 40 drops them. "Requires a Premium license." appears only where a feature check gates the route.
  • Shared parameter wording: user reads "User ID, username, or me for the authenticated user." and organization reads "Organization ID, name, or default for the default organization." limit, offset, and after_id use one wording each, and differ only where a handler has its own default.
  • Error codes in descriptions: a description names an error status code in its text, and this PR adds no @Failure lines for those codes, so each page's Responses table lists only the codes the annotations already declared. Adding @Failure lines is a follow-up for all routes at once, so later API docs PRs don't mix the two styles.
  • Writing: one to three sentences per route, in present tense and active voice. The first sentence starts with a verb and stands on its own, because the API landing page shows it on each endpoint's card.
  • Review: each area ran doc-check in author self-check mode on its own PR, with the Fact Checker, Continuity Editor, Copy Editor, and Skeptic personas. The combined text then got a focused Continuity Editor and Skeptic pass for wording across areas, which became commit 37. The Skeptic rejected 13 candidates, such as handler-specific limit defaults.
  • Annotation fixes in scope: where an annotation contradicts the new text, commit 41 fixes it: @Security on routes without a session token, format(uuid) on parameters that accept names, required on optional parameters, and parameters the handlers read but the annotations left out.
  • Out of scope: other annotation bugs, such as success codes or types that don't match the handler and summaries that say "by name" on routes that take an ID. Field comments, DeploymentValues, and the 103 hidden routes are out of scope too.

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

@linear-code

linear-code Bot commented Oct 30, 2026

Copy link
Copy Markdown

DOCS-1439

This was referenced Oct 30, 2026
Fix the annotation bugs from the first Coder Agents review round that
the descriptions now make visible, so swagger.json changes more than
description values in this commit.

- Remove `@Security CoderSessionToken` from the 13 routes registered
  without apiKeyMiddleware, and exempt them in assertSecurityDefined.
- Drop `format(uuid)` from the 42 organization, user, and workspace
  proxy path parameters that also accept a name, `default`, `me`, or
  `primary`.
- Mark 12 optional query parameters as not required.
- Declare 15 query parameters that the handlers read but the
  annotations left out, such as `include_all`, `format`, and the PTY
  parameters.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 2. The new commits fix every round 1 finding, drop the role lists, and correct @Security, required, format(uuid), and missing @Param lines; the panel checked the fixes against the code. Findings: 5 P3, 6 P4, 3 Nit, and no P0 to P2.

The new permission-only sentences expose two places where the role lists hid a wrong permission (profile update, dormant start), and the Permissions section's link does not yet let a reader resolve a permission to a role.

Out of scope (needs a ticket or explicit acceptance by a human):

  • coderd/templateversions.go:1149: GET .../versions/{templateversionname}/previous is published, accepts an organization name or default, and still declares "Organization ID" format(uuid); it is one of the 5 routes left for #30125, so generated clients reject valid values unless #30125 fixes it.
  • docs/admin/users/groups-roles.md:27: the built-in role table has nine coarse rows, so it cannot say which role holds most permissions the API reference names.
  • coderd/templateversions.go:1413: archiving an in-use version returns 500 "Internal error fetching template version.", so the message names the wrong operation and blames the server for a caller condition.
  • enterprise/coderd/organizations.go:244: deleting an organization that still has resources returns 500, though the detail names what the caller must delete first.
  • coderd/workspaces.go:423: the two create-workspace routes keep their older imperative description across four lines, so the most-used routes read differently from the rest of the reference.
  • coderd/workspacebuilds.go:1013: verifyUserCanCancelWorkspaceBuilds checks for the owner role name, so Organization Admin or a custom role cannot cancel a running build even with update on the workspace and template.
  • coderd/coderdtest/swaggerparser.go:365: the exemption list hand-copies which routes skip apiKeyMiddleware, while chi.Walk already passes each route's middleware, so a new public route that keeps @Security goes undetected.
  • enterprise/coderd/templates.go:82: the available-ACL handler pages users with offset and after_id but returns groups from the start, so paging clients receive the same groups on every page.
  • From round 1, still open: coderd/exp_chats.go:4630 (chat diff fetched with the chat owner's git token for any chat reader), enterprise/coderd/groups.go:645 (paginated groups maps the authorization error to 500), enterprise/coderd/scimroutes.go:52 (SCIM 2.0 handler has no annotations), coderd/database/queries/workspacebuilds.sql:48 (after_id cursor direction), coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, and coderd/database/dbauthz/dbauthz.go:8580.

Notes:

  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/users.go Resolved
Comment thread coderd/workspacebuilds.go Resolved
Comment thread scripts/apidocgen/postprocess/main.go Resolved
Comment thread coderd/coderdtest/swaggerparser.go Resolved
Comment thread coderd/coderdtest/swaggerparser.go Resolved
Comment thread coderd/members.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/x/chatd/chatd.go Resolved
Comment thread coderd/parameters.go Resolved
Comment thread coderd/notifications.go Resolved
Fix what the second Coder Agents review round flagged, most of which
the dropped role lists had hidden.

- Correct two permission sentences: updating another user's profile
  needs update on personal user data, and starting a dormant workspace
  needs update on it.
- Point the API index Permissions section at the role routes, which
  list each role's permissions, and at the API key scopes page.
- Make TestEndpointsDocumented fail when a route that takes no session
  token declares @Security.
- Name the status code wherever a sentence said a call fails, give
  every `key:value` search parameter one opening, and declare `offset`
  and `after_id` on the template ACL available route.
- Point the custom notification and user secret limit constants at the
  annotations that copy them.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 3. Commit 42 fixes all 14 round 2 findings, and the panel checked them against the code. Findings: 2 P3, 8 P4, 3 Nit, and no P0 to P2.

The fix to the Permissions section adds its own gap: the role routes it points to omit member and organization-member, so readers following it miss the permissions every user holds.

Out of scope (needs a ticket or explicit acceptance by a human):

  • coderd/roles.go:83: the role list routes never return member or organization-member, so no API call or UI view shows the permissions every user and organization member holds.
  • coderd/coderdtest/swaggerparser.go:190: VerifySwaggerDefinitions walks only /api/v2, so the @Security check never runs on /oauth2/*, /.well-known/*, or /scim/v2/*, including the "Doesn't require a session token" text on /oauth2/tokens, /oauth2/revoke, and /oauth2/register.
  • coderd/usersecrets.go:236: @Failure 413 says "8 MiB", which is 8*codersdk.MaxSecretsFileBytes, so it goes stale when that constant changes.
  • coderd/x/chatd/chatd.go:107: the advisor constant comment says "intentionally generous relative to the advisor's concise guidance remit" for a one-clause reason; this PR changes only line 109.
  • coderd/exp_chats.go:464: the chats list q text opens with "Search query. Supports", unlike the other q text this PR rewrites.
  • coderd/mcp_acl.go:74: the q text on the hidden ACL routes (also exp_chats_model_acl.go:69, organizationskills_acl.go:60) differs from the template ACL q this PR rewrites.
  • Earlier rounds, still open: coderd/exp_chats.go:4630 (chat diff fetched with the owner's git token), enterprise/coderd/groups.go:645, enterprise/coderd/scimroutes.go:52, coderd/database/queries/workspacebuilds.sql:48, coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, coderd/database/dbauthz/dbauthz.go:8580, coderd/templateversions.go:1149, docs/admin/users/groups-roles.md:27, coderd/templateversions.go:1413, enterprise/coderd/organizations.go:244, coderd/workspaces.go:423, coderd/workspacebuilds.go:1013, coderd/coderdtest/swaggerparser.go:365, and enterprise/coderd/templates.go:82.

Notes:

  • coderd/templateversions.go:1321: this route and enterprise/coderd/organizations.go:170 now document 500 for caller-caused conditions; whoever fixes those handlers (listed above) must change these descriptions in the same commit.
  • coderd/exp_chats.go:405: the constant-to-annotation ties are comments only; nothing fails when a constant changes.
  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/users.go Resolved
Comment thread coderd/users.go Resolved
Comment thread coderd/usersecrets.go Resolved
Comment thread scripts/apidocgen/postprocess/main.go Resolved
Comment thread coderd/roles.go Resolved
Comment thread coderd/workspaces.go Resolved
Comment thread coderd/coderdtest/swaggerparser.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread codersdk/usersecretvalidation.go Resolved
Comment thread coderd/workspaces.go Resolved
Fix what the third Coder Agents review round flagged.

- Say that the role routes leave out the member and organization-member
  roles, and that the API key scopes page lists a subset of the
  permissions.
- Correct the login type, `log_level`, and secrets import sentences, and
  add the `search` key to the users `q` text.
- Name the status code on the remaining "Fails" sentences, and write
  status codes without their reason phrases.
- Move the user secret limit notes into the constants' doc comments,
  which make gen copies into typesGenerated.ts.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 4. Commit 43 fixes all 13 round 3 findings, and the panel checked them and the new status codes against the handlers. Findings: 9 P4 and 2 Nit, none above P4.

Out of scope (needs a ticket or explicit acceptance by a human):

  • coderd/workspacebuilds.go:862: the unchanged expect_status text says "412 Precondition Failed", so the cancel page writes status codes two ways.
  • enterprise/coderd/licenses.go:332: the entitlements refresh rate limit returns 400, not 429, so HTTP clients that retry on 429 with Retry-After treat a retryable condition as a permanent error.
  • Earlier rounds, still open: coderd/roles.go:83, coderd/coderdtest/swaggerparser.go:190, coderd/usersecrets.go:236, coderd/x/chatd/chatd.go:107, coderd/exp_chats.go:464, coderd/mcp_acl.go:74, coderd/exp_chats.go:4630, enterprise/coderd/groups.go:645, enterprise/coderd/scimroutes.go:52, coderd/database/queries/workspacebuilds.sql:48, coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, coderd/database/dbauthz/dbauthz.go:8580, coderd/templateversions.go:1149, docs/admin/users/groups-roles.md:27, coderd/templateversions.go:1413, enterprise/coderd/organizations.go:244, coderd/workspaces.go:423, coderd/workspacebuilds.go:1013, coderd/coderdtest/swaggerparser.go:365, and enterprise/coderd/templates.go:82.

Notes:

  • coderd/templateversions.go:1321: this route and enterprise/coderd/organizations.go:170 document 500 for caller-caused conditions; whoever fixes those handlers must change these descriptions in the same commit.
  • coderd/exp_chats.go:405: the constant-to-annotation ties are comments only; nothing fails when a constant changes.
  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

Comment thread scripts/apidocgen/postprocess/main.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread enterprise/coderd/templates.go Resolved
Comment thread coderd/usersecrets.go Resolved
Comment thread codersdk/usersecretvalidation.go Resolved
Comment thread coderd/x/chatd/chatd.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread enterprise/coderd/licenses.go Resolved
Comment thread enterprise/coderd/licenses.go Resolved
Fix what the fourth Coder Agents review round flagged.

- Name the organization-service-account role on the API index page.
- Name the status codes for tool result submission, chat archiving, and
  the entitlements refresh limit, which any refresh starts.
- State the per-user secret limits on the import route, and point
  MaxUserSecretValueBytes and the advisor token default at every
  annotation that states them.
- Write the remaining status codes without reason phrases.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 5. Commit 44 fixes 10 of the 11 round 4 findings and records in the PR description that error codes stay in prose, which closes the @Failure finding. Findings: 6 P4, none above P4. Two of them are errors in this round's fixes: the tool results 403 and the per-value secret sync note.

Out of scope (needs a ticket or explicit acceptance by a human):

  • enterprise/coderd/licenses.go:315: refresh-entitlements declares @Success 201, but the handler writes 200 (:356), so the published Responses table lists the wrong success code.
  • @Failure lines for all routes: the author's reply calls this a follow-up with no ticket, so the Responses tables list only success codes until someone files it.
  • Earlier rounds, still open: coderd/workspacebuilds.go:862, enterprise/coderd/licenses.go:332, coderd/roles.go:83, coderd/coderdtest/swaggerparser.go:190, coderd/usersecrets.go:236, coderd/x/chatd/chatd.go:107, coderd/exp_chats.go:464, coderd/mcp_acl.go:74, coderd/exp_chats.go:4630, enterprise/coderd/groups.go:645, enterprise/coderd/scimroutes.go:52, coderd/database/queries/workspacebuilds.sql:48, coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, coderd/database/dbauthz/dbauthz.go:8580, coderd/templateversions.go:1149, docs/admin/users/groups-roles.md:27, coderd/templateversions.go:1413, enterprise/coderd/organizations.go:244, coderd/workspaces.go:423, coderd/workspacebuilds.go:1013, coderd/coderdtest/swaggerparser.go:365, and enterprise/coderd/templates.go:82.

Notes:

  • coderd/exp_chats.go:2715: the documented archive 409 arrives after patchChat has saved the title and labels from the same request; that handler order is the coderd/exp_chats.go:2934 item above, and this text must change when it is fixed.
  • coderd/templateversions.go:1321: this route and enterprise/coderd/organizations.go:170 document 500 for caller-caused conditions; whoever fixes those handlers must change these descriptions in the same commit.
  • coderd/exp_chats.go:405: the constant-to-annotation ties are comments only; nothing fails when a constant changes.
  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/exp_chats.go Resolved
Comment thread codersdk/usersecretvalidation.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/usersecrets.go Resolved
Comment thread coderd/usersecrets.go Resolved
Comment thread enterprise/coderd/licenses.go Resolved
Fix what the fifth Coder Agents review round flagged.

- Separate the 404 and 403 cases for tool result submission.
- Say that archive state changes work only on a root chat and apply to
  the whole chat family, which must be idle or in an error state.
- Say that the per-user secret byte totals count stored bytes, and that
  the env secret limit is a total.
- Point MaxUserSecretValueBytes at every annotation that states it.
- Name the changes the entitlements refresh route applies, since adding
  or deleting a license already refreshes them.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 6. Commit 45 fixes all 6 round 5 findings, and the panel verified each against the handlers. Findings: 3 P4 and 3 Nit, none above P4. The main gap is that the update secret route doesn't state the limits that create and import now document.

Out of scope (needs a ticket or explicit acceptance by a human): unchanged from round 5. The items are enterprise/coderd/licenses.go:315, @Failure lines for all routes, coderd/workspacebuilds.go:862, enterprise/coderd/licenses.go:332, coderd/roles.go:83, coderd/coderdtest/swaggerparser.go:190, coderd/usersecrets.go:236, coderd/x/chatd/chatd.go:107, coderd/exp_chats.go:464, coderd/mcp_acl.go:74, coderd/exp_chats.go:4630, enterprise/coderd/groups.go:645, enterprise/coderd/scimroutes.go:52, coderd/database/queries/workspacebuilds.sql:48, coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, coderd/database/dbauthz/dbauthz.go:8580, coderd/templateversions.go:1149, docs/admin/users/groups-roles.md:27, coderd/templateversions.go:1413, enterprise/coderd/organizations.go:244, coderd/workspaces.go:423, coderd/workspacebuilds.go:1013, coderd/coderdtest/swaggerparser.go:365, and enterprise/coderd/templates.go:82.

Notes:

  • coderd/exp_chats.go:2715: the documented archive 409 arrives after patchChat has saved the title and labels; this text must change when the coderd/exp_chats.go:2934 handler order is fixed.
  • coderd/templateversions.go:1321: this route and enterprise/coderd/organizations.go:170 document 500 for caller-caused conditions; whoever fixes those handlers must change these descriptions in the same commit.
  • coderd/exp_chats.go:405: the constant-to-annotation ties are comments only; nothing fails when a constant changes.
  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/usersecrets.go Resolved
Comment thread coderd/usersecrets.go Resolved
Comment thread enterprise/coderd/licenses.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread codersdk/usersecretvalidation.go Resolved
Comment thread coderd/usersecrets.go Resolved

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new commits since the round 6 review (head is still a21d2b9256), and none of the six round 6 threads has a reply, so this round runs no reviewers. Further review is blocked until the author pushes fixes or replies on each thread.

Open findings:

  • coderd/usersecrets.go:428 (P4): the update secret description states none of the per-user limits, though the route returns 400 when a change exceeds them.
  • coderd/usersecrets.go:142 (P4): "larger than the values you send" doesn't say the overhead is about a third or name --external-token-encryption-keys.
  • coderd/exp_chats.go:2717 (P4): "The change also applies to the root chat's sub-agent chats" can be read as covering all eight updatable fields, not only the archive state.
  • enterprise/coderd/licenses.go:309 (Nit): the text doesn't say the automatic refresh runs every 10 minutes.
  • codersdk/usersecretvalidation.go:101 (Nit): "states" where the sibling note at line 64 says "state".
  • coderd/usersecrets.go:226 (Nit): create and import word the same two limits differently.

For each, push a fix, or reply on the thread with why it should not change.

🤖 This review was automatically generated with Coder Agents.

Fix what the sixth Coder Agents review round flagged.

- State the per-user secret limits and the per-value cap on the update
  secret route, which returns 400 when a change exceeds them.
- Use one wording for the limits on the create, import, and update
  routes, and name the encryption setting that makes stored values
  about a third larger.
- Say that only the archive state reaches a root chat's sub-agent chats.
- State the 10-minute automatic entitlements refresh, and tie its
  default to the description.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 8. Commit 46 fixes all 6 round 6 findings, and the panel verified each against the code. Findings: 1 Nit.

Out of scope (needs a ticket or explicit acceptance by a human):

  • enterprise/coderd/licenses.go:303: the unchanged doc comment on postRefreshEntitlements also states the 10-minute interval, and the new sync note doesn't name it, so changing the default leaves that comment stale.
  • Unchanged from earlier rounds: enterprise/coderd/licenses.go:315, @Failure lines for all routes, coderd/workspacebuilds.go:862, enterprise/coderd/licenses.go:332, coderd/roles.go:83, coderd/coderdtest/swaggerparser.go:190, coderd/usersecrets.go:236, coderd/x/chatd/chatd.go:107, coderd/exp_chats.go:464, coderd/mcp_acl.go:74, coderd/exp_chats.go:4630, enterprise/coderd/groups.go:645, enterprise/coderd/scimroutes.go:52, coderd/database/queries/workspacebuilds.sql:48, coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, coderd/database/dbauthz/dbauthz.go:8580, coderd/templateversions.go:1149, docs/admin/users/groups-roles.md:27, coderd/templateversions.go:1413, enterprise/coderd/organizations.go:244, coderd/workspaces.go:423, coderd/workspacebuilds.go:1013, coderd/coderdtest/swaggerparser.go:365, and enterprise/coderd/templates.go:82.

Notes:

  • coderd/usersecrets.go:429: the update route's limit sentence lists the 50-secret count, which a PATCH can't exceed because the trigger excludes the row being updated; the sentence still holds as a statement of the limits and matches create and import.
  • coderd/exp_chats.go:2715: the documented archive 409 arrives after patchChat has saved the title and labels; this text must change when the coderd/exp_chats.go:2934 handler order is fixed.
  • coderd/templateversions.go:1321: this route and enterprise/coderd/organizations.go:170 document 500 for caller-caused conditions; whoever fixes those handlers must change these descriptions in the same commit.
  • coderd/exp_chats.go:405: the constant-to-annotation ties are comments only; nothing fails when a constant changes.
  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

Comment thread enterprise/coderd/coderd.go Resolved
The note on the default entitlements update interval now names
postRefreshEntitlements, and its doc comment, which also states the
interval, so a search finds both.

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 9. Commit 18c3b998df fixes the one round 8 finding, and the new sync comment also names the postRefreshEntitlements doc comment, which closes that out-of-scope item. No in-scope finding is open.

Out of scope (needs a ticket or explicit acceptance by a human), unchanged from earlier rounds: enterprise/coderd/licenses.go:315, @Failure lines for all routes, coderd/workspacebuilds.go:862, enterprise/coderd/licenses.go:332, coderd/roles.go:83, coderd/coderdtest/swaggerparser.go:190, coderd/usersecrets.go:236, coderd/x/chatd/chatd.go:107, coderd/exp_chats.go:464, coderd/mcp_acl.go:74, coderd/exp_chats.go:4630, enterprise/coderd/groups.go:645, enterprise/coderd/scimroutes.go:52, coderd/database/queries/workspacebuilds.sql:48, coderd/exp_chats.go:2934, coderd/debug.go:236, enterprise/coderd/groups.go:97, enterprise/coderd/groups.go:595, enterprise/coderd/aibridge.go:1132, codersdk/deployment.go:4527, coderd/database/dbauthz/dbauthz.go:8580, coderd/templateversions.go:1149, docs/admin/users/groups-roles.md:27, coderd/templateversions.go:1413, enterprise/coderd/organizations.go:244, coderd/workspaces.go:423, coderd/workspacebuilds.go:1013, coderd/coderdtest/swaggerparser.go:365, and enterprise/coderd/templates.go:82.

Notes:

  • coderd/usersecrets.go:429: the update route's limit sentence lists the 50-secret count, which a PATCH can't exceed; the sentence still holds as a statement of the limits.
  • coderd/exp_chats.go:2715: the documented archive 409 arrives after patchChat has saved the title and labels; this text must change when the coderd/exp_chats.go:2934 handler order is fixed.
  • coderd/templateversions.go:1321: this route and enterprise/coderd/organizations.go:170 document 500 for caller-caused conditions; whoever fixes those handlers must change these descriptions in the same commit.
  • coderd/exp_chats.go:405: the constant-to-annotation ties are comments only; nothing fails when a constant changes.
  • coderd/exp_chats.go:466: until #31473 merges, no test fails when a published route has no @Description.

🤖 This review was automatically generated with Coder Agents.

@nickvigilante
nickvigilante marked this pull request as ready for review November 2, 2026 15:01
@coder
coder Bot requested review from Emyrk, hwang251 and ibetitsmike November 2, 2026 19:23
@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


1 out of 2 committers have signed the CLA.
✅ (nickvigilante)[https://github.com/nickvigilante]
❌ @coder[bot]
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

This branch had an error being deployed

1 failed deployment
main — 7a529397 Deployed Nov 16, 2026 by coder[bot] via cla #257911
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant