Skip to content

docs: describe the Agents API operations and parameters - #31536

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes 23 Agents API routes and improves 22 parameters, so the REST API reference page for each route has more than a title.
The reference renders from swagger.json, and these routes had no description.
The tag is the workspace agent API, so each description names the credential the route takes and which side calls it.

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>
THIN     DELETE /api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer} workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent} workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/connection workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/containers workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/containers/watch workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/coordinate workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/listening-ports workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/logs workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/pty workspaceagent (path): "Workspace agent ID"
THIN     GET /api/v2/workspaceagents/{workspaceagent}/startup-logs workspaceagent (path): "Workspace agent ID"
THIN     POST /api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}/recreate workspaceagent (path): "Workspace agent ID"
summary: need=23 problems=0 thin_params_left=11
$ 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	1.119s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.609s
OK: no emdash or endash characters found.

A JSON diff of swagger.json against origin/main changes only description values: 45 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.

  • Fixed, Fact Checker: the 9 {workspaceagent} routes and connection also accept a workspace proxy token in the Coder-External-Proxy-Token header, and the text now says so (coderd/coderd.go:1865-1878, coderd/httpmw/actor.go:15-36, coderd/httpmw/workspaceproxy.go:28).
  • Fixed, Fact Checker: GET /api/v2/workspaceagents/me/reinit said wait=true returns 409 whenever the workspace isn't a prebuild waiting to be claimed, but a just-claimed workspace gets an event instead. The text now lists the 409 cases (coderd/workspaceagents.go:1719, :1765, :1776, :1805).
  • Fixed, Continuity Editor: external auth provider in four parameters now reads external authentication provider, matching the glossary and the route text.
  • Fixed, Copy Editor: a Azure and a AWS are now an Azure and an AWS.
  • Fixed, Copy Editor: New code uses, older, and current are now Use ... instead, legacy, and other (voice and tone, describe conditions, not moments in time).
  • Fixed: reinit, coordinate, and listening-ports went over three sentences, so each is back to three.
  • Skeptic rejected 3: a non-breaking space in 1 MiB (the rule skips the API reference), workspace agent token against agent token elsewhere in the docs (no glossary entry), and sentences over 25 words (targets, not ceilings).

The workspaceagent path parameter stays Workspace agent ID on the 11 routes that take it, because the middleware accepts only a UUID (coderd/httpmw/workspaceagentparam.go, ParseUUIDParam).

