Skip to content

docs: describe the Templates API operations and parameters - #31540

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Adds @Description text to the 35 published Templates routes that had none, and replaces thin or wrong parameter text on the same routes (33 parameters).
The REST API reference renders these pages from swagger.json, so they showed only a title.

The previous template version route (.../versions/{templateversionname}/previous) belongs to #30125 and isn't touched.

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.

Two existing parameter texts were wrong and are fixed here:

  • On GET /api/v2/templateversions/{templateversion}/dry-run/{jobID}/logs, after said "After Unix timestamp", but the handler compares it with the log id (GetProvisionerLogsAfterID), as it does on the template version logs route.
  • On both logs routes, before is documented but the handler never reads it, so its text now says so.

Verification

$ python3 check_routes.py 07-templates.txt
summary: need=35 problems=0 thin_params_left=29

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

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

$ make lint/emdash
OK: no emdash or endash characters found.

A JSON diff of swagger.json against origin/main shows 68 changed description values (35 new route descriptions and 33 parameter descriptions) and no other difference.

The 29 remaining thin parameters are all path IDs that accept only a UUID (template and templateversion), where Template ID and Template version ID are complete.

The doc-check self-check ran persona by persona: Fact Checker, Continuity Editor, Copy Editor, then Skeptic.
The Fact Checker found two issues, which the follow-up commit fixes: the dry-run cancel route also needs permission to update the template (dbauthz.go:8595-8610), and the unlicensed max_port_share_level check rejects only values other than public.
The Fact Checker also confirmed that without a Premium license the PATCH handler ignores the update_workspace_last_used_at and update_workspace_dormant_at fields, because only the enterprise schedule store reads them (enterprise/coderd/schedule/template.go:107-195).
The Continuity Editor and Copy Editor reported no findings.
The Skeptic verified both findings and rejected 2 candidate findings that weren't caused by this change.
The checks above were re-run after the follow-up commit.

Claims checked against the code

Line numbers are on this branch.
roles.go rows cite the role definitions: Owner :414, Template Admin :507, Organization Admin :587, Organization Template Admin :669, Auditor :479, Organization Auditor :617, Organization Workspace Access :738.

