Skip to content

docs: describe the InitScript API operations and parameters - #31526

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes GET /api/v2/init-script/{os}/{arch} and gives its os and arch path parameters their accepted values, 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	2.720s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.667s
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 Coder Terraform provider claim is cross-repo, but provisionersdk/agent.go:42-44 supports it.
Claims checked against the code
Route Claim Evidence
GET /api/v2/init-script/{os}/{arch} Doesn't require a session token coderd/coderd.go:2135-2137 (no auth middleware), coderd/coderdtest/swaggerparser.go:372 (assertSecurityDefined exempts it)
GET /api/v2/init-script/{os}/{arch} Access URL is filled in and token authentication is selected coderd/initscript.go:39-40
GET /api/v2/init-script/{os}/{arch} 400 for an unsupported pair, and the match ignores case coderd/initscript.go:29-37
os and arch path parameters Supported values are linux, darwin, windows, and amd64, arm64, plus armv7 on linux only provisionersdk/agent.go:25-39
GET /api/v2/init-script/{os}/{arch} The Coder Terraform provider builds the init_script of a coder_agent from the same script provisionersdk/agent.go:42-44 (AgentScriptEnv is documented as consumed by the Coder Terraform provider, which performs additional substitutions)
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.

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

@nickvigilante The prepare-linkspector-browser job failed after about 1h2m with no log available (job). It looks like a runner or setup timeout, since lint-docs passed on the same commit, but the link checker runs on docs/reference/api/, which this PR regenerates. I didn't rerun it.

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

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