Skip to content

docs: describe the Audit API operations and parameters - #31552

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds a description for GET /api/v2/audit and improves its q, limit, and offset parameters.
The REST API reference renders these routes from swagger.json, and they had no description.

Merge notes

This PR doesn't touch the exemption lists from #31473.
If #31473 merges first, TestEndpointsDocumented names each route on this PR to remove from those lists.

Verification

summary: need=1 problems=0 thin_params_left=0
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.384s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	1.607s

A JSON diff of coderd/apidoc/swagger.json against origin/main changes only description values on the routes in this PR.

Claims checked against the code
Route Claim Evidence
GET /api/v2/audit Requires permission to read audit logs: Owner and Auditor site-wide, Organization Admin and Organization Auditor in their organization; otherwise 403 coderd/coderd.go:1508-1530, coderd/rbac/roles.go:422,484,601,626
GET /api/v2/audit Returns only the audit logs the caller can read (SQL filter), newest first coderd/database/dbauthz/dbauthz.go:3271-3285, coderd/database/queries/auditlogs.sql:108
GET /api/v2/audit Audit logs are recorded only while the deployment has a Premium license; the route itself isn't gated by RequireFeatureMW and the handler checks no entitlement enterprise/coderd/coderd.go:1031-1036, coderd/coderd.go:1508-1533
GET /api/v2/audit q keys, bare term as resource_type, lowercased, date_to inclusive through end of day, username:me, organization ID or name coderd/searchquery/search.go:38-89, 760-777, coderd/audit.go:60-75
GET /api/v2/audit limit default 0 returns 100 results; offset default 0 coderd/pagination.go:14-34, coderd/database/queries/auditlogs.sql:109-112
doc-check self-check

Ran in author self-check mode on the branch diff, annotation text only: Fact Checker, Continuity Editor, Copy Editor, and then the Skeptic.
The other personas didn't run because no Markdown page was written by hand, and docs/reference/api/ is generated.
Fact Checker: Found one wrong claim: the limit parameter said the default, 0, returns all results, but the query returns 100 results when limit is 0 (coderd/database/queries/auditlogs.sql:109-112).
Fixed in a follow-up commit.
Continuity Editor: No findings.
The q keys match coderd/searchquery/search.go:38-89.
Copy Editor: No findings after the fix above.
Skeptic: kept 1 and rejected 2.
One finding that limit is marked required but has a default, rejected because the required flag is an annotation bug outside this PR's scope.
One finding that the Premium sentence should say the route requires a license, rejected because the code gates only recording (enterprise/coderd/coderd.go:1031-1036), and the sentence says that.
No blocking findings remain.

Writing rules applied
  • One to three present-tense, active-voice sentences, addressed to "you", with the first sentence starting with a verb.
  • Permission sentences name the built-in roles by display name, each traced to coderd/rbac/roles.go and the handler or dbauthz check.
  • Premium license, experiment, and authentication sentences appear only where the code gates the route.
  • Streams say that the route upgrades to a WebSocket and what each message carries.
  • Full API paths and exact field names, parameter names, and values are in backticks.
  • Parameter text states what the value selects, its accepted forms, and its default and limits from the code.
  • Shared parameters (user, limit, offset) use the shared wording only where the handler matches it.
  • No em dashes, en dashes, spaced double hyphens, semicolons in prose, or raw angle brackets and braces outside backticks.
CI flakes unrelated to this change

test-go-pg (ubuntu-latest) failed two tests that this PR doesn't touch: https://github.com/coder/coder/actions/runs/40935636968/job/123665502865

  • TestChatTurnStopsAtStepLimit/Default in coderd/x/chatd.
  • TestServerTailnet_ReverseProxy_TCPDialFailure in coderd, a tailnet timing test that hit a 502 after about five seconds. This PR changes only annotation comments.

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.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

The limit parameter said the default of 0 returns all results, but the query returns 100 results when limit is 0.

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