Dashboard resources and assignment

All paths below are relative to /api/v1.

Read

GET /dashboards / MCP list_dashboards: dashboards:read, optional limit/cursor. Each list item contains id, name, assignable, public, public_url, public_wallboard_url. assignable identifies a custom dashboard, not authorization to publish it.

GET /dashboards/:id / get_dashboard: dashboards:read, ID plus optional limit/cursor for nested checks.

Dashboard detail includes:

Field	Meaning
id, name	Dashboard identity
default	Account Overview rather than custom membership
public	Public sharing state
editable	Private custom dashboard eligible for supported automation edits
settings	Display booleans and incident-history day count
public_url, public_wallboard_url	Existing unauthenticated sharing links, or null
checks	Paginated check resources plus nullable position and group_id
groups	Up to 100 objects with group id and name
groups_truncated	Whether more groups exist than returned

Nested checks follow ID pagination, not necessarily display order. Read position/group_id for presentation. Overview has no membership positions. Public URLs are returned only for already-public custom dashboards; a read does not enable sharing.

Create and update

POST /dashboards / create_dashboard: requires dashboards:create, dashboard body and idempotency. Creates a private custom dashboard.

PATCH /dashboards/:id / update_dashboard: requires dashboards:update, ID and dashboard body; private custom dashboards only.

Body field	Constraint
name	Nonempty string <=255; required on create, unique within account
show_incident_history	Boolean
show_needs_attention	Boolean
show_summary_panels	Boolean
incident_history_days	Seven or 30

The defaults are the saved dashboard defaults; read settings after creation. Supported writes return the dashboard fields above without nested checks/groups. They cannot edit Overview, published dashboards, public state, branding, groups, pinned navigation or landing defaults.

{
  "dashboard": {
    "name": "Service health",
    "show_incident_history": true,
    "incident_history_days": 30
  }
}

Attach

PUT /dashboards/:dashboard_id/checks/:check_id / attach_check_to_dashboard, scope dashboards:assign. No REST body; MCP requires both IDs.

Idempotently adds the owned check to an existing custom dashboard. Overview is not assignable. Attachment can target a published custom dashboard, so adding a check may change publicly visible content: review that consequence. Returns {"id":"<dashboard-id>","check_id":"<check-id>"}.

Detach

DELETE /dashboards/:dashboard_id/checks/:check_id / detach_check_from_dashboard, scope dashboards:assign. Private custom dashboards only. Idempotently removes membership without deleting the check. Returns the same ID pair as attach.

Reorder

PUT /dashboards/:dashboard_id/check_order / reorder_dashboard_checks, scope dashboards:assign. Private custom dashboards only.

{
  "check_ids": ["check_FIRST", "check_SECOND"],
  "group_id": "123"
}

group_id is optional; omit for the ungrouped collection. Supply every check in that group exactly once, in the desired order. The array must contain 1-100 unique IDs. Partial lists, duplicates, foreign checks and movement between groups are not supported.

Returns id and the accepted check_ids array. The operation does not create or rename groups. For other dashboard actions use the UI.