Manage Status Page Monitors

Add, update, remove, reorder and replace the monitors shown on a status page

Overview

A status page shows the monitors attached to it. These endpoints manage that list. All monitors must belong to the same project as the status page.

Action	Endpoint
Add a monitor	POST /api/projects/{projectId}/status-pages/{id}/monitors
Update a monitor’s display settings	PATCH /api/projects/{projectId}/status-pages/{id}/monitors/{monitorId}
Remove a monitor	DELETE /api/projects/{projectId}/status-pages/{id}/monitors/{monitorId}
Reorder monitors	PUT /api/projects/{projectId}/status-pages/{id}/monitors/reorder
Replace the monitor list	PATCH /api/projects/{projectId}/status-pages/{id}/monitors

Authentication

Header	Required	Description
X-API-Key	Yes	Your API key (Authorization: Bearer {jwt} also works). API keys need the read_write scope.
Content-Type	Yes (when sending a body)	application/json

Required access: project admin. Unlike the core status page endpoints, these do not need an X-Project-ID header.

Path parameters

Parameter	Type	Description
projectId	UUID	The project
id	UUID	The status page
monitorId	UUID	The monitor (update and remove only)

Add a monitor

Request body

Field	Type	Required	Description
monitor_id	UUID	Yes	Monitor to add
display_order	integer	Yes	Sort position, 0 or greater
display_name	string | null	No	Name shown on the page instead of the monitor’s own name
group_name	string | null	No	Group heading on the page, up to 100 characters
auto_publish_incidents	boolean | null	No	Post this monitor’s incidents to the page automatically. null or omitted picks a default based on the monitor type.

Response (201 Created)

{
  "success": true,
  "data": {
    "message": "Monitor added successfully",
    "monitor_id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607"
  }
}

cURL

curl -X POST https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monitor_id": "YOUR_MONITOR_ID", "display_name": "API", "display_order": 0 }'

Update a monitor

Changes how one monitor appears. Send only the fields to change.

Field	Type	Description
display_name	string | null	Name shown on the page
group_name	string | null	Group heading, up to 100 characters
display_order	integer	Sort position, 0 or greater
is_visible	boolean	Hide or show the monitor
auto_publish_incidents	boolean	Post this monitor’s incidents automatically

Response (200):

{
  "success": true,
  "data": {
    "message": "Monitor updated successfully",
    "monitor_id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607"
  }
}

cURL

curl -X PATCH https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/monitors/YOUR_MONITOR_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Public API", "is_visible": true }'

Remove a monitor

Response (200):

{
  "success": true,
  "data": {
    "message": "Monitor removed successfully",
    "status_page_id": "0b7c3a52-7d57-4c35-9f0e-5a3b6f1f2a10",
    "monitor_id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607"
  }
}

cURL

curl -X DELETE https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/monitors/YOUR_MONITOR_ID \
  -H "X-API-Key: YOUR_API_KEY"

Removing a monitor from a status page does not delete the monitor.

Reorder monitors

Field	Type	Required	Description
monitor_ids	UUID[]	Yes	Monitor IDs in the desired order, at least one. Each monitor’s display_order becomes its index in this array. IDs not on the page are ignored.

Response (200):

{
  "success": true,
  "data": {
    "message": "Monitors reordered successfully",
    "count": 2
  }
}

cURL

curl -X PUT https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/monitors/reorder \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monitor_ids": ["YOUR_MONITOR_ID_1", "YOUR_MONITOR_ID_2"] }'

Set several monitors at once

Replaces the page’s monitor list with the monitors you send, in one atomic operation. Monitors on the page that are not in the request are removed. Monitors already on the page are updated, and new monitors are added. For monitors already on the page, display_order is always applied; the other fields are applied only when you send them.

Field	Type	Required	Description
monitors	array	Yes	At least one entry. Each monitor_id may appear once.
monitors[].monitor_id	UUID	Yes	Monitor ID
monitors[].display_order	integer	Yes	Sort position, 0 or greater
monitors[].display_name	string | null	No	Display name
monitors[].group_name	string | null	No	Group heading, up to 100 characters
monitors[].auto_publish_incidents	boolean	No	Automatic incident posting. For a new monitor, omitted picks a default based on the monitor type.
monitors[].is_visible	boolean	No	Show or hide the monitor. New monitors default to visible; existing monitors keep their current value when omitted.

Response (200):

{
  "success": true,
  "data": {
    "added": ["a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607"],
    "updated": ["b4e2d3c5-6c7f-4081-9ba2-c3d4e5f60718"],
    "removed": ["c9d8e7f6-a5b4-4c3d-8e2f-1a0b9c8d7e6f"],
    "failed": []
  }
}

failed is always an empty array. The operation is all-or-nothing: if any new monitor does not exist or belongs to another project, the request fails with 400 VALIDATION_ERROR and nothing changes.

cURL

curl -X PATCH https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monitors": [
      { "monitor_id": "YOUR_MONITOR_ID_1", "display_order": 0, "group_name": "Core" },
      { "monitor_id": "YOUR_MONITOR_ID_2", "display_order": 1, "is_visible": false }
    ]
  }'

Errors

Status	Code	Cause
400	VALIDATION_ERROR	Invalid body, monitorId is not a UUID, a monitor_id is duplicated in the bulk request, or a new monitor in the bulk request does not exist in this project
401	AUTHENTICATION_REQUIRED	Missing or invalid credentials
403	INSUFFICIENT_PERMISSIONS	Caller is not a project admin
403	API_KEY_ORGANIZATION_MISMATCH	The API key belongs to a different organization than the status page
403	READ_ONLY_API_KEY	The API key has the read scope
404	RESOURCE_NOT_FOUND	Status page not found, the monitor to add does not exist or is not in this project, or the monitor is not on this page (update and remove)
409	CONFLICT	Adding a monitor that is already on the page: message This monitor is already on the status page.