Skip to content

docs: describe the Organizations API operations and parameters - #31524

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This describes the seven Organizations 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.
The ids and status parameters of GET /api/v2/organizations/{organization}/provisionerjobs are unchanged, because #30124 and #30122 own them.

Existing text I corrected on routes in this list:

  • organization on PATCH and DELETE /api/v2/organizations/{organization} said "ID or name". It also accepts default, so it now uses the shared wording.
  • organization on GET /api/v2/organizations/{organization} and the provisioner job routes said "Organization ID", but httpmw.ExtractOrganizationParam also accepts a name and default.

Verification

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

A JSON diff of swagger.json against main shows 16 changes, all adding or editing description values on these routes and their parameters, and nothing else.
The one remaining thin parameter is the job path ID, which accepts only a UUID.

doc-check ran in author self-check mode on the branch diff.
The Fact Checker checked every added claim against the code, the Continuity Editor compared the text with docs/admin/users/organizations.md and the glossary, and the Copy Editor read each added line against the style guide.
They returned no blocking findings, so this PR needed no follow-up commit.
The Skeptic had nothing to verify.

Claims checked against the code
Route Claim Evidence
GET /api/v2/organizations Returns only the organizations you can read coderd/database/dbauthz/dbauthz.go:4759 (fetchWithPostFilter)
POST /api/v2/organizations Needs a Premium license enterprise/coderd/coderd.go:451 (RequireFeatureMW(FeatureMultipleOrganizations))
POST /api/v2/organizations Needs permission to create organizations, which only Owner has coderd/database/dbauthz/dbauthz.go:6745 (insert on ResourceOrganization), coderd/rbac/roles.go:414 (Owner), coderd/rbac/roles.go:587 (Organization Admin has only organization-scoped permissions)
POST /api/v2/organizations Adds you as a member with no roles, display_name defaults to name, default is reserved enterprise/coderd/organizations.go:291, :326, :360
PATCH and DELETE /api/v2/organizations/{organization} Need a Premium license enterprise/coderd/coderd.go:459 to :462
PATCH /api/v2/organizations/{organization} Needs update permission on the organization (Owner, Organization Admin) coderd/database/dbauthz/dbauthz.go:8408, coderd/rbac/roles.go:587
PATCH /api/v2/organizations/{organization} Omitted fields keep their values, default is reserved enterprise/coderd/organizations.go:60, :118 to :130
DELETE /api/v2/organizations/{organization} Needs delete permission on the organization (Owner, Organization Admin) coderd/database/dbauthz/dbauthz.go:8434 (deleteQ), coderd/rbac/roles.go:587
DELETE /api/v2/organizations/{organization} Fails for the default organization enterprise/coderd/organizations.go:194
DELETE /api/v2/organizations/{organization} Fails while workspaces, templates, provisioner keys, groups other than Everyone, or more than one member remain coderd/database/migrations/000318_update_protect_deleting_orgs_to_filter_deleted_users.up.sql:81 to :89
Provisioner job routes Need read permission on provisioner jobs (Owner, Organization Admin, Organization Template Admin) coderd/provisionerjobs.go:105, coderd/rbac/roles.go:587, :693
GET .../provisionerjobs Newest first coderd/database/queries/provisionerjobs.sql:261 (ORDER BY pj.created_at DESC)
GET .../provisionerjobs limit defaults to 50, 0 returns all jobs coderd/provisionerjobs.go:112, :131 (Valid: limit > 0)
{organization} path parameters Accept an ID, name, or default coderd/httpmw/organizationparam.go:54 to :96
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.
  • "Requires a Premium license" appears only on routes behind RequireFeatureMW.
  • Shared wording for organization path parameters, 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

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

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