Skip to content

docs: describe the license and appearance API operations - #31543

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

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

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

This adds a @Description to the 10 license, entitlements, appearance, premium funnel, and notification template method routes in the Enterprise tag that had none, and improves the text of their six body and path parameters.
The REST API reference renders these routes from swagger.json, so their pages showed only a title.

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 11-enterprise-licenses.txt
summary: need=10 problems=0 thin_params_left=1

$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.400s

$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.471s

A JSON diff of swagger.json against origin/main shows 10 operation descriptions and 6 parameter descriptions changed, and nothing else.
The remaining thin parameter is notification_template, a path ID that accepts only a UUID, so Notification template ID. is complete.

Claims checked against the code
Route Claim Evidence
POST /api/v2/licenses No license is required to add one; only create permission on licenses enterprise/coderd/coderd.go:399-406 (only apiKeyMiddleware, no RequireFeatureMW), enterprise/coderd/licenses.go:96
POST /api/v2/licenses, POST .../trial, POST .../refresh-entitlements Requires create on licenses, which only Owner has enterprise/coderd/licenses.go:96,160,323, coderd/rbac/roles.go:422 (Owner gets all permissions except the listed ones, licenses are not excluded), no other role grants license permissions
POST /api/v2/licenses Several licenses can coexist; 400 for an invalid key or a key locked to another deployment enterprise/coderd/licenses.go:62-70,106-123
POST /api/v2/licenses/refresh-entitlements Once per minute, 400 with Retry-After coderd/entitlements/entitlements.go:91-101, enterprise/coderd/licenses.go:330-334
POST /api/v2/licenses/trial 409 when the deployment already has a license; request goes to the license server enterprise/coderd/licenses.go:171-195
POST /api/v2/licenses/trial source and attribution_id are for telemetry and aren't forwarded codersdk/licenses.go:43-48, enterprise/coderd/licenses.go:179-190
GET /api/v2/licenses Returns only licenses you can read; only Owner can enterprise/coderd/licenses.go:401, coderd/rbac/roles.go:422
DELETE /api/v2/licenses/{id} Requires delete on licenses; ID is an integer enterprise/coderd/licenses.go:437,460
GET /api/v2/entitlements Returns the entitlements JSON, including features, warnings, errors, license and trial flags, telemetry requirement, refresh time enterprise/coderd/coderd.go:1431-1434, codersdk/deployment.go:540-548
GET /api/v2/entitlements Doesn't require a session token enterprise/coderd/coderd.go:371-372 (route registered with no apiKeyMiddleware)
GET /api/v2/entitlements The dashboard reads it site/src/api/api.ts calls /api/v2/entitlements
GET /api/v2/appearance Accepts a session token or a workspace agent token enterprise/coderd/coderd.go:696-707 (RequireAPIKeyOrWorkspaceAgent)
GET, PUT /api/v2/appearance Name, logo, and banners apply only with the appearance feature enterprise/coderd/coderd.go:1175-1190, coderd/appearance/appearance.go:21-31
PUT /api/v2/appearance Requires update on deployment configuration, which only Owner has; replaces all values; banner colors must be hex enterprise/coderd/appearance.go:163,176,197-230, coderd/rbac/roles.go:422,495
POST /api/v2/deployment/premium-funnel-events Records a telemetry event; returns 404 without read on licenses coderd/premiumfunnel.go:33-36,59-76
POST /api/v2/deployment/premium-funnel-events The dashboard calls it site/src/api/api.ts and site/src/api/queries/premiumFunnel.ts (dashboard client)
POST /api/v2/deployment/premium-funnel-events variant is premium, small, or ai_governance codersdk/premiumfunnel.go:81-83
PUT /api/v2/notifications/templates/{notification_template}/method Methods smtp, webhook, inbox; 304 when unchanged coderd/database/models.go:2874-2876, enterprise/coderd/notifications.go:46-72
Same Requires update on notification templates, which only Owner has coderd/database/dbauthz/dbauthz.go:8387-8392, coderd/rbac/roles.go:422
doc-check self-check

Author self-check mode, run on the annotation text in the diff, with nothing posted to GitHub.
Personas that ran: Fact Checker, Consistency, Language, and Skeptic (verifier).
Personas skipped: Cartographer, Newcomer, Reader Advocate, and Architect, because no hand-written docs page or navigation changed, only annotation text and its generated output.
No blocking findings remain.
make lint/emdash passed, and the generated docs/reference/api/enterprise.md went through the markdownlint step of make gen.

Writing rules applied
  • One to three sentences in present tense, active voice, each starting with a verb.
  • No license line on POST /api/v2/licenses, because adding a license can't require one, and none on routes that have no RequireFeatureMW.
  • Role display names, and only roles traced through roles.go.
  • Authentication: GET /api/v2/entitlements says it doesn't require a session token, and GET /api/v2/appearance names the workspace agent token alternative.
  • Say who calls the telemetry route: the dashboard.
  • Body parameters say what the body is.
  • Literals, field names, and enum values in backticks, with full API paths.
  • "Select" instead of "click" in prose.
  • No em dashes, en dashes, semicolons in prose, or raw angle brackets and braces 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 describes the license, entitlements, appearance, premium funnel,
and notification template method routes, and improves their parameter
text.

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 license and appearance 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