Cronitor API

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

ParameterTypeDescription
withStatusbooleanInclude current status information
withComponentsbooleanInclude 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

ParameterTypeDescription
withStatusbooleanInclude current status information
withComponentsbooleanInclude 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

ParameterTypeDescription
statuspagestringFilter by status page key
withStatusbooleanInclude current status information
withUptimeHistorybooleanInclude uptime history data
orderBystringSort 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

ParameterTypeDescription
withStatusbooleanInclude current status information
withUptimeHistorybooleanInclude uptime history data
timestringTime 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
Previous
Metrics