---
title: Status Pages API
description: Create and manage public status pages for your services via the Cronitor API.
---

The Status Pages API allows you to programmatically create, configure, and manage public status pages that display the health of your services. Status pages automatically reflect monitor states and provide a transparent way to communicate service status to your users. {% .lead %}

See our [Status Pages documentation](/docs/status-pages) for general information on using status pages to communicate service health.

---

## Quick Start

### Create a Status Page
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "My Service Status",
        "hosted_subdomain": "mystatus"
    }' \
    https://cronitor.io/api/statuspages
```

### List All Status Pages
```bash
curl https://cronitor.io/api/statuspages -u API_KEY:
```

### Add a Component to Status Page
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "monitor": "abc123",
        "statuspage": "sp_abc123def456"
    }' \
    https://cronitor.io/api/statuspage_components
```

---

## Status Pages

### List Status Pages

Retrieve all status pages for your organization.

```bash
GET https://cronitor.io/api/statuspages   |   status_codes: 200, 400
```

**Authentication:** Requires API key with `statuspage:read` scope or valid session token.

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `withStatus` | boolean | Include current status information |
| `withComponents` | boolean | Include component details |

#### Example
```bash
curl "https://cronitor.io/api/statuspages?withStatus=true" -u API_KEY:
```

#### Response
```json
{
  "page": 1,
  "page_count": 1,
  "page_size": 50,
  "total_count": 2,
  "data": [
    {
      "key": "sp_abc123def456",
      "name": "My Service Status",
      "website_url": "https://myservice.com",
      "support_url": "https://myservice.com/support",
      "hosted_subdomain": "mystatus",
      "custom_domain": null,
      "access": "public",
      "environment": "production",
      "logo_url": null,
      "allow_search_index": true,
      "enable_performance_metrics": true,
      "components_count": 3,
      "status": {
        "state": "operational"
      },
      "created": "2023-06-01T10:00:00Z",
      "updated": "2023-06-01T10:00:00Z"
    }
  ]
}
```

### Create Status Page

Create a new status page.

```bash
POST https://cronitor.io/api/statuspages   |   status_codes: 201, 400
```

**Authentication:** Requires API key with `statuspage:write` scope or valid session token.

#### Request Body
```json
{
  "name": "My Service Status",
  "website_url": "https://myservice.com",
  "support_url": "https://myservice.com/support",
  "hosted_subdomain": "mystatus",
  "custom_domain": "status.myservice.com",
  "access": "public",
  "environment": "production",
  "logo_url": "https://example.com/logo.png",
  "allow_search_index": true,
  "enable_performance_metrics": true,
  "ip_allowlist": ["192.168.1.0/24", "10.0.0.1"]
}
```

#### Examples

##### Basic Status Page
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "My Service Status",
        "hosted_subdomain": "mystatus"
    }' \
    https://cronitor.io/api/statuspages
```

##### Complete Status Page with Custom Domain
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "My Service Status",
        "website_url": "https://myservice.com",
        "support_url": "https://myservice.com/support",
        "hosted_subdomain": "mystatus",
        "custom_domain": "status.myservice.com",
        "access": "private",
        "ip_allowlist": ["192.168.1.0/24"]
    }' \
    https://cronitor.io/api/statuspages
```

### Get Status Page

Retrieve details for a specific status page.

```bash
GET https://cronitor.io/api/statuspages/:key   |   status_codes: 200, 404
```

**Authentication:** Requires API key with `statuspage:read` scope or valid session token.

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `withStatus` | boolean | Include current status information |
| `withComponents` | boolean | Include component details |

#### Example
```bash
curl "https://cronitor.io/api/statuspages/sp_abc123def456?withStatus=true&withComponents=true" -u API_KEY:
```

### Update Status Page

Update an existing status page.

```bash
PUT https://cronitor.io/api/statuspages/:key   |   status_codes: 200, 400, 404
```

**Authentication:** Requires API key with `statuspage:write` scope or valid session token.

#### Request Body
```json
{
  "name": "Updated Service Status",
  "website_url": "https://myservice.com",
  "access": "private",
  "ip_allowlist": ["10.0.0.0/8"]
}
```

#### Example
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "name": "Updated Service Status",
        "access": "private"
    }' \
    https://cronitor.io/api/statuspages/sp_abc123def456
```

### Delete Status Page

Delete a status page (marks as not visible).

```bash
DELETE https://cronitor.io/api/statuspages/:key   |   status_codes: 204, 404
```

**Authentication:** Requires API key with `statuspage:write` scope or valid session token.

#### Example
```bash
curl --user API_KEY: \
    --request DELETE \
    https://cronitor.io/api/statuspages/sp_abc123def456
