Status Pages 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.

See our Status Pages documentation for general information on using status pages to communicate service health.

Quick Start

Create a Status Page

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

curl https://cronitor.io/api/statuspages -u API_KEY:

Add a Component to Status Page

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.

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

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

Response

{
  "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.

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

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

Request Body

{
  "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

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

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.

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

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

Update Status Page

Update an existing status page.

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

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

Example

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).

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

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

Example

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.

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

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.

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

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

Group Component

{
  "group": "web-services",
  "statuspage": "sp_abc123def456",
  "name": "Web Services",
  "autopublish": true
}

Examples

Add Monitor Component

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

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.

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

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

Update Component

Update an existing component.

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

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.

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

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

statuspage (string) - Status page key to add component to
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

{
  "hosted_subdomain": ["This field is required."],
  "custom_domain": ["Invalid domain format."]
}

404 Not Found

{
  "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