API Monitor groups

Base URL: https://api.okstatus.eu/api/v1/monitor-groups — every request needs an Authorization: Bearer oks_live_... header, see Authentication.

A group is a folder of the Monitors page. Two rules shape the endpoints below:

• A monitor belongs to one group at most. Putting it in a group takes it out of its previous one.
• A group can carry alert channels. A monitor that joins the group gets them attached; monitors already in the group are not touched when the group’s channels change.

List groups

GET /api/v1/monitor-groups

Returns every group, in dashboard order, with the ids of its monitors.

{
  "data": [
    {
      "id": "7b1e…",
      "name": "Payments",
      "description": "Everything on the checkout path",
      "color": "aurora",
      "tags": ["prod"],
      "alertChannelIds": ["3f6e…"],
      "monitorIds": ["a41c…", "c9d2…"],
      "paused": false,
      "muted": false
    }
  ]
}

paused and muted tell whether the group was paused or muted as a whole from the dashboard; they are read-only here. To pause monitors through the API, PATCH each monitor.

Create a group

POST /api/v1/monitor-groups
Content-Type: application/json

Field	Type	Required	Description
name	string	✅	Group name (1–255 chars)
description	string		Free text shown under the name
color	string		A color of the dashboard’s palette, by its key — as returned for an existing group
tags	string[]		Up to 10 tags, for the group itself (they are not copied to its monitors)
alertChannelIds	string[]		Channels attached to every monitor that joins the group
monitorIds	string[]		The group’s monitors

Returns 201 with { "data": Group }. If one of the monitorIds is not a monitor of your organization, the request fails with 404 NOT_FOUND and no group is created.

Get / update / delete a group

GET    /api/v1/monitor-groups/:id
PATCH  /api/v1/monitor-groups/:id
DELETE /api/v1/monitor-groups/:id

PATCH accepts the same fields as create, all optional. monitorIds is the complete membership: monitors left out of the list leave the group, and [] empties it.

curl -X PATCH https://api.okstatus.eu/api/v1/monitor-groups/$GROUP_ID \
  -H "Authorization: Bearer $OKSTATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monitorIds": ["a41c…", "c9d2…", "e07f…"] }'

DELETE removes the group only — its monitors are kept and go back to the ungrouped list. It returns { "data": { "deleted": true } }.

Errors

404 NOT_FOUND if the group, or a monitor named in monitorIds, doesn’t exist in your org. See Authentication for the shared error format and rate limits.