> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#add-a-monitor) | `POST /api/projects/{projectId}/status-pages/{id}/monitors` |
| [Update a monitor's display settings](#update-a-monitor) | `PATCH /api/projects/{projectId}/status-pages/{id}/monitors/{monitorId}` |
| [Remove a monitor](#remove-a-monitor) | `DELETE /api/projects/{projectId}/status-pages/{id}/monitors/{monitorId}` |
| [Reorder monitors](#reorder-monitors) | `PUT /api/projects/{projectId}/status-pages/{id}/monitors/reorder` |
| [Replace the monitor list](#set-several-monitors-at-once) | `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)

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

```bash cURL theme={null}
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):

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

```bash cURL theme={null}
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):

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

```bash cURL theme={null}
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):

```json theme={null}
{
  "success": true,
  "data": {
    "message": "Monitors reordered successfully",
    "count": 2
  }
}
```

```bash cURL theme={null}
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):

```json theme={null}
{
  "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.

```bash cURL theme={null}
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.` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.