Route Claim Evidence
POST /api/v2/organizations/{organization}/templates Needs permission to create templates in the organization: Owner, Template Admin, Organization Admin, Organization Template Admin dbauthz.go:6873 (InsertTemplate), roles.go:414,507,587,669
same The version can't be archived or already in a template, and its import job can still be running templates.go:280,290, codersdk/organizations.go:158-164
same Everyone group gets the use role unless disable_everyone_group_access is true templates.go:437-440, db2sdk.go:995
same Without a Premium license, scheduling and require_active_version settings are ignored templates.go:471,484, coderd/schedule/template.go:183-190,227, dbauthz/accesscontrol.go:35-68, enterprise/coderd/coderd.go:1069,1167
same Without a Premium license, max_port_share_level returns a validation error templates.go:381, coderd/portsharing/portsharing.go:23, enterprise/coderd/coderd.go:1190
PATCH /api/v2/templates/{template} Omitted fields keep their current values templates_meta_update.go:83-113, templates.go:712
same Needs permission to update the template: Owner, Template Admin, Organization Admin, Organization Template Admin dbauthz.go:8679 (UpdateTemplateMetaByID), roles.go:414,507,587,669
same Without a Premium license, autostop_requirement, autostart_requirement, allow_user_autostart, allow_user_autostop, failure_ttl_ms, time_til_dormant_ms, time_til_dormant_autodelete_ms, update_workspace_last_used_at, and update_workspace_dormant_at are ignored templates.go:839, coderd/schedule/template.go:183-190,227 (AGPL store keeps stored values), enterprise/coderd/schedule/template.go:107-195 (only the enterprise store applies them), enterprise/coderd/coderd.go:1069 (FeatureAdvancedTemplateScheduling)
same Without a Premium license, require_active_version and a non-empty deprecation_message are ignored templates.go:811, dbauthz/accesscontrol.go:35-68, enterprise/coderd/coderd.go:1167 (FeatureAccessControl)
same Without a Premium license, setting max_port_share_level to anything other than public returns a validation error (the check is skipped when the value equals the unlicensed public level) templates.go:755-762, coderd/portsharing/portsharing.go:23, enterprise/coderd/coderd.go:1190 (FeatureControlSharedPorts)
DELETE /api/v2/templates/{template} Fails while non-prebuilt workspaces exist, and prebuilt workspaces are cleaned up afterward templates.go:100-111
same Needs permission to delete the template: same four roles dbauthz.go:1540 (SoftDeleteTemplateByID), roles.go:414,507,587,669
GET /api/v2/templates/{template} 404 if the template is deleted or unreadable httpmw/templateparam.go:34-37, dbauthz.go:5159
GET /api/v2/templates/{template}/daus Last 60 days of data, tz_offset query parameter with default 0 insights.go:52,62,67-68
same Needs permission to view the template's insights: Owner, Auditor, Template Admin, Organization Admin, Organization Auditor, Organization Template Admin dbauthz.go:1590,5174, roles.go:414,479,507,587,617,669, policy.go:17
GET /api/v2/organizations/{organization}/templates/{templatename} and the version lookups by name Template name matches case-insensitively queries/templates.sql:118
GET /api/v2/templates/{template}/versions/{templateversionname} and the organization variant Includes matched_provisioners while the import job is pending, and names are unique per template templateversions.go:1039,1125, templateversions.go:1813
GET /api/v2/templateversions/{templateversion} Includes matched_provisioners while the import job is pending templateversions.go:76-86
GET /api/v2/templates/{template}/versions Oldest first; archived excluded unless include_archived is true (default false) queries/templateversions.sql:37, templateversions.go:890,925
same limit, offset, after_id use the shared pagination wording templateversions.go:883, coderd/pagination.go:17-22
PATCH /api/v2/templates/{template}/versions Version must belong to the template, have built successfully, and not be archived templateversions.go:1472,1486,1493
same Needs permission to update the template: same four roles dbauthz.go:8667 (UpdateTemplateActiveVersionByID), roles.go:414,507,587,669
POST /api/v2/templates/{template}/versions/archive Default archives only failed versions, all archives every unused version, unused means not in a workspace's latest build and not the active version templateversions.go:1286, queries/templateversions.sql:155-212
same Needs permission to update the template: same four roles dbauthz.go:1898 (ArchiveUnusedTemplateVersions), roles.go:414,507,587,669
POST /api/v2/templateversions/{templateversion}/archive Fails when a workspace's latest build uses the version or it's the active version templateversions.go:1396, queries/templateversions.sql:155-212
POST /api/v2/templateversions/{templateversion}/archive and .../unarchive Needs permission to update the template: same four roles dbauthz.go:1898,7798, roles.go:414,507,587,669
PATCH /api/v2/templateversions/{templateversion} Renaming to a name another version uses returns an error; omitted name or message keeps its value templateversions.go:141-147,186
same Needs permission to update the template: same four roles dbauthz.go:8693 (UpdateTemplateVersionByID), roles.go:414,507,587,669
PATCH /api/v2/templateversions/{templateversion}/cancel Error if the job already completed or was canceled templateversions.go:254,260
same Needs permission to update the template: same four roles dbauthz.go:8553 (UpdateProvisionerJobWithCancelByID), roles.go:414,507,587,669
POST /api/v2/organizations/{organization}/templateversions Set file_id or example_id, not both templateversions.go:1586
same Needs permission to create templates in the organization: same four roles dbauthz.go:6881 (InsertTemplateVersion), roles.go:414,507,587,669
POST /api/v2/templateversions/{templateversion}/dry-run Plans the template without creating a workspace provisionerd/runner/runner.go:756-830
same 425 until the template version's import job has finished templateversions.go:553
same Needs permission to create workspaces in the organization: Owner, Organization Admin, Organization Workspace Access templateversions.go:533, roles.go:242,414,587,738
GET .../dry-run/{jobID} 403 if the job isn't a dry run of this template version templateversions.go:835,857
GET .../dry-run/{jobID}/resources 400 until the job completes provisionerjobs.go:215
PATCH .../dry-run/{jobID}/cancel 400 if already completed or canceled templateversions.go:765,771
same Needs permission to update workspaces owned by the user who started the dry run: Owner, Organization Admin templateversions.go:758, dbauthz.go:8595-8610, roles.go:414,587
GET .../dry-run/{jobID}/logs and GET /api/v2/templateversions/{templateversion}/logs follow upgrades to a WebSocket sending one JSON log per message and closes when the job ends; presence of the parameter enables it provisionerjobs.go:158,593,621,643
same after is a log ID; before is never read provisionerjobs.go:184-203,454,694
GET /api/v2/templateversions/{templateversion}/dynamic-parameters First message has id -1 and is computed with no inputs parameters.go:164-181
same Each request gets a reply with the same id; an omitted owner_id keeps the previous owner; user_id query sets the starting owner parameters.go:48-60,193-217
same Connection closes after 30 minutes parameters.go:141
POST .../dynamic-parameters/evaluate 425 until the import job has finished parameters.go:102
GET .../external-auth user_id for another user needs permission to create workspaces for that user templateversions.go:372
GET .../rich-parameters 425 until the import job has completed templateversions.go:312
GET .../variables 403 until the import job has completed, and sensitive value and default_value are *redacted* templateversions.go:493,2088-2098
GET .../resources 400 until the import job has completed, and the resources aren't tied to a workspace provisionerjobs.go:215, templateversions.go:1980-1986
GET .../presets Includes desired prebuild instances presets.go:58
GET .../parameters and GET .../schema Always return an empty array, replaced by rich-parameters deprecated.go:22,36, coderd.go:1660
GET /api/v2/organizations/{organization}/templates/examples Deprecated in favor of /api/v2/templates/examples templates.go:956
Writing rules applied
  • The first sentence starts with a verb and stands alone on the endpoint card.
  • Present tense, active voice, and "you" for the caller.
  • One sentence per @Description line, with no semicolons, em dashes, or en dashes.
  • Permission sentences name the built-in roles, traced through dbauthz and roles.go.
  • Premium license is named only where the handler delegates to a store that checks the entitlement.
  • Streams say when they upgrade to a WebSocket and what each message carries.
  • Removed routes say what they return now and name the replacement by full path.
  • Full API paths, and parameter names, fields, and literals in backticks.
  • Shared parameter wording copied exactly for organization, limit, offset, and after_id.
  • Body parameters say what the body is.

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 also replaces the thin or inaccurate parameter text on the same
routes.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

The dry-run cancel route also needs permission to update the template,
and the unlicensed port sharing check only rejects levels other than public.

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 Templates 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