REST API

The Drumbeats REST API manages monitors, incidents, projects, and notifications programmatically. It runs at https://api.drumbeats.io/v1/ and authenticates with an API key — either project-scoped or account-scoped. This page covers the global concerns — authentication, key types, permission scopes, scoping, pagination, error shape — and links out to each resource's endpoint reference.

The Ping API is separate from the REST API. The Ping API has no authentication header — the monitor ID in the URL is the credential — and is the surface every monitored job hits. Everything on this page is about the management API your dashboard scripts use.

Base URL

https://api.drumbeats.io/v1/

https://api.drumbeats.io/v1/

Every customer-facing endpoint — this REST API and the Ping API alike — is reachable at this same bare origin. You will never need the internal /beats, /id, or /alerts path segments referenced elsewhere in our infra docs; those are internal service routing, not part of the public contract:

The interactive OpenAPI explorer — browse the schema and "Try it out" against these same endpoints — is hosted at api.drumbeats.io/beats/api-docs/public. That /beats segment is where the docs page lives, not part of any request URL above.

Authentication

Every REST API endpoint requires an API key passed in the X-API-Key header.

curl https://api.drumbeats.io/v1/monitors?project_id=<project-id> \
  -H "X-API-Key: dk_live_<26-char-random>"

curl https://api.drumbeats.io/v1/monitors?project_id=<project-id> \
  -H "X-API-Key: dk_live_<26-char-random>"

There are two kinds of key. They share the same format and the same header — the difference is how far they reach and how their permissions are granted.

Project-scoped keys are unchanged from earlier releases. Account-scoped keys are new: only users who own at least one project can create one, and they carry permission scopes so you can mint a key that, for example, reads everywhere but writes nowhere. Because an account-scoped key spans projects, you pass project_id to target a specific one — the same way the list endpoints already work.

Creating an API key

Project-scoped key:

1. Open the dashboard and go to Settings → Project Settings → API Keys.
2. Click Create API Key.
3. Enter a name and expiration (1–365 days).
4. Copy the key immediately — it is shown only once.

Account-scoped key:

1. Go to Account → API Keys. (Available only if you own at least one project.)
2. Click Create API Key.
3. Enter a name and expiration (1–365 days), and select the permission scopes the key should carry. Selecting none mints a read-only key.
4. Copy the key immediately — it is shown only once.

Key details

Permission scopes

Account-scoped keys carry an explicit set of permission scopes. A scope governs what kind of action the key may perform; the key's project role governs where. The two are independent gates — see The two gates below.

Two rules shape how scopes combine:

• read is implied by any write scope. A key with manage_monitors can already read; you do not also need to select read.
• A key minted with no scopes selected is read-only. It can call every GET endpoint its projects expose and nothing else.

Project-scoped keys do not have a scope picker. They behave as read plus monitor writes — the set of things a project key could already do before scopes were introduced — and can never reach the project, notification, or destroy operations no matter the role they inherit. Those operations are account-key territory.

The two gates

A request from an API key must pass both of these checks:

1. Permission scope — the key holds the scope the operation requires (or read for a read).
2. Project role — the key's role on the target project is high enough for the operation.

For example, creating a monitor needs the manage_monitors scope and a MEMBER (or higher) role on that project. A key with manage_monitors but only READONLY on the project is rejected; so is a key that is OWNER on the project but was minted without manage_monitors.

Project scoping

A project-scoped key operates inside the single project it is bound to, so most endpoints do not require a project_id parameter. An account-scoped key spans projects, so you pass project_id to target one — the same parameter the list endpoints already use. The endpoints that always take project_id are the list endpoints that filter by project (e.g. GET /v1/monitors?project_id=…); GET /v1/projects takes none and returns every project the authenticated principal can see.

Response codes

Error responses use this shape:

{ "error": "Description of what went wrong" }

{ "error": "Description of what went wrong" }

Pagination

List endpoints use page-based pagination. The defaults work for dashboards; bump limit to 200 for batch scripts.

Responses include a pagination object alongside the data array:

{
  "data": [ /* … */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

{
  "data": [ /* … */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Role matrix

The role a key holds on a project is the second of the two gates. A project-scoped key inherits its creator's role on its one project; an account-scoped key resolves to your role on each project it touches. The role caps what the key can do there.

An account-scoped key also needs the matching permission scope on top of the role — the role alone is not enough.

Endpoint reference

• Monitors API — create, update, delete, pause, query monitors and their pings.
• Incidents API — list, acknowledge, and resolve incidents.
• Projects API — list, retrieve, create, update, and delete projects and their membership.
• Notification Channels API — list, retrieve, create, update, and delete channels and their types.
• Notification Groups API — list, retrieve, create, update, and delete groups and the channels they fan out to.

Related guides

• Ping API — the unauthenticated surface jobs ping; not part of the REST API.
• Incidents — incident lifecycle and what the dashboard does that the REST API mirrors.
• Notifications — how alert routing maps to the channels and groups returned by these endpoints.