Reference

REST API notification groups

Manage routing groups and their channel membership from code.

curl https://api.drumbeats.io/v1/notification-groups \
  -H "X-API-Key: dk_live_<key>"

curl https://api.drumbeats.io/v1/notification-groups \
  -H "X-API-Key: dk_live_<key>"

A group is a named bundle of channels. Monitors point at groups, so changing where alerts land is one edit rather than one per monitor. When a group is paged, every channel in it fires in parallel.

Any key can read. Writes need an account-scoped key with manage_notifications. A project-scoped key is read-only on this resource.

Read groups#

GET /v1/notification-groups
GET /v1/notification-groups/<group-id>
GET /v1/notification-groups/<group-id>/channels

GET /v1/notification-groups
GET /v1/notification-groups/<group-id>
GET /v1/notification-groups/<group-id>/channels

The list returns group metadata: name, channel count, and the monitors currently wired to each group. Fetching one group includes the channels it fans out to. The /channels route returns just that list when you do not want the surrounding metadata.

Create a group#

POST /v1/notification-groups

POST /v1/notification-groups

Needs manage_notifications and MANAGER or higher on the project.

Field	Required	Notes
`project_id`	yes	Project to create it in
`name`	yes	Display name
`description`	no	Free text

curl -X POST https://api.drumbeats.io/v1/notification-groups \
  -H "X-API-Key: dk_live_<account-key>" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "<project-id>", "name": "Backend on-call", "description": "Backend rotation" }'

curl -X POST https://api.drumbeats.io/v1/notification-groups \
  -H "X-API-Key: dk_live_<account-key>" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "<project-id>", "name": "Backend on-call", "description": "Backend rotation" }'

Returns 201. The group starts empty.

Update or delete a group#

PATCH  /v1/notification-groups/<group-id>
DELETE /v1/notification-groups/<group-id>

PATCH  /v1/notification-groups/<group-id>
DELETE /v1/notification-groups/<group-id>

PATCH needs manage_notifications and MANAGER or higher. Send only what changes.

DELETE needs the destroy scope, an account-scoped key, and the OWNER role on the project. Monitors pointing at a deleted group lose that routing silently, so check what is attached before removing one.

Attach and detach channels#

POST   /v1/notification-groups/<group-id>/channels
DELETE /v1/notification-groups/<group-id>/channels/<channel-id>

POST   /v1/notification-groups/<group-id>/channels
DELETE /v1/notification-groups/<group-id>/channels/<channel-id>

Both need manage_notifications and MANAGER or higher. Both return 204.

The channel has to live in the same project as the group. One channel can belong to several groups.

Detaching removes only the membership. The channel itself survives and keeps working anywhere else it is attached.

Next#

Notifications groups for routing patterns and the dashboard flow. REST API notification channels for the channels these groups reference. REST API monitors for the notification_group_ids field that links a monitor to a group.