Skip to content

docs: describe the template and workspace control API operations - #31520

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-template-workspace-controls
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-template-workspace-controls

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Adds @Description text to the 10 template and workspace control routes that had none (template ACLs, prebuild invalidation, quiet hours, the connection log, workspace sharing settings, and external agent credentials), and replaces thin or incomplete parameter text on those routes.
The REST API reference renders these routes from swagger.json, so they showed only a title.

Merge notes

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

GET /api/v2/organizations/{organization}/paginated-groups already had a description, but its description had raw braces outside backticks, which check_routes.py flags.
This PR wraps the two paths in backticks and gives them the full /api/v2 prefix, and improves its organization, limit, offset, and after_id parameters.

Verification

Head `33f34559fe`, after the self-check commit.

$ python3 check_routes.py <route list>
summary: need=10 problems=0 thin_params_left=5
$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest
$ make lint/emdash
OK: no emdash or endash characters found.

The swagger.json diff against origin/main changes only description values (26 changed on the routes in this PR, proven with a JSON walk that fails on any other change).

Remaining THIN lines are path IDs that accept only a UUID (template and workspace), so Template ID and Workspace ID are complete.

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 the survivors.
Fixed 3 blocking findings: the limit text on GET /api/v2/connectionlog no longer says what happens when the parameter is omitted (the annotation marks it required), the q search keys are in backticks, and the workspace sharing text no longer has an ambiguous it. Also reworded the service_accounts sentence.
Skeptic rejected 1 finding.
Rejected: a Fact Checker note that the template ACL permission sentence leaves out users with the template admin role, because the sentence doesn't claim to list every holder.

Annotation bugs noticed, not fixed here
  • GET /api/v2/connectionlog: limit is marked required in the annotation, but the handler treats it as optional (ParsePagination defaults it to 0, which returns up to 100 results).
  • GET and PUT /api/v2/users/{user}/quiet-hours: @Success declares an array of codersdk.UserQuietHoursScheduleResponse, but the handlers return a single object.
  • GET and PATCH .../settings/workspace-sharing: organization carries format(uuid), but the route accepts an ID, name, or default.
  • GET and PUT /api/v2/users/{user}/quiet-hours: user carries format(uuid), but the route accepts an ID, username, or me.
