Skip to content

docs: describe the Insights API operations and parameters - #31547

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

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

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds descriptions for the 5 Insights routes and improves 13 of their 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=5 problems=0 thin_params_left=0
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.461s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.405s

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/insights/daus Requires permission to read deployment configuration, which the Owner and Auditor roles have coderd/insights.go:42, coderd/rbac/roles.go:422,495
GET /api/v2/insights/daus Always returns 60 days, one entry per day, using tz_offset hours from UTC (default 0) coderd/insights.go:55,65-71, codersdk/insights.go:300
GET /api/v2/insights/daus, user-activity, user-latency, templates Returns 404 when usage stats collection is turned off coderd/coderd.go:1976-1986
GET /api/v2/insights/user-activity, user-latency, templates Requires permission to view template insights, which the Owner, Auditor, and Template Admin roles have coderd/database/dbauthz/dbauthz.go:1590-1611, 5532-5552, 5658-5680, coderd/rbac/roles.go:422,487,512-513
GET /api/v2/insights/user-status-counts Requires permission to read users, which the Owner, Auditor, Template Admin, and User Admin roles have coderd/database/dbauthz/dbauthz.go:5760-5765, coderd/rbac/roles.go:422,488,521,539
GET /api/v2/insights/user-status-counts Covers the last 60 days; timezone and tz_offset can't be combined; default UTC coderd/insights.go:323-362
user-activity, user-latency, templates start_time must be 00:00:00 and neither time can be later than the end of the current hour; end_time must be 00:00:00 unless it falls on the current day, when it must be on the hour; end_time isn't before start_time coderd/insights.go:658-760
GET /api/v2/insights/templates interval is day or week; week needs the last period to span at least 6 days; omitted means no interval_reports coderd/insights.go:759-786, 453-470 (interval reports only when interval is set)
user-activity, user-latency, templates Time params are RFC 3339; template_ids is a comma-separated UUID list with no default restriction coderd/insights.go:129,235,428, 658-670
GET /api/v2/insights/user-latency P50 and P95 connection latency in milliseconds coderd/insights.go:263-266, codersdk/insights.go (ConnectionLatency)
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: No findings.
The 60-day windows, time parameter limits, interval rules, and 404 on disabled usage stats match coderd/insights.go and coderd/coderd.go:1976-1986.
Continuity Editor: No findings.
The three time parameters share one wording on each route.
Copy Editor: Found one rule-anchored finding: the timezone and tz_offset parameters said "Don't combine it with ...", an imperative negation (voice-and-tone.md#spell-out-negative-instructions, enforced by Coder.ImperativeNegation).
Both now say "Do not combine", in a follow-up commit.
Skeptic: kept 1 and rejected 3.
One finding that interval is described as optional but marked required, rejected because the text is true in the code and the required flag is an annotation bug outside this PR's scope.
One finding that organization roles are missing from the permission sentences, rejected because they pass only for templates in their own organization and the sentences don't claim to be exhaustive.
One nbsp finding, rejected because Coder.UnitSpacing skips generated API pages.
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.

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 timezone and tz_offset parameters now tell the reader not to combine them with an imperative that spells out the negation, as the style guide requires.

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