Skip to content

docs: describe the Provisioning API operations and parameters - #31519

Closed
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-provisioning
Closed

nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-provisioning

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes GET /api/v2/organizations/{organization}/provisionerdaemons and improves its organization and limit parameters, so the REST API reference page for the route has more than a title.
The reference renders from swagger.json, and this route had no description.

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.

Verification

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

A JSON diff of swagger.json against origin/main changes only description values: 3 in total, all on routes in this PR or their parameters, and no other value differs.

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 what survived. The other personas (Cartographer, Newcomer, Reader Advocate, Architect) didn't run.

  • Fact Checker, Continuity Editor, and Copy Editor returned no blocking findings.
  • Skeptic rejected 1: the organization text names a name and default while the annotation says format(uuid). The shared wording is mandated where the route uses ExtractOrganizationParam, and types are out of scope.

The ids and status parameters are untouched because #30124 and #30122 change them.

Claims checked against the code
Route Claim Evidence
GET /api/v2/organizations/{organization}/provisionerdaemons Requires permission to read provisioner jobs in the organization, which the Owner, Organization Admin, and Organization Template Admin roles have, and returns 404 without it coderd/provisionerdaemons.go:42-45, coderd/rbac/roles.go:414-422 (Owner has all permissions except a list that excludes neither resource), coderd/rbac/roles.go:601 (Organization Admin, ResourceProvisionerJobs isn't excluded), coderd/rbac/roles.go:693 (Organization Template Admin)
GET /api/v2/organizations/{organization}/provisionerdaemons The site-wide Template Admin role is not listed, because it has no ResourceProvisionerJobs permission coderd/rbac/roles.go:507-526
organization path parameter Accepts an ID, name, or default coderd/coderd.go:1567 (ExtractOrganizationParam), coderd/httpmw/organizationparam.go:67-90
limit query parameter Default 50, and 0 returns all results coderd/provisionerdaemons.go:49 (PositiveInt32(qp, 50, "limit")), :71 (Valid: limit > 0)
GET /api/v2/organizations/{organization}/provisionerdaemons Returns each daemon's status and current and previous job coderd/provisionerdaemons.go:84-113
Writing rules applied
  • One to three sentences per route, present tense, first sentence starts with a verb and stands alone on the endpoint card.
  • Permissions name the built-in roles, traced through api.Authorize calls, middleware, and coderd/rbac/roles.go.
  • Routes without a session token say so, and routes with another credential name it.
  • Streams say that the route upgrades to a WebSocket or sends server-sent events, and what each message carries.
  • Full API paths and literals (fields, parameters, values) are in backticks.
  • Shared parameter wording is copied exactly only where the code matches it.
  • No em dashes, en dashes, semicolons, or raw angle brackets and braces outside backticks.
Annotation notes, not changed here
  • The handler also accepts offline and max_age query parameters that have no @Param, and it rejects any other query parameter (ErrorExcessParams).
  • The organization parameter has format(uuid), but the middleware also accepts a name or default.
  • The frozen ids text says "job IDs", but the handler passes the IDs to the daemon query.

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 one to each Provisioning route and improves the
parameter descriptions.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Provisioning 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