Claims checked against the code
Route Claim Evidence
GET /api/v2/connectionlog Premium license enterprise/coderd/coderd.go:385 (RequireFeatureMW(FeatureConnectionLog))
GET /api/v2/connectionlog Reads need connection log read permission, held by Owner and Auditor, and by Organization Admin and Organization Auditor in their organization coderd/database/dbauthz/dbauthz.go:2135,4052, coderd/rbac/roles.go:485,627
GET /api/v2/connectionlog Returns only entries you can read coderd/database/dbauthz/dbauthz.go:2141,4059 (prepareSQLFilter)
GET /api/v2/connectionlog Newest first coderd/database/queries/connectionlogs.sql:145
GET /api/v2/connectionlog A limit of 0 returns up to 100 results coderd/database/queries/connectionlogs.sql:151
GET /api/v2/connectionlog count capped, count_cap is 2000 enterprise/coderd/connectionlog.go:20
GET /api/v2/connectionlog q keys, enum values, me aliases, and type exclusive with method and app coderd/searchquery/search.go:91-151
GET and PATCH /api/v2/organizations/{organization}/settings/workspace-sharing organization takes ID, name, or default enterprise/coderd/coderd.go:513-523 (ExtractOrganizationParam), coderd/httpmw/organizationparam.go:54-85
GET .../workspace-sharing --disable-workspace-sharing forces sharing_globally_disabled and none enterprise/coderd/workspacesharing.go:42-50, codersdk/deployment.go:3824-3826
PATCH .../workspace-sharing Requires update on the organization (Owner, Organization Admin) enterprise/coderd/workspacesharing.go:82, coderd/rbac/roles.go:421-432,596-625
PATCH .../workspace-sharing none or service_accounts removes existing shares enterprise/coderd/workspacesharing.go:173-180
PATCH .../workspace-sharing sharing_disabled applies only when shareable_workspace_owners is empty enterprise/coderd/workspacesharing.go:95-104
GET and PATCH /api/v2/templates/{template}/acl, GET .../acl/available Premium license enterprise/coderd/coderd.go:631-637 (templateRBACEnabledMW), enterprise/coderd/templates.go:348
GET .../acl, GET .../acl/available Requires update on the template coderd/database/dbauthz/dbauthz.go:9965-9987, enterprise/coderd/templates.go:46
PATCH .../acl Requires create on the template coderd/database/dbauthz/dbauthz.go:8651-8657
template ACL routes Update and create on templates held by Owner, Template Admin, Organization Admin, Organization Template Admin coderd/rbac/roles.go:508-512,679, Owner and Organization Admin via allPermsExcept at coderd/rbac/roles.go:421-432,596-625
PATCH .../acl Roles admin and use, empty string removes, omitted entries unchanged codersdk/templates.go:205-236, enterprise/coderd/templates.go:266-277
GET .../acl/available Honors q and limit enterprise/coderd/templates.go:54-70
POST /api/v2/templates/{template}/prebuilds/invalidate Premium license enterprise/coderd/coderd.go:643 (FeatureWorkspacePrebuilds)
POST .../prebuilds/invalidate Requires update on the template enterprise/coderd/templates.go:397, coderd/database/dbauthz/dbauthz.go:8502-8509
POST .../prebuilds/invalidate Invalidates presets of the active version, prebuilds are replaced coderd/database/queries/presets.sql:109-120, coderd/prebuilds/global_snapshot.go:127-137, codersdk/templates.go:580-582
GET and PUT /api/v2/users/{user}/quiet-hours Premium license enterprise/coderd/users.go:19-37, enterprise/coderd/coderd.go:715-719
GET .../quiet-hours Default until the user sets one, user_set and user_can_set enterprise/coderd/schedule/user.go:45-90
PUT .../quiet-hours 403 when custom schedules are off, controlled by --allow-custom-quiet-hours enterprise/coderd/users.go:110, enterprise/coderd/schedule/user.go:94-96, codersdk/deployment.go:4020-4026
PUT .../quiet-hours Own schedule, or Owner and User Admin for others coderd/database/dbauthz/dbauthz.go:8996-9003, coderd/rbac/roles.go:463,539-541
PUT .../quiet-hours Single daily time, optional CRON_TZ= prefix, example from the default codersdk/users.go:362-372, enterprise/coderd/schedule/user.go:55-68, codersdk/deployment.go:4010-4013
user parameter on quiet hours Takes ID, username, or me enterprise/coderd/coderd.go:715-720 (ExtractUserParam at line 719), coderd/httpmw/userparam.go:34-62
GET /api/v2/workspaces/{workspace}/external-agent/{agent}/credentials Premium license enterprise/coderd/coderd.go:761 (FeatureWorkspaceExternalAgent)
GET .../external-agent/{agent}/credentials Requires SSH permission on the workspace, which the owner has enterprise/coderd/workspaceagents.go:48, coderd/rbac/roles.go:400-425
GET .../external-agent/{agent}/credentials Token and install command, only for an external agent in the latest build enterprise/coderd/workspaceagents.go:54-103
GET /api/v2/organizations/{organization}/paginated-groups organization takes ID, name, or default enterprise/coderd/coderd.go:564-569, coderd/httpmw/organizationparam.go:54-85
GET .../paginated-groups limit default 0 returns all, offset, after_id keyset coderd/pagination.go:14-24, coderd/database/queries/groups.sql:107-130
Writing rules applied
  • One to three present-tense sentences, first sentence starts with a verb and stands alone on the endpoint card.
  • Permission sentences name the check and the built-in roles, traced to dbauthz and roles.go.
  • "Requires a Premium license." only where the router uses RequireFeatureMW or an entitlement middleware.
  • Shared user and organization wording, only where the route uses the matching httpmw extractor.
  • The handler's own limit default (100) instead of the shared wording for the connection log.
  • Full /api/v2 paths and backticks around field names, enum values, and flags.
  • No em dashes, en dashes, semicolons, or raw braces and angle brackets outside backticks.

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 descriptions and fuller parameter text for template ACLs, prebuild invalidation, quiet hours, the connection log, workspace sharing settings, and external agent credentials.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

A doc-check self-review found the connection log limit text described omitted-parameter behavior on a parameter marked required, the `q` search keys without code formatting, and ambiguous wording in the workspace sharing text.

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 template and workspace control API operations. 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