Coder Notifications API
The Notifications API from Coder — 13 operation(s) for notifications.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/coder:coder-notifications-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
description: Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
title: Coder Notifications API
termsOfService: https://coder.com/legal/terms-of-service
contact:
name: API Support
url: https://coder.com
email: support@coder.com
license:
name: AGPL-3.0
url: https://github.com/coder/coder/blob/main/LICENSE
version: '2.0'
servers:
- url: /
tags:
- name: Notifications
paths:
/api/v2/notifications/custom:
post:
tags:
- Notifications
summary: Send a custom notification
operationId: send-a-custom-notification
responses:
'204':
description: No Content
'400':
description: Invalid request body
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
'403':
description: System users cannot send custom notifications
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
'500':
description: Failed to send custom notification
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
security:
- CoderSessionToken: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.CustomNotificationRequest'
description: Provide a non-empty title or message
required: true
/api/v2/notifications/dispatch-methods:
get:
tags:
- Notifications
summary: Get notification dispatch methods
operationId: get-notification-dispatch-methods
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/codersdk.NotificationMethodsResponse'
security:
- CoderSessionToken: []
/api/v2/notifications/inbox:
get:
tags:
- Notifications
summary: List inbox notifications
operationId: list-inbox-notifications
parameters:
- description: Comma-separated list of target IDs to filter notifications
name: targets
in: query
schema:
type: string
- description: Comma-separated list of template IDs to filter notifications
name: templates
in: query
schema:
type: string
- description: 'Filter notifications by read status. Possible values: read, unread, all'
name: read_status
in: query
schema:
type: string
- description: ID of the last notification from the current page. Notifications returned will be older than the associated one
name: starting_before
in: query
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.ListInboxNotificationsResponse'
security:
- CoderSessionToken: []
/api/v2/notifications/inbox/mark-all-as-read:
put:
tags:
- Notifications
summary: Mark all unread notifications as read
operationId: mark-all-unread-notifications-as-read
responses:
'204':
description: No Content
security:
- CoderSessionToken: []
/api/v2/notifications/inbox/watch:
get:
tags:
- Notifications
summary: Watch for new inbox notifications
operationId: watch-for-new-inbox-notifications
parameters:
- description: Comma-separated list of target IDs to filter notifications
name: targets
in: query
schema:
type: string
- description: Comma-separated list of template IDs to filter notifications
name: templates
in: query
schema:
type: string
- description: 'Filter notifications by read status. Possible values: read, unread, all'
name: read_status
in: query
schema:
type: string
- description: Define the output format for notifications title and body.
name: format
in: query
schema:
type: string
enum:
- plaintext
- markdown
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.GetInboxNotificationResponse'
security:
- CoderSessionToken: []
/api/v2/notifications/inbox/{id}/read-status:
put:
tags:
- Notifications
summary: Update read status of a notification
operationId: update-read-status-of-a-notification
parameters:
- description: id of the notification
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
security:
- CoderSessionToken: []
/api/v2/notifications/settings:
get:
tags:
- Notifications
summary: Get notifications settings
operationId: get-notifications-settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.NotificationsSettings'
security:
- CoderSessionToken: []
put:
tags:
- Notifications
summary: Update notifications settings
operationId: update-notifications-settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.NotificationsSettings'
'304':
description: Not Modified
security:
- CoderSessionToken: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.NotificationsSettings'
description: Notifications settings request
required: true
/api/v2/notifications/templates/custom:
get:
tags:
- Notifications
summary: Get custom notification templates
operationId: get-custom-notification-templates
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/codersdk.NotificationTemplate'
'500':
description: Failed to retrieve 'custom' notifications template
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
security:
- CoderSessionToken: []
/api/v2/notifications/templates/system:
get:
tags:
- Notifications
summary: Get system notification templates
operationId: get-system-notification-templates
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/codersdk.NotificationTemplate'
'500':
description: Failed to retrieve 'system' notifications template
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.Response'
security:
- CoderSessionToken: []
/api/v2/notifications/test:
post:
tags:
- Notifications
summary: Send a test notification
operationId: send-a-test-notification
responses:
'200':
description: OK
security:
- CoderSessionToken: []
/api/v2/users/{user}/notifications/preferences:
get:
tags:
- Notifications
summary: Get user notification preferences
operationId: get-user-notification-preferences
parameters:
- description: User ID, name, or me
name: user
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/codersdk.NotificationPreference'
security:
- CoderSessionToken: []
put:
tags:
- Notifications
summary: Update user notification preferences
operationId: update-user-notification-preferences
parameters:
- description: User ID, name, or me
name: user
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/codersdk.NotificationPreference'
security:
- CoderSessionToken: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.UpdateUserNotificationPreferences'
description: Preferences
required: true
/api/v2/users/{user}/webpush/subscription:
post:
tags:
- Notifications
summary: Create user webpush subscription
operationId: create-user-webpush-subscription
parameters:
- description: User ID, name, or me
name: user
in: path
required: true
schema:
type: string
responses:
'204':
description: No Content
security:
- CoderSessionToken: []
x-apidocgen:
skip: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.WebpushSubscription'
description: Webpush subscription
required: true
delete:
tags:
- Notifications
summary: Delete user webpush subscription
operationId: delete-user-webpush-subscription
parameters:
- description: User ID, name, or me
name: user
in: path
required: true
schema:
type: string
responses:
'204':
description: No Content
security:
- CoderSessionToken: []
x-apidocgen:
skip: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/codersdk.DeleteWebpushSubscription'
description: Webpush subscription
required: true
/api/v2/users/{user}/webpush/test:
post:
tags:
- Notifications
summary: Send a test push notification
operationId: send-a-test-push-notification
parameters:
- description: User ID, name, or me
name: user
in: path
required: true
schema:
type: string
responses:
'204':
description: No Content
security:
- CoderSessionToken: []
x-apidocgen:
skip: true
components:
schemas:
codersdk.CustomNotificationContent:
type: object
properties:
message:
type: string
title:
type: string
codersdk.GetInboxNotificationResponse:
type: object
properties:
notification:
$ref: '#/components/schemas/codersdk.InboxNotification'
unread_count:
type: integer
codersdk.ListInboxNotificationsResponse:
type: object
properties:
notifications:
type: array
items:
$ref: '#/components/schemas/codersdk.InboxNotification'
unread_count:
type: integer
codersdk.DeleteWebpushSubscription:
type: object
properties:
endpoint:
type: string
codersdk.NotificationMethodsResponse:
type: object
properties:
available:
type: array
items:
type: string
default:
type: string
codersdk.UpdateUserNotificationPreferences:
type: object
properties:
template_disabled_map:
type: object
additionalProperties:
type: boolean
codersdk.InboxNotificationAction:
type: object
properties:
label:
type: string
url:
type: string
codersdk.NotificationTemplate:
type: object
properties:
actions:
type: string
body_template:
type: string
enabled_by_default:
type: boolean
group:
type: string
id:
type: string
format: uuid
kind:
type: string
method:
type: string
name:
type: string
title_template:
type: string
codersdk.InboxNotification:
type: object
properties:
actions:
type: array
items:
$ref: '#/components/schemas/codersdk.InboxNotificationAction'
content:
type: string
created_at:
type: string
format: date-time
icon:
type: string
id:
type: string
format: uuid
read_at:
type: string
targets:
type: array
items:
type: string
format: uuid
template_id:
type: string
format: uuid
title:
type: string
user_id:
type: string
format: uuid
codersdk.WebpushSubscription:
type: object
properties:
auth_key:
type: string
endpoint:
type: string
p256dh_key:
type: string
codersdk.CustomNotificationRequest:
type: object
properties:
content:
$ref: '#/components/schemas/codersdk.CustomNotificationContent'
codersdk.NotificationsSettings:
type: object
properties:
notifier_paused:
type: boolean
codersdk.Response:
type: object
properties:
detail:
description: 'Detail is a debug message that provides further insight into why the
action failed. This information can be technical and a regular golang
err.Error() text.
- "database: too many open connections"
- "stat: too many open files"'
type: string
message:
description: 'Message is an actionable message that depicts actions the request took.
These messages should be fully formed sentences with proper punctuation.
Examples:
- "A user has been created."
- "Failed to create a user."'
type: string
validations:
description: 'Validations are form field-specific friendly error messages. They will be
shown on a form field in the UI. These can also be used to add additional
context if there is a set of errors in the primary ''Message''.'
type: array
items:
$ref: '#/components/schemas/codersdk.ValidationError'
codersdk.NotificationPreference:
type: object
properties:
disabled:
type: boolean
id:
type: string
format: uuid
updated_at:
type: string
format: date-time
codersdk.ValidationError:
type: object
required:
- detail
- field
properties:
detail:
type: string
field:
type: string
securitySchemes:
AIGatewayKey:
type: apiKey
name: X-AI-Governance-Gateway-Key
in: header
Authorization:
type: apiKey
name: Authorization
in: header
CoderSessionToken:
type: apiKey
name: Coder-Session-Token
in: header
x-provenance:
method: harvested
publisher: Coder
source: https://raw.githubusercontent.com/coder/coder/main/coderd/apidoc/swagger.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)