Skip to content

docs: describe the Notifications API operations and parameters - #31500

Closed
nickvigilante wants to merge 3 commits into
mainfrom
vigilante/api-descriptions-notifications
Closed

nickvigilante wants to merge 3 commits into
mainfrom
vigilante/api-descriptions-notifications

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds descriptions for the 13 Notifications routes and improves 14 of their parameters.
The REST API reference renders these routes from swagger.json, and they had no description.
The inbox routes are for you, and the settings, templates, test, and dispatch routes are for administrators.

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=13 problems=0 thin_params_left=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.616s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.393s

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/notifications/settings Any authenticated user can read coderd/database/dbauthz/dbauthz.go:4575-4578 (no authz check)
PUT /api/v2/notifications/settings Requires permission to update deployment configuration, which the Owner role has coderd/database/dbauthz/dbauthz.go:9737-9741, coderd/rbac/roles.go:422
PUT /api/v2/notifications/settings Returns 304 when settings are unchanged coderd/notifications.go:96-99
GET /api/v2/notifications/templates/system, GET /api/v2/notifications/templates/custom Any authenticated user can read coderd/database/dbauthz/dbauthz.go:4565-4569
GET /api/v2/notifications/dispatch-methods Returns every defined method except inbox, not only configured ones, plus the default method coderd/notifications.go:177-194
POST /api/v2/notifications/test Requires permission to update deployment configuration, which the Owner role has; sends to the caller coderd/notifications.go:218-226, coderd/rbac/roles.go:422
GET /api/v2/users/{user}/notifications/preferences Owner can read any user's preferences, a user can read their own coderd/database/dbauthz/dbauthz.go:5701-5706, coderd/rbac/roles.go:422,458-459
PUT /api/v2/users/{user}/notifications/preferences Owner can update any user's preferences, a user can update their own coderd/database/dbauthz/dbauthz.go:8978-8983, coderd/rbac/roles.go:422,458-459
PUT /api/v2/users/{user}/notifications/preferences user accepts ID, username, or me coderd/coderd.go:1758, coderd/httpmw/userparam.go:51-62
PUT /api/v2/users/{user}/notifications/preferences Request body is template_disabled_map, template ID to disabled flag coderd/notifications.go:316-325, codersdk/notifications.go:214-216
POST /api/v2/notifications/custom System users can't send coderd/notifications.go:408-417
POST /api/v2/notifications/custom Title up to 120 and message up to 2000 bytes, both required codersdk/notifications.go:299-322
POST /api/v2/notifications/custom Sends to the caller coderd/notifications.go:418-422
GET /api/v2/notifications/inbox Returns up to 25 notifications, newest first coderd/database/queries/notificationsinbox.sql:12,28 (default limit 25, ORDER BY created_at DESC)
GET /api/v2/notifications/inbox read_status default all; values all, read, unread coderd/inboxnotifications.go:313-336
GET /api/v2/notifications/inbox targets must all match; starting_before unknown ID returns the first page coderd/database/queries/notificationsinbox.sql:25, coderd/inboxnotifications.go:343-349
GET /api/v2/notifications/inbox/watch Upgrades to a WebSocket; each message has notification and unread_count coderd/inboxnotifications.go:224, 281-284, codersdk/inboxnotification.go:37-40
GET /api/v2/notifications/inbox/watch format default markdown, plaintext converts title and content; filters targets (all must match), templates, read_status (default all) coderd/inboxnotifications.go:134-138, 176-215, 267-278
PUT /api/v2/notifications/inbox/{id}/read-status Body is_read; returns notification and unread_count codersdk/inboxnotification.go:91-99, coderd/inboxnotifications.go:431-456
PUT /api/v2/notifications/inbox/mark-all-as-read Marks only the caller's notifications coderd/inboxnotifications.go:483-486
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 delivery methods route said it lists the methods the deployment supports, but it returns every method Coder defines except inbox (coderd/notifications.go:177-194).
Fixed in a follow-up commit.
Continuity Editor: No findings.
Shared user wording matches the handler (httpmw.ExtractUserParam), and the Owner-role sentences use the same form on every route.
Copy Editor: No findings after the fix above.
The "disable" wording was already changed to "turn off" in the first follow-up commit.
Skeptic: kept 1 and rejected 2.
One nbsp-between-number-and-unit finding for "2000 bytes", rejected because Coder.UnitSpacing skips pages generated from Go source (word-choice and numbers-units-and-dates rule text).
One finding that "Use the query parameters to filter which notifications you receive" is redundant, rejected because no style rule cites it.
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 style guide prefers "turn off" over "disable" in product-facing prose.

Part of DOCS-1439.

Assisted-by: AI
The delivery methods route returns the methods Coder defines, not only the ones the deployment has configured, so the description no longer says it lists the methods the deployment supports.

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