Skip to content

docs: describe the AI Gateway API operations and parameters - #31527

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Adds a @Description to GET /api/v2/ai-gateway/providers, replaces the thin limit text on GET /api/v2/ai-gateway/sessions, and backticks a path in the existing GET /api/v2/ai-gateway/sessions/{session_id} description.
The REST API reference renders these routes from swagger.json, and the providers route showed only a title.

The other AI Gateway routes already have descriptions, so I left them alone.
The one edit to an existing description wraps /api/v2/aibridge/sessions/{session_id} in backticks, because raw braces break the MDX renderer and check_routes.py flags it.

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=1 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 (3 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 finding rejected by the verifier, so there is no follow-up commit.
Skeptic rejected 1 finding.
Rejected: a Copy Editor note on the relative "which" in the providers description, because the pronoun rule covers it, this, they, and that, and the referent is clear.

Claims checked against the code
Route Claim Evidence
GET /api/v2/ai-gateway/providers Premium license enterprise/coderd/coderd.go:317-326 (RequireFeatureMW(FeatureAIBridge))
GET /api/v2/ai-gateway/providers Requires read on AI Gateway interceptions, held by Owner and Auditor coderd/database/dbauthz/dbauthz.go:3115-3125, coderd/rbac/roles.go:421-432,499
GET /api/v2/ai-gateway/providers Returns name, type, display name, icon only, no configuration or secrets enterprise/coderd/aibridge.go:654-675, coderd/database/dbauthz/dbauthz.go:3116-3118
GET /api/v2/ai-gateway/sessions limit defaults to 100, maximum 1000 enterprise/coderd/aibridge.go:36-39,185-193
Writing rules applied
  • One to three present-tense sentences, first sentence starts with a verb and stands alone on the endpoint card.
  • Permission sentence names the check and the built-in roles, traced to dbauthz and roles.go.
  • "Requires a Premium license." only where the router uses RequireFeatureMW.
  • The handler's own limit default and maximum instead of the shared wording.
  • Full /api/v2 paths and backticks around field names and literals.
  • No em dashes, en dashes, semicolons, or raw braces and angle brackets outside backticks.
CI flakes unrelated to this change

test-go-pg (windows-2022) failed in TestAPISessionRecoveryWriteDeadline/message, which this PR doesn't touch: https://github.com/coder/coder/actions/runs/40925178654/job/123628850409

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 a description for the AI Gateway providers route and fuller text for the sessions limit parameter.

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