Repository navigation
docs: describe every published REST API operation and its parameters - #31562
nickvigilante wants to merge 48 commits into
Conversation
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
|
/coder-agents-review |
There was a problem hiding this comment.
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}/previousis published, accepts an organization name ordefault, 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 returns500"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 returns500, 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:verifyUserCanCancelWorkspaceBuildschecks for theownerrole 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 skipapiKeyMiddleware, whilechi.Walkalready passes each route's middleware, so a new public route that keeps@Securitygoes undetected.enterprise/coderd/templates.go:82: the available-ACL handler pages users withoffsetandafter_idbut 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 to500),enterprise/coderd/scimroutes.go:52(SCIM 2.0 handler has no annotations),coderd/database/queries/workspacebuilds.sql:48(after_idcursor 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, andcoderd/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.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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 returnmemberororganization-member, so no API call or UI view shows the permissions every user and organization member holds.coderd/coderdtest/swaggerparser.go:190:VerifySwaggerDefinitionswalks only/api/v2, so the@Securitycheck 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 413says "8 MiB", which is8*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 listqtext opens with "Search query. Supports", unlike the otherqtext this PR rewrites.coderd/mcp_acl.go:74: theqtext on the hidden ACL routes (alsoexp_chats_model_acl.go:69,organizationskills_acl.go:60) differs from the template ACLqthis 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, andenterprise/coderd/templates.go:82.
Notes:
coderd/templateversions.go:1321: this route andenterprise/coderd/organizations.go:170now document500for 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.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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 unchangedexpect_statustext says "412 Precondition Failed", so the cancel page writes status codes two ways.enterprise/coderd/licenses.go:332: the entitlements refresh rate limit returns400, not429, so HTTP clients that retry on429withRetry-Aftertreat 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, andenterprise/coderd/templates.go:82.
Notes:
coderd/templateversions.go:1321: this route andenterprise/coderd/organizations.go:170document500for 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.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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 writes200(:356), so the published Responses table lists the wrong success code.@Failurelines 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, andenterprise/coderd/templates.go:82.
Notes:
coderd/exp_chats.go:2715: the documented archive409arrives afterpatchChathas saved the title and labels from the same request; that handler order is thecoderd/exp_chats.go:2934item above, and this text must change when it is fixed.coderd/templateversions.go:1321: this route andenterprise/coderd/organizations.go:170document500for 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.
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
|
/coder-agents-review Generated by Coder Agents on behalf of @nickvigilante. |
|
/coder-agents-review |
There was a problem hiding this comment.
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 archive409arrives afterpatchChathas saved the title and labels; this text must change when thecoderd/exp_chats.go:2934handler order is fixed.coderd/templateversions.go:1321: this route andenterprise/coderd/organizations.go:170document500for 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.
There was a problem hiding this comment.
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 returns400when 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
|
/coder-agents-review |
There was a problem hiding this comment.
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 onpostRefreshEntitlementsalso 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,@Failurelines 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, andenterprise/coderd/templates.go:82.
Notes:
coderd/usersecrets.go:429: the update route's limit sentence lists the 50-secret count, which aPATCHcan'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 archive409arrives afterpatchChathas saved the title and labels; this text must change when thecoderd/exp_chats.go:2934handler order is fixed.coderd/templateversions.go:1321: this route andenterprise/coderd/organizations.go:170document500for 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.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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 aPATCHcan't exceed; the sentence still holds as a statement of the limits.coderd/exp_chats.go:2715: the documented archive409arrives afterpatchChathas saved the title and labels; this text must change when thecoderd/exp_chats.go:2934handler order is fixed.coderd/templateversions.go:1321: this route andenterprise/coderd/organizations.go:170document500for 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.
|
I have read the CLA Document and I hereby sign the CLA 1 out of 2 committers have signed the CLA. |
Adds a
@Descriptionto every route the REST API reference publishes, and rewrites the thin or wrong@Paramtext 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/andenterprise/coderd/, the API index page text inscripts/apidocgen/postprocess, the@Securitycheck in the swagger test, comments on a fewcodersdklimit constants, and the files generated from them, so API behavior doesn't change.Commits 1 to 40 change only
descriptionvalues inswagger.json.Commits 41 and 42 also fix
security,required,format, and missing parameters where they contradict the new text.Field comments in
codersdkare 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.
mainmainThe last 12 commits are new:
GETandPUT /api/v2/chats/config/advisorandPATCH /api/v2/chats/{chat}/queue/{queuedMessage}landed onmainafter the area PRs were written, so commits 36 and 39 describe them.limit,after_id, and the log-streaming parameters one wording per behavior, and puts "Requires a Premium license." on its own line.dbauthzhas one: anyone who can update a template can read its files, and template insights check each template intemplate_ids.@Securityfrom the 13 routes registered withoutapiKeyMiddleware, dropsformat(uuid)from 42 path parameters that also accept a name,default,me, orprimary, marks 12 optional query parameters as not required, and declares 15 query parameters the handlers read.@Security, names the status code wherever a sentence said a call fails, and declares two more query parameters.memberandorganization-memberroles, and naming the status code on the last "Fails" sentences.Merge order
coderd/provisionerdaemons.go,coderd/provisionerjobs.go,coderd/exp_chats.go, andenterprise/coderd/idpsync.go, and every API docs PR regenerates the same files.@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
make coderd/apidoc/.genand the pre-commit hook, which runsmake pre-commit(gen, fmt, lint, typos, and a slim build). Commits 1 to 40 also passed a check thatswagger.jsonchanged onlydescriptionvalues, and the otherswagger.jsonchanges in commits 41 and 42 are the 13security, 12required, 42format, and 17 parameter changes listed above.coderdpackage tests,TestEndpointsDocumented,TestSDKFieldsFormatted,TestEnterpriseEndpointsDocumented, and thescripts/apidocgen/postprocesstests pass, andmake lint/emdashpasses. The rebase ontomainregenerated the API docs after each of commits 1 to 38 and reran thedescription-only check.<,>,{, or}outside backticks, which would break MDX renderers.@Securitycheck, the API index page string, and generated files, and CI runs the swagger tests on Linux, macOS, and Windows. The onlysite/change is four generated comment lines intypesGenerated.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
swagger.json,docs.go, anddocs/reference/api/are regenerated, never edited by hand.api.Authorizecall or itsdbauthzquery. The first plan also named the built-in roles that have each permission, but those lists drifted fromcoderd/rbac/roles.goand 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.userreads "User ID, username, ormefor the authenticated user." andorganizationreads "Organization ID, name, ordefaultfor the default organization."limit,offset, andafter_iduse one wording each, and differ only where a handler has its own default.@Failurelines for those codes, so each page's Responses table lists only the codes the annotations already declared. Adding@Failurelines is a follow-up for all routes at once, so later API docs PRs don't mix the two styles.limitdefaults.@Securityon routes without a session token,format(uuid)on parameters that accept names,requiredon optional parameters, and parameters the handlers read but the annotations left out.DeploymentValues, and the 103 hidden routes are out of scope too.Part of DOCS-1439.
Generated by Coder Agents on behalf of @nickvigilante.