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
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 pagehosted_subdomain
(string) - Subdomain for hosted status page URL
Optional Fields
website_url
(string) - URL to your main websitesupport_url
(string) - URL to your support pagecustom_domain
(string) - Custom domain for the status pageaccess
(string) - Access level:public
orprivate
environment
(string) - Environment key to associate withlogo_url
(string) - URL to your logo imageallow_search_index
(boolean) - Allow search engines to index the pageenable_performance_metrics
(boolean) - Show performance metrics on the pageip_allowlist
(array) - IP addresses/ranges allowed for private pages
Read-Only Fields
key
(string) - Unique identifier for the status pageauth_secret
(string) - Authentication secret for the pagecomponents_count
(integer) - Number of components on the pagestatus
(object) - Current overall status of the pagemetadata
(object) - Additional metadata about the pagecreated
(datetime) - Creation timestampupdated
(datetime) - Last update timestamp
Component Fields
Required Fields
statuspage
(string) - Status page key to add component tomonitor
ORgroup
(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 componentautopublish
(boolean) - Automatically publish incidents for this component
Read-Only Fields
key
(string) - Unique identifier for the componenttype
(string) - Component type:job
,check
,event
,heartbeat
, orgroup
position
(integer) - Display order positionstatus
(object) - Current status of the componentuptime_history
(array) - Historical uptime datacreated
(datetime) - Creation timestampupdated
(datetime) - Last update timestamp
Status Values
Page Status States
operational
- All components are operationaldegraded_performance
- Some components have issuespartial_outage
- Some components are downmajor_outage
- Multiple critical components are down
Component Status States
operational
- Component is working normallydegraded_performance
- Component has performance issuespartial_outage
- Component is partially downmajor_outage
- Component is completely downunder_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