Skip to content

docs: describe the Workspaces API operations and parameters - #31539

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-workspaces
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-workspaces

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This describes the 20 Workspaces routes that had no @Description, fixes parameter text that was wrong or thin on them, and leaves the routes that #30125 documents alone.
The reference comes from swagger.json, which make gen builds from these annotations.

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.
GET /api/v2/workspaces/{workspace}/watch-ws is not touched, because #30125 owns it.
Its sibling GET /api/v2/workspaces/{workspace}/watch is described here, and points to watch-ws as its replacement.

Existing text I corrected on routes in this list:

  • include_deleted on GET /api/v2/workspaces/{workspace} said it returns data "instead of HTTP 404". The handler returns 410 Gone, so the text now says that. The text on the by-name route stays at 404, which is what that handler returns.
  • q on GET /api/v2/workspaces listed 11 keys. searchquery.Workspaces accepts more, so the text now lists all of them.
  • user said "User ID, name, or me" or "Username, UUID, or me". Both routes resolve it with httpmw.ExtractUserParam or ExtractOrganizationMembersParam, which take an ID, a username, or me, so they now use the shared wording.

Verification

check_routes.py: summary: need=0 problems=0 thin_params_left=17
go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.435s
go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.536s

A JSON diff of swagger.json against main shows 45 changes, all adding or editing description values on these routes and their parameters, and nothing else.
The 17 remaining thin parameters are all workspace path IDs, which accept only a UUID, so Workspace ID is complete.
check_routes.py was run against the fresh list for this branch, which matches the shared list except that it reflects these edits.

doc-check ran in author self-check mode on the branch diff, persona by persona.
The Fact Checker found two incomplete claims, which the Skeptic confirmed.
The six update routes and the two ACL routes said the workspace owner has the permission outright, but it comes from the Organization Workspace Access role, so the text now names it.
GET .../agent-connection-watch said build_update is sent when transition or job_status changes, but the server also sends it first and when the build number changes, so the text now says so.
The Continuity Editor and the Copy Editor found nothing.
The fixes are in the follow-up commit, and the swagger tests, check_routes.py, and the swagger.json diff were run again.

Claims checked against the code
Route Claim Evidence
PATCH /api/v2/workspaces/{workspace}, /autostart, /ttl, /dormant, /autoupdates, /usage Need update permission on the workspace, which Owner and Organization Admin have and which the owner has through the Organization Workspace Access role coderd/database/dbauthz/dbauthz.go:9138, :9300, :9453, :9414, :9287 (UpdateWorkspace, autostart, TTL, dormant, automatic updates), coderd/workspaces.go:1848, coderd/rbac/roles.go:236 to :244 (orgWorkspaceAccessMemberPerms, not part of the member floor), :414 (Owner), :587 (Organization Admin), docs/admin/users/groups-roles.md:36 to :38
PATCH /api/v2/workspaces/{workspace} Renames only when the deployment or template allows it coderd/workspaces.go:1259
PUT .../autostart Schedule form, empty turns it off, template can disallow it, prebuilt workspaces fail codersdk/workspaces.go:333 to :336, coderd/workspaces.go:1350, :1376, :3251
PUT .../ttl One minute to 30 days, null or 0 turns autostop off, template can disallow it, prebuilt workspaces fail coderd/workspaces.go:54 to :58, :1457, :1472, :3183 to :3215
PUT .../dormant 304 when already in that state, prebuilt workspaces fail, owner notified when another user marks it dormant coderd/workspaces.go:1590, :1600, :1655
PUT .../extend New deadline at least 30 minutes ahead, can't pass the template maximum, workspace must be running and built, deadline can't be manual, prebuilt workspaces fail coderd/workspaces.go:59, :1747, :3235 :1775, :1781, :1787, :1805
POST .../usage Marks the workspace used, and with the workspace-usage experiment and agent_id plus app_name counts an app session coderd/workspaces.go:1853 to :1860, codersdk/deployment.go:5503 (ExperimentWorkspaceUsage, "workspace-usage")
PUT and DELETE .../favorite Owner only coderd/workspaces.go:1958, :2007
PUT .../autoupdates Values are always or never coderd/workspaces.go:2074
GET .../resolve-autostart parameter_mismatch needs a template that requires the active version or always updates, an older build, and an unresolved parameter coderd/workspaces.go:2125, :2140, :2190
GET .../watch Server-sent events with ping, data, and error, a first ping, then the current workspace on each change coderd/workspaces.go:2351, codersdk/serversentevents.go:23 to :25
GET .../timings Timings of the latest build, in three lists coderd/workspaces.go:2469 (GetLatestWorkspaceBuildByWorkspaceID), coderd/workspacebuilds.go:1669 to :1700
GET .../acl Users and groups with admin or use role, minimal identity only coderd/workspaces.go:2507 to :2601, codersdk/workspaces.go:843 to :844
PATCH and DELETE .../acl Need share permission, fail when sharing is off for the organization, and you can't change your own role unless you can share any workspace in the organization coderd/database/dbauthz/dbauthz.go:9149, :2845, coderd/workspaces.go:2637, :2652, :2759, :2790 to :2805
PATCH and DELETE .../acl Who has share permission: Owner, Organization Admin, and the owner through the Organization Workspace Access role when the organization lets everyone share coderd/rbac/roles.go:236 to :244, :414 (Owner), :587 (Organization Admin), :1195 to :1245 (members share only when the organization lets everyone)
GET .../agent-connection-watch WebSocket, message kinds, the initial send, and the conditions that send them, agent_name selects the agent, server closes on any client message coderd/workspaceconnwatcher/watcher.go:74, :135, :217 to :256, :258 to :332, codersdk/workspacesdk/workspaceagentconnwatch.go:27 to :55
GET /api/v2/workspaces/{workspace} 410 Gone for a deleted workspace unless include_deleted is true coderd/workspaces.go:98
GET /api/v2/users/{user}/workspace/{workspacename} 404 for a deleted workspace unless include_deleted is true coderd/workspaces.go:331 to :345
GET /api/v2/workspaces Returns only readable workspaces, q keys coderd/workspaces.go:188 to :260 (GetWorkspaces authorizes the query itself), coderd/searchquery/search.go:323 to :390
GET /api/v2/workspaces, GET .../available-users limit and offset default to 0 coderd/workspaces.go:192, coderd/users.go:386, coderd/pagination.go:19 to :23
GET .../available-users Needs permission to create workspaces for other users in the organization coderd/workspaces.go:3341, coderd/rbac/roles.go:414, :587
GET .../available-users Lists users deployment-wide, q uses the user search keys coderd/workspaces.go:3349, coderd/users.go:374 to :410, coderd/searchquery/search.go:217 to :231
Writing rules applied
  • One to three sentences per route, present tense, first sentence starts with a verb and stands alone.
  • Permission sentences name the built-in roles, traced to dbauthz or Authorize calls and coderd/rbac/roles.go.
  • No license claims, because none of these routes sit behind RequireFeatureMW.
  • Streaming routes say what they upgrade to, what each message carries, and who closes the connection, using the wording from fix: document WebSocket routes as 101 responses in the Swagger spec #30125.
  • The deprecated watch route keeps @Deprecated and names its replacement by full path.
  • The workspace-usage experiment appears by its exact name in backticks.
  • Shared wording for user, organization, limit, and offset, copied exactly.
  • Body parameters say what the body is, not the request type name.
  • Full API paths and literals in backticks, with no dashes or semicolons.

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

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