opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-21 20:51:01 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
fe4a73f8ab1b784e8af6f197c20122d7993270bc
coder/docs/reference/api/notifications.md
T
Nick Vigilante c84aa564ba docs: normalize code-fence languages for Shiki compatibility (#27161) 
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.

## Changes

- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags

`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).

Does not touch `offlinedocs/`.

Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)

<details>
<summary>How the fence tags were verified</summary>

Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:

```text
FAIL  env        -- Language `env` is not included in this bundle.
FAIL  Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL  promql     -- Language `promql` is not included in this bundle.
FAIL  caddyfile  -- Language `caddyfile` is not included in this bundle.
FAIL  pwsh       -- Language `pwsh` is not included in this bundle.
FAIL  output     -- Language `output` is not included in this bundle.
```

`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.

For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.

The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.

</details>


---

*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
2026-07-15 14:07:09 -04:00

23 KiB
Generated
Raw Blame History

Notifications

Send a custom notification

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/notifications/custom \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/notifications/custom

Body parameter

{
  "content": {
    "message": "string",
    "title": "string"
  }
}

Parameters

Name In Type Required Description
body body codersdk.CustomNotificationRequest true Provide a non-empty title or message

Example responses

400 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
204 No Content No Content
400 Bad Request Invalid request body codersdk.Response
403 Forbidden System users cannot send custom notifications codersdk.Response
500 Internal Server Error Failed to send custom notification codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get notification dispatch methods

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/dispatch-methods \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/notifications/dispatch-methods

Example responses

200 Response

[
  {
    "available": [
      "string"
    ],
    "default": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.NotificationMethodsResponse

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» available array false
» default string false

To perform this operation, you must be authenticated. Learn more.

List inbox notifications

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/inbox \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/notifications/inbox

Parameters

Name In Type Required Description
targets query string false Comma-separated list of target IDs to filter notifications
templates query string false Comma-separated list of template IDs to filter notifications
read_status query string false Filter notifications by read status. Possible values: read, unread, all
starting_before query string(uuid) false ID of the last notification from the current page. Notifications returned will be older than the associated one

Example responses

200 Response

{
  "notifications": [
    {
      "actions": [
        {
          "label": "string",
          "url": "string"
        }
      ],
      "content": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "read_at": "string",
      "targets": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
      "title": "string",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
    }
  ],
  "unread_count": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ListInboxNotificationsResponse

To perform this operation, you must be authenticated. Learn more.

Mark all unread notifications as read

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/inbox/mark-all-as-read \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/notifications/inbox/mark-all-as-read

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Watch for new inbox notifications

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/inbox/watch \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/notifications/inbox/watch

Parameters

Name In Type Required Description
targets query string false Comma-separated list of target IDs to filter notifications
templates query string false Comma-separated list of template IDs to filter notifications
read_status query string false Filter notifications by read status. Possible values: read, unread, all
format query string false Define the output format for notifications title and body.

Enumerated Values

Parameter Value(s)
format markdown, plaintext

Example responses

200 Response

{
  "notification": {
    "actions": [
      {
        "label": "string",
        "url": "string"
      }
    ],
    "content": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "read_at": "string",
    "targets": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
    "title": "string",
    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
  },
  "unread_count": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GetInboxNotificationResponse

To perform this operation, you must be authenticated. Learn more.

Update read status of a notification

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/inbox/{id}/read-status \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/notifications/inbox/{id}/read-status

Parameters

Name In Type Required Description
id path string true id of the notification

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get notifications settings

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/settings \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/notifications/settings

Example responses

200 Response

{
  "notifier_paused": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.NotificationsSettings

To perform this operation, you must be authenticated. Learn more.

Update notifications settings

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/settings \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/notifications/settings

Body parameter

{
  "notifier_paused": true
}

Parameters

Name In Type Required Description
body body codersdk.NotificationsSettings true Notifications settings request

Example responses

200 Response

{
  "notifier_paused": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.NotificationsSettings
304 Not Modified Not Modified

To perform this operation, you must be authenticated. Learn more.

Get custom notification templates

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/templates/custom \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/notifications/templates/custom

Example responses

200 Response

[
  {
    "actions": "string",
    "body_template": "string",
    "enabled_by_default": true,
    "group": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "kind": "string",
    "method": "string",
    "name": "string",
    "title_template": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.NotificationTemplate
500 Internal Server Error Failed to retrieve 'custom' notifications template codersdk.Response

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» actions string false
» body_template string false
» enabled_by_default boolean false
» group string false
» id string(uuid) false
» kind string false
» method string false
» name string false
» title_template string false

To perform this operation, you must be authenticated. Learn more.

Get system notification templates

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/templates/system \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/notifications/templates/system

Example responses

200 Response

[
  {
    "actions": "string",
    "body_template": "string",
    "enabled_by_default": true,
    "group": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "kind": "string",
    "method": "string",
    "name": "string",
    "title_template": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.NotificationTemplate
500 Internal Server Error Failed to retrieve 'system' notifications template codersdk.Response

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» actions string false
» body_template string false
» enabled_by_default boolean false
» group string false
» id string(uuid) false
» kind string false
» method string false
» name string false
» title_template string false

To perform this operation, you must be authenticated. Learn more.

Send a test notification

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/notifications/test \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/notifications/test

Responses

Status Meaning Description Schema
200 OK OK

To perform this operation, you must be authenticated. Learn more.

Get user notification preferences

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/notifications/preferences \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/{user}/notifications/preferences

Parameters

Name In Type Required Description
user path string true User ID, name, or me

Example responses

200 Response

[
  {
    "disabled": true,
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.NotificationPreference

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» disabled boolean false
» id string(uuid) false
» updated_at string(date-time) false

To perform this operation, you must be authenticated. Learn more.

Update user notification preferences

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/users/{user}/notifications/preferences \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/users/{user}/notifications/preferences

Body parameter

{
  "template_disabled_map": {
    "property1": true,
    "property2": true
  }
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.UpdateUserNotificationPreferences true Preferences

Example responses

200 Response

[
  {
    "disabled": true,
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.NotificationPreference

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» disabled boolean false
» id string(uuid) false
» updated_at string(date-time) false

To perform this operation, you must be authenticated. Learn more.

Reference in New Issue View Git Blame Copy Permalink