Reference

REST API — Notification Groups

Manage Drumbeats notification groups and their channels via the REST API. Groups are what monitors are wired to — one incident pages every channel.

The Drumbeats Notification Groups API lists, retrieves, creates, updates, and deletes notification groups and manages the channels each group delivers to. A notification group is a named collection of channels — monitors are wired to groups (not directly to channels) so the same routing can be reused across multiple monitors and updated in one place. Every endpoint requires an X-API-Key header.

Reads work from any key. Group writes — create, update, delete — are reachable only by an account-scoped key with the right permission scope; a project-scoped key is read-only here.

List groups

GET /v1/notification-groups

GET /v1/notification-groups

Returns every notification group in the project associated with the API key.

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

The response includes group metadata: name, channel count, and the IDs of monitors currently wired to the group.

Get one group

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

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

Returns a single group by UUID, including the list of channels it fans out to.

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

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

Get a group's channels

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

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

Returns the channels associated with a specific group. Identical to fetching the group and reading the embedded channels field — use this when you want only the channel list and no group metadata.

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

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

Create a group

POST /v1/notification-groups

POST /v1/notification-groups

Requires an account-scoped key with the manage_notifications scope, plus a MANAGER (or higher) role on the target project.

Field	Required	Type	Description
`project_id`	Yes	UUID	Project to create the group in.
`name`	Yes	string	Display name.
`description`	No	string	Free-text description.

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": "DevOps Team", "description": "On-call routing" }'

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": "DevOps Team", "description": "On-call routing" }'

Returns 201. The new group starts with no channels — wire channels to it with the channel-membership routes below.

Update a group

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

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

Requires the manage_notifications scope and a MANAGER (or higher) role on the group's project. Send only the fields you want to change.

Delete a group

Hard-gated: requires the destroy scope, an account-scoped key, and the OWNER role on the group's project.

Add a channel to a group

Links an existing channel to the group. Requires the manage_notifications scope and a MANAGER (or higher) role on the group's project. The channel must belong to the same project as the group.

Field	Required	Type	Description
`channel_id`	Yes	UUID	The notification channel to attach.

Returns 204. Channels can belong to multiple groups.

Remove a channel from a group

Detaches a channel from the group. Requires the manage_notifications scope and a MANAGER (or higher) role on the group's project. Only the membership is removed — the channel itself is not deleted.

Returns 204. You can also manage channel membership in the dashboard under Notifications → Groups.

Notifications: groups — how to create groups in the dashboard and assign them to monitors.
Notifications: alert logic — how a group delivers under cooldown and re-page rules.
REST API — Notification Channels — the channel resources groups reference.
REST API — Monitors — the notification_group_ids field that links a monitor to one or more groups.