Skip to content

docs: describe the AI Providers API operations and parameters - #31530

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Adds @Description text to the five AI provider routes that had none, and replaces the path and body parameter text on those routes.
The REST API reference renders these routes from swagger.json, so they showed only a title.

Merge notes

This PR doesn't touch the exemption lists in #31473.
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=5 problems=0 thin_params_left=0
$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest
$ make lint/emdash
OK: no emdash or endash characters found.

The swagger.json diff against origin/main changes only description values (10 changed, proven with a JSON walk that fails on any other change).

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 the survivors.
No blocking findings. One suggestion left as is (see below), so there is no follow-up commit.
Skeptic rejected 0 findings.
Left as a suggestion: POST /api/v2/ai/providers says providers of type bedrock don't accept api_keys, and the code also rejects them for any provider with Bedrock settings.

Claims checked against the code
Route Claim Evidence
all five routes No license or experiment gate, only a session token coderd/coderd.go:2138 (aiProvidersHandler(api, apiKeyMiddleware))
GET /api/v2/ai/providers, GET .../{idOrName} Requires read on AI providers, held by the Owner role coderd/database/dbauthz/dbauthz.go:3094-3113,3166-3171, coderd/rbac/roles.go:421-432 (no other built-in role lists ResourceAIProvider)
POST /api/v2/ai/providers Requires create on AI providers coderd/ai_providers.go:178, coderd/database/dbauthz/dbauthz.go:6440
PATCH .../{idOrName} Requires update on AI providers coderd/ai_providers.go:327, coderd/database/dbauthz/dbauthz.go:7863
DELETE .../{idOrName} Requires delete on AI providers coderd/database/dbauthz/dbauthz.go:2205
GET /api/v2/ai/providers Includes disabled providers, keys masked coderd/ai_providers.go:60-62, codersdk/aiproviders.go:264-270
GET /api/v2/ai/providers, .../{idOrName} Routing warnings in status coderd/ai_providers.go:100,144, codersdk/aiproviders.go:254-262
POST /api/v2/ai/providers Required fields and name format codersdk/aiproviders.go:22-25,292-314,465-477,549-570
POST /api/v2/ai/providers bedrock type rejects api_keys codersdk/aiproviders.go:327-332, coderd/ai_providers.go:196-203
POST /api/v2/ai/providers 409 on a duplicate name coderd/ai_providers.go:257
PATCH .../{idOrName} Empty patch rejected, unsent fields stay coderd/ai_providers.go:337, codersdk/aiproviders.go:462
PATCH .../{idOrName} api_keys is the full post-patch set, existing by id, new by api_key, others removed codersdk/aiproviders.go:371-394
DELETE .../{idOrName} enabled disables without deleting coderd/ai_providers.go:430, codersdk/aiproviders.go:377
{idOrName} UUID or name matching the name pattern coderd/ai_providers.go:603-618
Coder Agents and AI Gateway use the providers Subscribers refetch on change coderd/ai_providers.go:573-580
Writing rules applied
  • One to three present-tense sentences, first sentence starts with a verb and stands alone on the endpoint card.
  • Permission sentences name the check and the built-in role, traced to dbauthz and roles.go.
  • No license sentence, because none of these routes sits behind a feature gate.
  • Product names: Coder Agents and AI Gateway.
  • Body parameters say what the body is, not the request type name.
  • Backticks around field names, enum values, and literals.
  • No em dashes, en dashes, semicolons, or raw braces and angle brackets 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 descriptions and fuller parameter text for the five AI provider routes.

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 AI Providers 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