Skip to content

docs: describe the proxy, provisioner key, and replica API operations - #31525

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-proxies-provisioner-keys
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-proxies-provisioner-keys

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Adds @Description text to the 12 workspace proxy, provisioner key, provisioner daemon, and replica routes that had none, 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.

Verification

Head `20029fb19c`, after the self-check commit.

$ python3 check_routes.py <route list>
summary: need=12 problems=0 thin_params_left=0
$ 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 (24 changed, proven with a JSON walk that fails on any other change).

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 1 blocking finding (a @Description line with two sentences on POST /api/v2/workspaceproxies) and 2 suggestions (the provisionerkey path text on GET /api/v2/provisionerkeys/{provisionerkey}, and the permission sentence on GET /api/v2/workspaceproxies).
Skeptic rejected 0 findings.

Annotation bugs noticed, not fixed here
  • GET /api/v2/provisionerkeys/{provisionerkey}: the handler ignores the path value and returns the key from the Coder-Provisioner-Daemon-Key header.
  • GET .../provisionerdaemons/serve: organization carries format(uuid), but the route accepts an ID, name, or default. The query parameters provisioner, name, version, and tag have no @Param lines.
  • .../workspaceproxies/{workspaceproxy}: workspaceproxy carries format(uuid), but the route accepts an ID, name, or primary.
Claims checked against the code
Route Claim Evidence
GET /api/v2/organizations/{organization}/provisionerdaemons/serve Premium license enterprise/coderd/coderd.go:617, enterprise/coderd/provisionerdaemons.go:41-50 (provisionerDaemonsEnabledMW)
GET .../provisionerdaemons/serve Upgrades to a WebSocket carrying multiplexed dRPC enterprise/coderd/provisionerdaemons.go (websocket.Accept, yamux.Server, drpcmux)
GET .../provisionerdaemons/serve coder provisioner start connects here enterprise/cli/provisionerdaemonstart.go:227, codersdk/provisionerdaemons.go:298
GET .../provisionerdaemons/serve Auth by key header, PSK header, or session token codersdk/client.go:99-103, codersdk/provisionerdaemons.go:320-330, enterprise/coderd/coderd.go:617-627
GET .../provisionerdaemons/serve Key sets the tags, tag not allowed with a key, key's organization applies enterprise/coderd/provisionerdaemons.go:83-93
GET .../provisionerdaemons/serve PSK works only for the default organization enterprise/coderd/provisionerdaemons.go:96-100
GET .../provisionerdaemons/serve scope=user open to any user, other scopes need create on provisioner daemons enterprise/coderd/provisionerdaemons.go:127-140, provisionersdk/provisionertags.go:6-10
GET .../provisionerdaemons/serve Roles with create on provisioner daemons coderd/rbac/roles.go:508-520 (Template Admin), coderd/rbac/roles.go:421-432,596-625 (Owner, Organization Admin), coderd/rbac/roles.go:679-690 (Organization Template Admin)
GET .../provisionerdaemons/serve Query parameters provisioner, name, version, tag enterprise/coderd/provisionerdaemons.go:162-250
GET .../provisionerdaemons/serve organization takes ID, name, or default enterprise/coderd/coderd.go:625 (ExtractOrganizationParam), coderd/httpmw/organizationparam.go:54-85
POST, GET, GET .../daemons, DELETE on /api/v2/organizations/{organization}/provisionerkeys Premium license enterprise/coderd/coderd.go:589-594 (FeatureExternalProvisionerDaemons)
provisioner key routes Create, read, delete on provisioner daemons in the organization, held by Owner, Template Admin, Organization Admin, Organization Template Admin coderd/database/dbauthz/dbauthz.go:2704,6848,7417-7423, coderd/database/modelmethods.go:676-680, coderd/rbac/roles.go:508-520
POST .../provisionerkeys Name at most 64 characters, not built-in, user-auth, or psk, 409 on duplicates enterprise/coderd/provisionerkeys.go:56-95, codersdk/provisionerdaemons.go:397-409
POST .../provisionerkeys Secret stored only as a hash and returned once enterprise/coderd/provisionerkeys.go:78,102, enterprise/coderd/provisionerkeys.go:269 (convert comment)
GET .../provisionerkeys Oldest first, reserved keys left out, only keys you can read enterprise/coderd/provisionerkeys.go:123,284, coderd/database/dbauthz/dbauthz.go:7421
GET .../provisionerkeys/daemons Includes the user-auth key and recently seen daemons enterprise/coderd/provisionerkeys.go:151-193
DELETE .../provisionerkeys/{provisionerkey} Reserved keys can't be deleted, active sessions tear down enterprise/coderd/provisionerkeys.go:219-238
GET /api/v2/provisionerkeys/{provisionerkey} Authenticates with the Coder-Provisioner-Daemon-Key header and returns that key, ignoring the path value enterprise/coderd/coderd.go:574-583, enterprise/coderd/provisionerkeys.go:255-266
GET /api/v2/replicas Requires read on replicas, held by the Owner role enterprise/coderd/replicas.go:25, coderd/rbac/roles.go:421-432
GET and POST /api/v2/workspaceproxies, GET, PATCH, DELETE .../{workspaceproxy} Premium license enterprise/coderd/coderd.go:413 (FeatureWorkspaceProxy)
GET /api/v2/workspaceproxies Members can read proxies coderd/rbac/roles.go:446-455, coderd/database/dbauthz/dbauthz.go:6190
GET /api/v2/workspaceproxies Primary region first, health status enterprise/coderd/workspaceproxy.go:455-475
POST /api/v2/workspaceproxies Owner only (create on workspace proxies), name primary reserved, token returned coderd/database/dbauthz/dbauthz.go:7219, enterprise/coderd/workspaceproxy.go:350,401-407
PATCH .../{workspaceproxy} Update on workspace proxies, regenerate_token, primary only display_name and icon coderd/database/dbauthz/dbauthz.go:9439, enterprise/coderd/workspaceproxy.go:125,173-175,189-215
DELETE .../{workspaceproxy} Delete on workspace proxies, primary can't be deleted coderd/database/dbauthz/dbauthz.go:9446, enterprise/coderd/workspaceproxy.go:271
.../{workspaceproxy} Accepts ID, name, or primary coderd/httpmw/workspaceproxy.go:177-186
organization on provisioner key routes Accepts ID, name, or default enterprise/coderd/coderd.go:589, coderd/httpmw/organizationparam.go:54-85
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.
  • Credentials named where a route takes something other than a session token: the Coder-Provisioner-Daemon-Key and Coder-Provisioner-Daemon-PSK headers.
  • The serve route says it upgrades to a WebSocket and what the connection carries.
  • Shared organization wording, only where the route uses ExtractOrganizationParam.
  • 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 workspace proxies, provisioner keys, the provisioner daemon connection, and replicas.

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 a description line with two sentences, an ambiguous workspace proxy permission sentence, and a confusing provisioner key path parameter.

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 proxy, provisioner key, and replica 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