Claims checked against the code
Route Claim Evidence
GET /api/v2/derp-map Doesn't require a session token coderd/coderd.go:1483 (route has no auth middleware, only the /api/v2 rate limiter and CLI telemetry)
GET /api/v2/derp-map Upgrades to a WebSocket, sends the map on connect and again when it changes coderd/workspaceagents.go:1265 (websocket.Accept), :1309 (CompareDERPMaps)
GET /api/v2/tailnet Upgrades to a WebSocket for a user-scoped tailnet connection to any workspace the user can SSH to coderd/workspaceagents.go:2583 (AuthorizeSQLFilter with ActionSSH), :2597 (websocket.Accept), coderd/coderd.go:2131 (apiKeyMiddleware)
GET /api/v2/tailnet, GET /api/v2/workspaceagents/{workspaceagent}/coordinate Returns 409 when the deployment turns on browser-only connections coderd/workspaceagents.go:1364, :2553 (override), enterprise/coderd/workspaceagents.go:18-22
GET /api/v2/tailnet Coder Desktop uses it coderd/workspaceagents.go:2625 (fillCoderDesktopTelemetry reads the Coder Desktop header on this route)
POST /api/v2/workspaceagents/{aws,azure,google}-instance-identity Doesn't require a session token and exchanges a signed instance identity for the agent token coderd/coderd.go:1832-1836 (registered before any auth middleware), coderd/workspaceresourceauth.go:220 (handleAuthInstanceID returns SessionToken)
POST /api/v2/workspaceagents/{aws,azure,google}-instance-identity The instance must belong to the workspace's latest build coderd/workspaceresourceauth.go:204-216
PATCH /api/v2/workspaceagents/me/app-status Takes the workspace agent token, and older agents call it while current agents use UpdateAppStatus on the Agent API coderd/coderd.go:1143, :1845 (workspaceAgentInfo is ExtractWorkspaceAgentAndLatestBuild), coderd/workspaceagents.go (@Deprecated annotation and the back-compat comment in patchWorkspaceAgentAppStatus)
PATCH /api/v2/workspaceagents/me/app-status state values working, idle, complete, failure codersdk/workspaceapps.go:21-24
GET /api/v2/workspaceagents/me/external-auth Takes the workspace agent token coderd/coderd.go:1844-1845, :1857
GET /api/v2/workspaceagents/me/external-auth Pass match or id, not both, and listen is presence-based coderd/workspaceagents.go:2162-2179 (400 when both or neither, query.Has("listen"))
GET /api/v2/workspaceagents/me/external-auth Returns a login URL when the owner hasn't linked the provider, and waits for a valid token with listen coderd/workspaceagents.go:2350, :2369 (login URL response), :2457-2460 (workspaceAgentsExternalAuthListen polls)
GET /api/v2/workspaceagents/me/external-auth Used for Git credentials and coder external-auth access-token coderd/workspaceagents.go:2231, :2245 (error text names coder gitaskpass and coder external-auth access-token)
GET /api/v2/workspaceagents/me/gitauth Same handler as external-auth, kept for legacy agents coderd/deprecated.go (workspaceAgentsGitAuth calls workspaceAgentsExternalAuth), coderd/coderd.go (// Deprecated: Required to support legacy agents)
GET /api/v2/workspaceagents/me/gitsshkey Returns the private key too, and takes the agent token codersdk/agentsdk/agentsdk.go:70-73 (PrivateKey), coderd/gitsshkey.go:121
POST /api/v2/workspaceagents/me/log-source Registering an existing id doesn't create another source coderd/workspaceagents.go:1621-1630 (unique violation returns the existing source)
PATCH /api/v2/workspaceagents/me/logs 1 MiB log limit per agent, 413 when exceeded coderd/database/dump.sql:4092 (max_logs_length on workspace_agents), coderd/workspaceagents.go:236
PATCH /api/v2/workspaceagents/me/logs level defaults to info coderd/workspaceagents.go:205
GET /api/v2/workspaceagents/me/reinit Server-sent events carrying workspace_id, reason, owner_id coderd/workspaceagents.go:1810 (NewSSEAgentReinitTransmitter), codersdk/agentsdk/agentsdk.go:865-869
GET /api/v2/workspaceagents/me/reinit With wait=true, an immediate event when the claim build succeeded, and 409 when the workspace wasn't a prebuild, the claim build failed, or a later build replaced the claim build coderd/workspaceagents.go:1707 (wait), :1719 (not a prebuild), :1765 (seeded event), :1776 (claim build failed), :1805 (later build)
The 9 {workspaceagent} routes (not pty) Also accept a workspace proxy token in the Coder-External-Proxy-Token header, instead of a session token coderd/coderd.go:1865-1878 (apiKeyMiddlewareOptional, ExtractWorkspaceProxy, RequireAPIKeyOrWorkspaceProxyAuth), coderd/httpmw/workspaceproxy.go:28, coderd/httpmw/actor.go:15-36
GET /api/v2/workspaceagents/{workspaceagent} and the other {workspaceagent} routes You must be able to read the workspace coderd/coderd.go:1874 (ExtractWorkspaceAgentAndWorkspaceParam), coderd/database/dbauthz/dbauthz.go:5824 (GetWorkspaceAgentAndWorkspaceByID uses fetch, which authorizes ActionRead)
GET /api/v2/workspaceagents/{workspaceagent}/connection Returns the DERP map and the workspace hostname suffix coderd/workspaceagents.go:1216-1224, codersdk/workspacesdk/workspacesdk.go:156-161
GET /api/v2/workspaceagents/{workspaceagent}/containers 400 unless the agent is connected, labels filter containers and not dev containers coderd/workspaceagents.go:977, :1016
GET /api/v2/workspaceagents/{workspaceagent}/containers Repeating label requires all labels (key=value) coderd/workspaceagents.go:937-952, coderd/util/maps/maps.go:22-31 (Subset)
DELETE .../containers/devcontainers/{devcontainer} Requires permission to update the workspace, 409 while transitioning, stops and removes the container and deletes the sub-agent if any coderd/workspaceagents.go:1036, agent/agentcontainers/api.go:1277, :1296, :1307, :1333, :1354, codersdk/workspaceagents.go:481-489
POST .../containers/devcontainers/{devcontainer}/recreate Requires permission to update the workspace, returns 202, 409 while transitioning coderd/workspaceagents.go:1128, :1203, agent/agentcontainers/api.go:1408, :1427
{devcontainer} path parameter ID comes from id in devcontainers of the list response agent/agentcontainers/api.go:1239-1244 (lookup by knownDC.ID), codersdk/workspaceagents.go:494-495
GET .../containers/watch WebSocket of JSON messages with the list response shape, 400 unless connected coderd/workspaceagents.go:853, :878, :894, :914
GET .../coordinate Requires permission to SSH to the workspace, upgrades to a WebSocket coderd/workspaceagents.go:1357, :1398
GET .../listening-ports 400 unless connected, TCP only, omits ports below 9, app ports, and ignored ports coderd/workspaceagents.go:733, :797-806, codersdk/workspacesdk/workspacesdk.go:60, codersdk/workspaceagents.go:447-451
GET .../logs follow, no_compression are presence-based, after is an integer of 0 or more, before is unused, format is json or text and text isn't supported with follow coderd/workspaceagents.go:407-409 (follow, no_compression), :410-440 (format, after), no read of before in the handler
GET .../logs With follow, each WebSocket message is a JSON array of log entries coderd/workspaceagents.go:525-528
GET .../pty Requires permission to SSH, upgrades to a WebSocket, reconnect UUID required, height and width default 80, optional command, container, container_user, backend_type coderd/workspaceapps/db.go:360-361, coderd/workspaceapps/proxy.go:785-790, :844
GET .../startup-logs Same handler as logs, kept for older clients coderd/deprecated.go (workspaceAgentLogsDeprecated calls workspaceAgentLogs)
/api/v2/workspaceagents/me/* routes Authenticate with the workspace agent token coderd/httpmw/workspaceagent.go:59-60 (ExtractWorkspaceAgentAndLatestBuild requires a valid agent token), coderd/coderd.go:1845
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.
Annotation bugs noticed, not changed here
  • The three *-instance-identity routes and GET /api/v2/derp-map list @Security CoderSessionToken, but their handlers need no session token.
  • GET /api/v2/workspaceagents/me/external-auth and /me/gitauth mark match and id as required, but the handler needs exactly one of them.
  • GET /api/v2/workspaceagents/{workspaceagent}/containers marks label as required, but the handler treats it as optional.
  • GET /api/v2/workspaceagents/{workspaceagent}/logs and /startup-logs document before, which the handler never reads, and startup-logs omits format.
  • POST /api/v2/workspaceagents/me/log-source documents 200, but the handler returns 201.
  • GET /api/v2/workspaceagents/{workspaceagent}/coordinate, /api/v2/tailnet, and /pty accept query parameters (version, reconnect, height, and others) that have no @Param, so their descriptions state them instead.
  • GET /api/v2/workspaceagents/{workspaceagent}/containers/watch documents a JSON response, but the route upgrades to a WebSocket.
CI flakes unrelated to this change

test-go-pg (windows-2022) failed TestAPISessionRecoveryWriteDeadline/message in agent/x/agentacp, a package this PR doesn't touch: https://github.com/coder/coder/actions/runs/40938193914/job/123674569767

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

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