Skip to content

docs: describe the Builds API operations and parameters - #31538

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This describes the eleven Builds routes that had no @Description and improves the thin or wrong parameter text on them, so the REST API reference renders more than a title.
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.

Existing text I corrected on routes in this list:

  • user said "User ID, name, or me". httpmw.ExtractUserParam takes an ID, a username, or me, so it now uses the shared wording.
  • after_id on GET /api/v2/workspaces/{workspace}/builds now says what the query does, which is to return builds with a higher build number than the build it names.
  • before on GET /api/v2/workspacebuilds/{workspacebuild}/logs now says it has no effect, because the handler never reads it.
  • follow on the same route now says that any value turns streaming on, because the handler checks only that the parameter is present.

Verification

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

A JSON diff of swagger.json against main shows 23 changes, all adding or editing description values on these routes and their parameters, and nothing else.
The 11 remaining thin parameters are all path IDs (workspacebuild and workspace) that accept only a UUID, so Workspace build ID and Workspace ID are 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 wrong or incomplete claims, which the Skeptic confirmed.
POST .../builds said the workspace owner has start, stop, and delete permission, but that comes from the Organization Workspace Access role, so the text now names it.
GET .../resources said it fails while the job is running, but it fails until the job completes, which includes a pending job.
The Copy Editor found one rule violation, "whose" for a thing in GET .../resources, which the Skeptic confirmed and which is rewritten.
The Continuity 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
POST /api/v2/workspaces/{workspace}/builds transition is start, stop, or delete codersdk/workspaces.go:123 (validate:"oneof=start stop delete,required")
POST /api/v2/workspaces/{workspace}/builds Needs permission to start, stop, or delete the workspace, which the Owner and Organization Admin roles have, and which the owner has through the Organization Workspace Access role coderd/wsbuilder/wsbuilder.go:1369 to :1390, 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
POST /api/v2/workspaces/{workspace}/builds A start build clears dormancy coderd/workspacebuilds.go:453
POST /api/v2/workspaces/{workspace}/builds orphan only with delete coderd/workspacebuilds.go:498
POST /api/v2/workspaces/{workspace}/builds state or orphan needs template update permission coderd/wsbuilder/wsbuilder.go:1433 to :1436, coderd/rbac/roles.go:414, :512, :587, :679
PATCH /api/v2/workspacebuilds/{workspacebuild}/cancel Cancel allowed when the template allows it, you are Owner, or expect_status is pending coderd/workspacebuilds.go:893, :992 to :1012
PATCH /api/v2/workspacebuilds/{workspacebuild}/cancel Fails if the job already completed or was canceled coderd/workspacebuilds.go:918, :924
GET /api/v2/workspacebuilds/{workspacebuild}/logs Oldest first, after is a log ID coderd/database/queries/provisionerjoblogs.sql:9 to :10 (id > @created_after ... ORDER BY id ASC)
GET /api/v2/workspacebuilds/{workspacebuild}/logs follow upgrades to a WebSocket, any value counts, one JSON ProvisionerJobLog per message, closes when the job finishes coderd/provisionerjobs.go:158, :585, :599, :700
GET /api/v2/workspacebuilds/{workspacebuild}/logs before is ignored coderd/provisionerjobs.go:154 to :180 (the handler reads only follow, after, and format)
GET /api/v2/workspacebuilds/{workspacebuild}/state Needs update permission on the template coderd/database/dbauthz/dbauthz.go:6128, coderd/database/modelmethods.go:450, coderd/rbac/roles.go:414, :512, :587, :679
PUT /api/v2/workspacebuilds/{workspacebuild}/state Needs update permission on the template, and doesn't queue a build coderd/workspacebuilds.go:1134, codersdk/workspacebuilds.go:222
GET /api/v2/workspacebuilds/{workspacebuild}/resources Returns a 400 until the job completes, including while it is pending coderd/provisionerjobs.go:217
GET /api/v2/workspacebuilds/{workspacebuild}/resources GET /api/v2/workspacebuilds/{workspacebuild} carries resources codersdk/workspacebuilds.go:87
GET /api/v2/workspaces/{workspace}/builds Newest first, since is an RFC 3339 lower bound, after_id returns higher build numbers coderd/database/queries/workspacebuilds.sql:40, :49, :61, coderd/workspacebuilds.go:135
GET /api/v2/workspaces/{workspace}/builds limit and offset default to 0 coderd/workspacebuilds.go:129 (ParsePagination), coderd/pagination.go:19 to :23
GET /api/v2/workspacebuilds/{workspacebuild}/timings Provisioner, agent script, and agent connection timings coderd/workspacebuilds.go:1669 to :1700
{user} path parameter Accepted forms coderd/httpmw/userparam.go:51 to :110
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 the builder's authorization checks and coderd/rbac/roles.go.
  • No license claims, because none of these routes sit behind RequireFeatureMW.
  • The log stream says it upgrades to a WebSocket and what each message carries.
  • The removed resources route keeps @Deprecated and names its replacement by full path.
  • No "whose" for things, per the word-choice rule.
  • Shared wording for user, limit, and offset, copied exactly, and parameter text that follows what the handler does.
  • 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 Builds 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