Skip to content

docs: describe the AI governance API operations and parameters - #31542

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

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

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

This adds a @Description to the 13 Agent Firewall session, AI Gateway key and serve, and AI budget and spend routes in the Enterprise tag that had none, and improves the text of their parameters.
The REST API reference renders these routes from swagger.json, so their pages showed only a title.

I also fixed existing parameter text on routes in this list: Agent firewall session ID now uses the product name, and the organization and user path parameters now use the shared wording, because the handlers resolve names, default, and me.

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 10-enterprise-ai-governance.txt
summary: need=13 problems=0 thin_params_left=5

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

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

A JSON diff of swagger.json against origin/main shows 13 operation descriptions and 18 parameter descriptions changed, and nothing else.
The five remaining thin parameters are group path IDs that accept only a UUID, so Group ID is complete.

Claims checked against the code
Route Claim Evidence
GET /api/v2/agent-firewall/sessions/{id}, GET /api/v2/agent-firewall/sessions/{id}/logs Requires a Premium license enterprise/coderd/coderd.go:389-392 (RequireFeatureMW(FeatureBoundary))
Both Owner and Auditor can read Agent Firewall logs coderd/database/dbauthz/dbauthz.go:3323-3325, :7375-7377, enterprise/coderd/agentfirewall.go:72, coderd/rbac/roles.go:439 (Owner), :501 (Auditor)
GET .../sessions/{id} Response carries workspace ID, owner ID, confined process, start time enterprise/coderd/agentfirewall.go:45-51
GET .../sessions/{id}/logs Ascending sequence order, seq_after inclusive, seq_before exclusive, limit defaults to 100 coderd/database/queries/boundarylogs.sql:65-82
GET /api/v2/ai-gateway/keys Premium license; Owner only; oldest first; no secret returned enterprise/coderd/coderd.go:329-338, coderd/rbac/roles.go:422,432, coderd/database/dbauthz/dbauthz.go:7359-7364, coderd/database/queries/ai_gateway_keys.sql:6-9
POST /api/v2/ai-gateway/keys Premium license; Owner only; secret returned once enterprise/coderd/coderd.go:329-338, coderd/database/dbauthz/dbauthz.go:6433-6435, codersdk/aigatewaykeys.go:28-29
POST /api/v2/ai-gateway/keys Name rules (unique, 64 characters or fewer, lowercase letters, numbers, non-consecutive hyphens, no leading or trailing hyphen) enterprise/coderd/aigatewaykeys.go:21,94-107
DELETE /api/v2/ai-gateway/keys/{key} Premium license; Owner only enterprise/coderd/coderd.go:329-338, coderd/database/dbauthz/dbauthz.go:2198-2202, coderd/rbac/roles.go:432
DELETE /api/v2/ai-gateway/keys/{key} A connected replica is closed at its next heartbeat check, every 60 seconds enterprise/coderd/aibridgeserve.go:31,205-229
GET /api/v2/ai-gateway/serve WebSocket upgrade carrying DRPC services; key in X-Coder-AI-Governance-Gateway-Key header, no session token enterprise/coderd/aibridgeserve.go:49-55,109-150, codersdk/client.go:105-106, enterprise/coderd/coderd.go:343-348 (no apiKeyMiddleware)
GET /api/v2/ai-gateway/serve Premium license; closed when the entitlement is revoked or the key is deleted enterprise/coderd/coderd.go:343-348, enterprise/coderd/aibridgeserve.go:217-229
GET, PUT, DELETE /api/v2/groups/{group}/ai/budget Premium license enterprise/coderd/coderd.go:652-653,678-680
GET .../ai/budget, DELETE .../ai/budget 404 when the group has no budget enterprise/coderd/aibridge.go:710-713,830-833, coderd/database/queries/aicostcontrol.sql:180-183
GET .../ai/budget Requires read on the group; roles that can read groups coderd/database/dbauthz/dbauthz.go:4311-4320, coderd/rbac/roles.go:281-283,489,522,543,630,660,687
PUT, DELETE .../ai/budget Requires update on the group; Owner, User Admin, Organization Admin, Organization User Admin coderd/database/dbauthz/dbauthz.go:2452-2461,9693-9703, coderd/rbac/roles.go:422,543,589-610,660
PUT .../ai/budget, PUT .../budget/override spend_limit_micros is in millionths of a dollar, per member, 0 to 1000000000000 codersdk/aibridge.go:19-21, enterprise/coderd/aibridge.go:726-736, docs/ai-coder/ai-gateway/cost-controls.md:81
GET, PUT, DELETE /api/v2/users/{user}/ai/budget/override, GET /api/v2/users/{user}/ai/spend Premium license enterprise/coderd/coderd.go:725-729
GET .../budget/override, GET .../ai/spend Requires read on the user; readable for yourself; Owner, Auditor, Template Admin, User Admin, Organization Admin, Organization User Admin read all users coderd/database/dbauthz/dbauthz.go:5475-5480,5525-5530, coderd/rbac/roles.go:463,488,521,539,594,650
GET, DELETE .../budget/override 404 when the user has no override enterprise/coderd/aibridge.go:862-865,1004-1007
PUT, DELETE .../budget/override Requires update on the user and the group; Owner and User Admin coderd/database/dbauthz/dbauthz.go:2760-2783,9832-9850, coderd/rbac/roles.go:422,539-543
PUT .../budget/override User must be a member of group_id; system user returns 403 enterprise/coderd/aibridge.go:890-898,960-971
GET .../budget/override, PUT, DELETE The override takes precedence over group budgets coderd/aibridge/budget/budget.go:60-72
GET /api/v2/users/{user}/ai/spend Returns the budget period, effective group, effective budget, and current spend enterprise/coderd/aibridge.go:1067-1124, codersdk/aibridge.go:49-80
GET /api/v2/organizations/{organization}/ai/spend/export and the other organization path parameters Organization ID, name, or default enterprise/coderd/coderd.go:535-537,572-579, coderd/httpmw/organizationparam.go:69-84
GET .../ai/spend/export user_id, group_id, provider_name, model filter the rows; group_id matches the effective group coderd/database/queries/aicostcontrol.sql:594-597
doc-check self-check

Author self-check mode, run on the annotation text in the diff, with nothing posted to GitHub.
Personas that ran: Fact Checker, Consistency, Language, and Skeptic (verifier).
Personas skipped: Cartographer, Newcomer, Reader Advocate, and Architect, because no hand-written docs page or navigation changed, only annotation text and its generated output.
No blocking findings remain.
make lint/emdash passed, and the generated docs/reference/api/enterprise.md went through the markdownlint step of make gen.

Writing rules applied
  • One to three sentences in present tense, active voice, each starting with a verb, with the permission and license sentences added only where traced.
  • Product names from the glossary: AI Gateway, Agent Firewall, AI Governance.
  • "Requires a Premium license." only where the route sits behind RequireFeatureMW.
  • Role display names, and only roles traced through roles.go.
  • Authentication named for /api/v2/ai-gateway/serve, which uses an AI Gateway key and no session token.
  • Streams: the serve route says it upgrades to a WebSocket and what it carries.
  • Shared wording for the organization and user path parameters where the handler resolves names and me.
  • Body parameters say what the body is.
  • Literals, field names, and enum values in backticks, with full API paths.
  • No em dashes, en dashes, semicolons in prose, 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 describes the Agent Firewall session routes, the AI Gateway key and
serve routes, and the AI budget and spend routes, and improves their
parameter text.

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