```

---

## Status Page Components

Components represent monitors or groups displayed on your status page.

### List Components

Retrieve all components for status pages.

```bash
GET https://cronitor.io/api/statuspage_components   |   status_codes: 200, 400
```

**Authentication:** Requires API key with `statuspage:read` scope or valid session token.

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `statuspage` | string | Filter by status page key |
| `withStatus` | boolean | Include current status information |
| `withUptimeHistory` | boolean | Include uptime history data |
| `orderBy` | string | Sort order: `position`, `-position` |

#### Example
```bash
curl "https://cronitor.io/api/statuspage_components?statuspage=sp_abc123def456&withStatus=true" -u API_KEY:
```

### Create Component

Add a monitor or group to a status page.

```bash
POST https://cronitor.io/api/statuspage_components   |   status_codes: 201, 400
```

**Authentication:** Requires API key with `statuspage:write` scope or valid session token.

#### Request Body

##### Monitor Component
```json
{
  "monitor": "abc123",
  "statuspage": "sp_abc123def456",
  "name": "API Service",
  "description": "Main API endpoint for our service",
  "autopublish": true
}
```

##### Group Component
```json
{
  "group": "web-services",
  "statuspage": "sp_abc123def456",
  "name": "Web Services",
  "autopublish": true
}
```

#### Examples

##### Add Monitor Component
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "monitor": "abc123",
        "statuspage": "sp_abc123def456",
        "name": "API Service"
    }' \
    https://cronitor.io/api/statuspage_components
```

##### Add Group Component
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "group": "web-services",
        "statuspage": "sp_abc123def456"
    }' \
    https://cronitor.io/api/statuspage_components
```

### Get Component

Retrieve details for a specific component.

```bash
GET https://cronitor.io/api/statuspage_components/:key   |   status_codes: 200, 404
```

**Authentication:** Requires API key with `statuspage:read` scope or valid session token.

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `withStatus` | boolean | Include current status information |
| `withUptimeHistory` | boolean | Include uptime history data |
| `time` | string | Time range for uptime history |

#### Example
```bash
curl "https://cronitor.io/api/statuspage_components/comp_abc123?withStatus=true" -u API_KEY:
```

### Update Component

Update an existing component.

```bash
PUT https://cronitor.io/api/statuspage_components/:key   |   status_codes: 200, 400, 404
```

**Authentication:** Requires API key with `statuspage:write` scope or valid session token.

#### Example
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "name": "Updated API Service",
        "description": "Updated description",
        "autopublish": false
    }' \
    https://cronitor.io/api/statuspage_components/comp_abc123
```

### Delete Component

Remove a component from a status page.

```bash
DELETE https://cronitor.io/api/statuspage_components/:key   |   status_codes: 204, 404
```

**Authentication:** Requires API key with `statuspage:write` scope or valid session token.

#### Example
```bash
curl --user API_KEY: \
    --request DELETE \
    https://cronitor.io/api/statuspage_components/comp_abc123
```

---

## Field Reference

### Status Page Fields

#### Required Fields
- **`name`** (string) - Display name for the status page
- **`hosted_subdomain`** (string) - Subdomain for hosted status page URL

#### Optional Fields
- **`website_url`** (string) - URL to your main website
- **`support_url`** (string) - URL to your support page
- **`custom_domain`** (string) - Custom domain for the status page
- **`access`** (string) - Access level: `public` or `private`
- **`environment`** (string) - Environment key to associate with
- **`logo_url`** (string) - URL to your logo image
- **`allow_search_index`** (boolean) - Allow search engines to index the page
- **`enable_performance_metrics`** (boolean) - Show performance metrics on the page
- **`ip_allowlist`** (array) - IP addresses/ranges allowed for private pages

#### Read-Only Fields
- **`key`** (string) - Unique identifier for the status page
- **`auth_secret`** (string) - Authentication secret for the page
- **`components_count`** (integer) - Number of components on the page
- **`status`** (object) - Current overall status of the page
- **`metadata`** (object) - Additional metadata about the page
- **`created`** (datetime) - Creation timestamp
- **`updated`** (datetime) - Last update timestamp

### Component Fields

#### Required Fields (Create)
- **`statuspage`** (string) - Status page key to add component to. Optional on update (inferred from existing component)
- **`monitor`** OR **`group`** (string) - Monitor key or group key to display

#### Optional Fields
- **`name`** (string) - Custom display name (defaults to monitor/group name)
- **`description`** (string) - Description text for the component
- **`autopublish`** (boolean) - Automatically publish incidents for this component

#### Read-Only Fields
- **`key`** (string) - Unique identifier for the component
- **`type`** (string) - Component type: `job`, `check`, `event`, `heartbeat`, or `group`
- **`position`** (integer) - Display order position
- **`status`** (object) - Current status of the component
- **`uptime_history`** (array) - Historical uptime data
- **`created`** (datetime) - Creation timestamp
- **`updated`** (datetime) - Last update timestamp

---

## Status Values

### Page Status States
- **`operational`** - All components are operational
- **`degraded_performance`** - Some components have issues
- **`partial_outage`** - Some components are down
- **`major_outage`** - Multiple critical components are down

### Component Status States
- **`operational`** - Component is working normally
- **`degraded_performance`** - Component has performance issues
- **`partial_outage`** - Component is partially down
- **`major_outage`** - Component is completely down
- **`under_maintenance`** - Component is under maintenance

---

## Error Responses

### 400 Bad Request
```json
{
  "hosted_subdomain": ["This field is required."],
  "custom_domain": ["Invalid domain format."]
}
```

### 404 Not Found
```json
{
  "detail": "Not found."
}
```

---

## Rate Limits

- **Authenticated requests**: 1000 requests per hour
- **Status page limit**: 10 status pages per organization (varies by plan)
- **Component limit**: 50 components per status page

---

## Notes

- Status pages automatically reflect the current state of associated monitors
- Private status pages require IP allowlist configuration for access
- Custom domains require DNS configuration to point to Cronitor's servers
- Component autopublish setting determines if incidents are automatically created for monitor failures