StatusCake API (1.2.0)
Download OpenAPI specification:Download
StatusCake API endpoints to manage monitoring resources.
Documentation on API authentication can be found here.
Documentation on API ratelimiting can be found here.
Documentation on error handling can be found here.
Documentation on input parameters, including how to pass arrays to API endpoints can be found here.
The Heartbeat API provides methods to operate on heartbeat resources, effectively allowing checks to be read and listed.
Get all heartbeat checks
Returns a list of heartbeat checks for an account.
query Parameters
status | string Enum: "down" "up" Heartbeat check status |
page | integer <int32> >= 1 Default: 1 Page of results |
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of heartbeat checks to return per page |
tags | string Comma separated list of tags assocaited with a check |
matchany | boolean Default: false Include heartbeat checks in response that match any specified tag or
all tags. This parameter does not take a value. The absence of this
paratemer equates to |
nouptime | boolean Default: false Do not calculate uptime percentages for results. This parameter does
not take a value. The absence of this paratemer equates to |
Responses
Response Schema: application/json
required | Array of objects (HeartbeatTestOverview) List of heartbeat checks |
required | object (Pagination) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/heartbeat \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "name": "example Heartbeat check",
- "period": 1800,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "paused": false,
- "status": "up",
- "tags": [
- "tag1",
- "tag2"
], - "uptime": 99.9
}
], - "metadata": {
- "page": 1,
- "per_page": 25,
- "page_count": 10,
- "total_count": 230
}
}
Create a heartbeat check
Creates a heartbeat check with the given parameters.
Request Body schema: application/x-www-form-urlencoded
name required | string Name of the check |
period required | integer <int32> [ 30 .. 172800 ] Default: 1800 Number of seconds since the last ping before the check is considered down |
contact_groups | Array of strings List of contact group IDs |
host | string Name of the hosting provider |
paused | boolean Default: false Whether the check should be run |
tags | Array of strings List of tags |
Responses
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/heartbeat \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Example%20Heartbeat&period=1800"
Response samples
- 201
- default
{- "data": {
- "new_id": "123"
}
}
Retrieve a heartbeat check
Returns a heartbeat check with the given id.
path Parameters
test_id required | string Heartbeat check ID |
Responses
Response Schema: application/json
required | object (HeartbeatTest) | ||||||||||||||||||||||
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/heartbeat/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": {
- "id": "123",
- "name": "example Heartbeat check",
- "period": 1800,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "last_tested_at": "2013-01-20T14:38:18+00:00",
- "paused": false,
- "status": "up",
- "tags": [
- "tag1",
- "tag2"
], - "uptime": 99.9
}
}
Update a heartbeat check
Updates a heartbeat check with the given parameters.
path Parameters
test_id required | string Heartbeat check ID |
Request Body schema: application/x-www-form-urlencoded
name | string Name of the check |
period | integer <int32> [ 30 .. 172800 ] Number of seconds since the last ping before the check is considered down |
contact_groups | Array of strings List of contact group IDs |
host | string Name of the hosting provider |
paused | boolean Whether the check should be run |
tags | Array of strings List of tags |
Responses
Request samples
- cURL
- Go
curl -X PUT https://api.statuscake.com/v1/heartbeat/123 \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Example%20Heartbeat&period=1800"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Delete a heartbeat check
Deletes a heartbeat check with the given id.
path Parameters
test_id required | string Heartbeat check ID |
Responses
Request samples
- cURL
- Go
curl -X DELETE https://api.statuscake.com/v1/heartbeat/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
The Pagespeed API provides methods to operate on pagespeed resources, effectively allowing checks to be created, read, updated, and deleted. In addition the history of a specific pagespeed check can be returned for a given period.
Get all pagespeed checks
Returns a list of pagespeed checks for an account.
query Parameters
page | integer <int32> >= 1 Default: 1 Page of results |
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of pagespeed checks to return per page |
Responses
Response Schema: application/json
required | Array of objects (PagespeedTest) List of pagespeed checks |
required | object (Pagination) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/pagespeed \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "name": "Example",
- "check_rate": 1800,
- "alert_bigger": 0,
- "alert_slower": 0,
- "alert_smaller": 0,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "latest_stats": {
- "loadtime": 209,
- "filesize": 160.513,
- "requests": 5,
- "has_issue": true,
- "latest_issue": "The Total Load Time of the Page (4841/ms) is longer than the alert\nthreshold of 0/ms"
}, - "location": "PAGESPD-UK5",
- "paused": false
}
], - "metadata": {
- "page": 1,
- "per_page": 25,
- "page_count": 10,
- "total_count": 230
}
}
Create a pagespeed check
Creates a pagespeed check with the given parameters.
Request Body schema: application/x-www-form-urlencoded
name required | string Name of the check |
website_url required | string <uri> URL, FQDN, or IP address of the website under test |
check_rate required | integer (PagespeedTestCheckRate) Enum: 60 300 600 900 1800 3600 86400 Number of seconds between checks |
alert_bigger | integer <int32> >= 0 Default: 0 An alert will be sent if the size of the page is larger than this value (kb). A value of 0 prevents alerts being sent. |
alert_slower | integer <int64> >= 0 Default: 0 An alert will be sent if the load time of the page exceeds this value (ms). A value of 0 prevents alerts being sent |
alert_smaller | integer <int32> >= 0 Default: 0 An alert will be sent if the size of the page is smaller than this value (kb). A value of 0 prevents alerts being sent |
contact_groups | Array of strings List of contact group IDs |
paused | boolean Default: false Whether the check should be run |
region required | string (PagespeedTestRegion) Enum: "AU" "CA" "DE" "FR" "IN" "JP" "NL" "SG" "UK" "US" "USW" Region on which to run checks |
Responses
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/pagespeed \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Example&website_url=https://www.example.com®ion=UK&check_rate=10"
Response samples
- 201
- default
{- "data": {
- "new_id": "123"
}
}
Retrieve a pagespeed check
Returns a pagespeed check with the given id.
path Parameters
test_id required | string Pagespeed check ID |
Responses
Response Schema: application/json
required | object (PagespeedTest) | ||||||||||||||||||||||
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/pagespeed/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": {
- "id": "123",
- "name": "Example",
- "check_rate": 1800,
- "alert_bigger": 0,
- "alert_slower": 0,
- "alert_smaller": 0,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "latest_stats": {
- "loadtime": 209,
- "filesize": 160.513,
- "requests": 5,
- "has_issue": true,
- "latest_issue": "The Total Load Time of the Page (4841/ms) is longer than the alert\nthreshold of 0/ms"
}, - "location": "PAGESPD-UK5",
- "paused": false
}
}
Update a pagespeed check
Updates a pagespeed check with the given parameters.
path Parameters
test_id required | string Pagespeed check ID |
Request Body schema: application/x-www-form-urlencoded
name | string Name of the check |
website_url | string <uri> URL, FQDN, or IP address of the website under test |
check_rate | integer (PagespeedTestCheckRate) Enum: 60 300 600 900 1800 3600 86400 Number of seconds between checks |
alert_bigger | integer <int32> >= 0 An alert will be sent if the size of the page is larger than this value (kb). A value of 0 prevents alerts being sent. |
alert_slower | integer <int64> >= 0 An alert will be sent if the load time of the page exceeds this value (ms). A value of 0 prevents alerts being sent |
alert_smaller | integer <int32> >= 0 An alert will be sent if the size of the page is smaller than this value (kb). A value of 0 prevents alerts being sent |
contact_groups | Array of strings List of contact group IDs |
paused | boolean Whether the check should be run |
region | string (PagespeedTestRegion) Enum: "AU" "CA" "DE" "FR" "IN" "JP" "NL" "SG" "UK" "US" "USW" Region on which to run checks |
Responses
Request samples
- cURL
- Go
curl -X PUT https://api.statuscake.com/v1/pagespeed/123 \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Example®ion=UK&check_rate=10"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Delete a pagespeed check
Deletes a pagespeed check with the given id.
path Parameters
test_id required | string Pagespeed check ID |
Responses
Request samples
- cURL
- Go
curl -X DELETE https://api.statuscake.com/v1/pagespeed/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Get all pagespeed check history
Returns a list of pagespeed check history results for a given id, detailing the runs performed on the StatusCake testing infrastruture.
The returned results are a paginated series. Alongside the response
data is a links
object referencing the current response document,
self
, and the next page in the series, next
.
Aggregated data over the specified duration is returned in the root
level metadata
field.
path Parameters
test_id required | string Pagespeed check ID |
query Parameters
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of results to return from the series |
before | integer <int64> >= 0 Only results created before this UNIX timestamp will be returned |
after | integer <int64> >= 0 Only results created after this UNIX timestamp will be returned |
Responses
Response Schema: application/json
required | Array of objects (PagespeedTestHistoryResult) List of pagespeed check history results |
required | object (Links) |
object (Metadata) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/pagespeed/123/history \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "created_at": "2017-11-04T11:58:23+00:00",
- "filesize": 169.342,
- "loadtime": 361,
- "requests": 9,
- "throttling": "4G"
}
], - "metadata": {
- "aggregates": {
- "filesize": {
- "min": 8,
- "max": 9,
- "avg": 8.129
}, - "loadtime": {
- "min": 162,
- "max": 3344,
- "avg": 410.292
}, - "requests": {
- "min": 160,
- "max": 169,
- "avg": 161.654
}
}
}
}
The SSL API provides methods to operate on SSL resources, effectively allowing checks to be created, read, updated, and deleted.
Get all SSL checks
Returns a list of SSL checks for an account.
query Parameters
page | integer <int32> >= 1 Default: 1 Page of results |
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of SSL checks to return per page |
Responses
Response Schema: application/json
required | Array of objects (SSLTest) List of SSL checks |
required | object (Pagination) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/ssl \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "check_rate": 1800,
- "alert_at": [
- 1,
- 7,
- 30
], - "alert_broken": true,
- "alert_expiry": true,
- "alert_mixed": true,
- "alert_reminder": true,
- "certificate_score": 55,
- "certificate_status": "CERT_OK",
- "cipher": "TLS_RSA_WITH_AES_128_GCM_SHA256",
- "cipher_score": 70,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "issuer_common_name": "Let's Encrypt Authority X3",
- "flags": {
- "follow_redirects": true,
- "has_mixed": true,
- "has_pfs": true,
- "is_broken": false,
- "is_expired": false,
- "is_extended": true,
- "is_missing": false,
- "is_revoked": false
}, - "follow_redirects": true,
- "hostname": "svc.example.com",
- "last_reminder": 0,
- "mixed_content": [
], - "paused": false,
- "updated_at": "2017-10-24T09:02:25+00:00",
- "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36 Edg/86.0.622.51 mycustomstring",
- "valid_from": "2017-10-10T14:06:00+00:00",
- "valid_until": "2017-12-29T00:00:00+00:00"
}
], - "metadata": {
- "page": 1,
- "per_page": 25,
- "page_count": 10,
- "total_count": 230
}
}
Create an SSL check
Creates an SSL check with the given parameters.
Request Body schema: application/x-www-form-urlencoded
website_url required | string <uri> URL of the server under test. Must begin with https:// |
check_rate required | integer (SSLTestCheckRate) Enum: 300 600 1800 3600 86400 2073600 Number of seconds between checks |
alert_at required | Array of integers <int32> [ items <int32 > ] List representing when alerts should be sent (days). Must be exactly 3 numerical values |
alert_broken | boolean Default: false Whether to enable alerts when SSL certificate issues are found |
alert_expiry | boolean Default: false Whether to enable alerts when the SSL certificate is to expire |
alert_mixed | boolean Default: false Whether to enable alerts when mixed content is found |
alert_reminder | boolean Default: false Whether to enable alert reminders |
contact_groups | Array of strings List of contact group IDs |
follow_redirects | boolean Default: false Whether to follow redirects when testing. Disabled by default |
hostname | string Hostname of the server under test |
paused | boolean Default: false Whether the check should be run |
user_agent | string Custom user agent string set when testing |
Responses
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/ssl \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "website_url=https://www.example.com&check_rate=1800&alert_at[]=1&alert_at[]=2&alert_at[]=3&alert_reminder=true&alert_expiry=true&alert_broken=true&alert_mixed=true"
Response samples
- 201
- default
{- "data": {
- "new_id": "123"
}
}
Retrieve an SSL check
Returns an SSL check with the given id.
path Parameters
test_id required | string SSL check ID |
Responses
Response Schema: application/json
required | object (SSLTest) | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/ssl/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": {
- "id": "123",
- "check_rate": 1800,
- "alert_at": [
- 1,
- 7,
- 30
], - "alert_broken": true,
- "alert_expiry": true,
- "alert_mixed": true,
- "alert_reminder": true,
- "certificate_score": 55,
- "certificate_status": "CERT_OK",
- "cipher": "TLS_RSA_WITH_AES_128_GCM_SHA256",
- "cipher_score": 70,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "issuer_common_name": "Let's Encrypt Authority X3",
- "flags": {
- "follow_redirects": true,
- "has_mixed": true,
- "has_pfs": true,
- "is_broken": false,
- "is_expired": false,
- "is_extended": true,
- "is_missing": false,
- "is_revoked": false
}, - "follow_redirects": true,
- "hostname": "svc.example.com",
- "last_reminder": 0,
- "mixed_content": [
], - "paused": false,
- "updated_at": "2017-10-24T09:02:25+00:00",
- "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36 Edg/86.0.622.51 mycustomstring",
- "valid_from": "2017-10-10T14:06:00+00:00",
- "valid_until": "2017-12-29T00:00:00+00:00"
}
}
Update an SSL check
Updates an SSL check with the given parameters.
path Parameters
test_id required | string SSL check ID |
Request Body schema: application/x-www-form-urlencoded
website_url | string <uri> URL of the server under test. Must begin with https:// |
check_rate | integer (SSLTestCheckRate) Enum: 300 600 1800 3600 86400 2073600 Number of seconds between checks |
alert_at | Array of integers <int32> [ items <int32 > ] List representing when alerts should be sent (days). Must be exactly 3 numerical values |
alert_broken | boolean Whether to enable alerts when SSL certificate issues are found |
alert_expiry | boolean Whether to enable alerts when the SSL certificate is to expire |
alert_mixed | boolean Whether to enable alerts when mixed content is found |
alert_reminder | boolean Whether to enable alert reminders |
contact_groups | Array of strings List of contact group IDs |
follow_redirects | boolean Whether to follow redirects when testing. Disabled by default |
hostname | string Hostname of the server under test |
paused | boolean Whether the check should be run |
user_agent | string Custom user agent string set when testing |
Responses
Request samples
- cURL
- Go
curl -X PUT https://api.statuscake.com/v1/ssl/123 \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "check_rate=1800&alert_at[]=1&alert_at[]=2&alert_at[]=3&alert_reminder=true&alert_expiry=true&alert_broken=true&alert_mixed=true"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Delete an SSL check
Deletes an SSL check with the given id.
path Parameters
test_id required | string Pagespeed check ID |
Responses
Request samples
- cURL
- Go
curl -X DELETE https://api.statuscake.com/v1/ssl/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
The Uptime API provides methods to operate on uptime resources, effectively allowing checks to be created, read, updated, and deleted. In addition the Uptime API is able to return a history of uptime status for a given period; and return a history of alerts since a given date.
Get all uptime checks
Returns a list of uptime checks for an account.
query Parameters
status | string Enum: "down" "up" Uptime check status |
page | integer <int32> >= 1 Default: 1 Page of results |
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of uptime checks to return per page |
tags | string Comma separated list of tags assocaited with a check |
matchany | boolean Default: false Include uptime checks in response that match any specified tag or all
tags. This parameter does not take a value. The absence of this
paratemer equates to |
nouptime | boolean Default: false Do not calculate uptime percentages for results. This parameter does
not take a value. The absence of this paratemer equates to |
Responses
Response Schema: application/json
required | Array of objects (UptimeTestOverview) List of uptime checks |
required | object (Pagination) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/uptime \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "name": "example HTTP check",
- "test_type": "HTTP",
- "check_rate": 1800,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "paused": false,
- "status": "up",
- "tags": [
- "tag1",
- "tag2"
], - "uptime": 99.9
}
], - "metadata": {
- "page": 1,
- "per_page": 25,
- "page_count": 10,
- "total_count": 230
}
}
Create an uptime check
Creates an uptime check with the given parameters.
Request Body schema: application/x-www-form-urlencoded
name required | string Name of the check |
test_type required | string (UptimeTestType) Enum: "DNS" "HEAD" "HTTP" "PING" "SMTP" "SSH" "TCP" Uptime check type |
website_url required | string <uri> URL or IP address of the server under test |
check_rate required | integer (UptimeTestCheckRate) Enum: 0 30 60 300 900 1800 3600 86400 Number of seconds between checks |
basic_username | string Basic authentication username |
basic_password | string Basic authentication password |
confirmation | integer <int32> [ 0 .. 3 ] Default: 2 Number of confirmation servers to confirm downtime before an alert is triggered |
contact_groups | Array of strings List of contact group IDs |
custom_header | string JSON object. Represents headers to be sent when making requests |
do_not_find | boolean Default: false Whether to consider the check as down if the content is present within the response |
dns_ips | Array of strings List of IP addresses to compare against returned DNS records |
dns_server | string FQDN or IP address of the nameserver to query |
enable_ssl_alert | boolean Default: false Whether to send an alert if the SSL certificate is soon to expire |
final_endpoint | string Specify where the redirect chain should end |
find_string | string String to look for within the response. Considered down if not found |
follow_redirects | boolean Default: false Whether to follow redirects when testing. Disabled by default |
host | string Name of the hosting provider |
include_header | boolean Default: false Include header content in string match search |
paused | boolean Default: false Whether the check should be run |
port | integer <int32> >= 0 Destination port for TCP checks |
post_body | string JSON object. Payload submitted with the request. Setting this updates the check to use the HTTP POST verb |
post_raw | string Raw HTTP POST string to send to the server |
regions | Array of strings List of regions on which to run checks. The values required for this
parameter can be retrieved from the |
status_codes_csv | string Comma separated list of status codes that trigger an alert |
tags | Array of strings List of tags |
timeout | integer <int32> [ 5 .. 75 ] Default: 15 The number of seconds to wait to receive the first byte |
trigger_rate | integer <int32> [ 0 .. 60 ] Default: 0 The number of minutes to wait before sending an alert |
use_jar | boolean Default: false Whether to enable cookie storage |
user_agent | string Custom user agent string set when testing |
Responses
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/uptime \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Example%20HTTP&test_type=HTTP&website_url=https://www.example.com&check_rate=1800®ions[]=london®ions[]=paris"
Response samples
- 201
- default
{- "data": {
- "new_id": "123"
}
}
Retrieve an uptime check
Returns an uptime check with the given id.
path Parameters
test_id required | string Uptime check ID |
Responses
Response Schema: application/json
required | object (UptimeTest) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/uptime/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": {
- "id": "123",
- "name": "example HTTP check",
- "test_type": "HTTP",
- "check_rate": 1800,
- "confirmation": 3,
- "contact_groups": [
- "1",
- "2",
- "3"
], - "dns_ips": [ ],
- "do_not_find": false,
- "enable_ssl_alert": true,
- "follow_redirects": false,
- "host": "AWS",
- "include_header": false,
- "last_tested_at": "2013-01-20T14:38:18+00:00",
- "next_location": "UK",
- "paused": false,
- "processing": true,
- "processing_on": "UKCON2",
- "processing_state": "pretest",
- "servers": [
- {
- "description": "United Kingdom, London - 5",
- "ipv4": "178.62.78.199",
- "ipv6": "2a03:b0c0:1:d0::5e:f001",
- "region": "United Kingdom / London",
- "region_code": "london",
- "status": "up"
}
], - "status": "up",
- "status_codes": [
- "400",
- "401",
- "402",
- "403",
- "404",
- "405",
- "406",
- "407",
- "408",
- "409",
- "410",
- "411",
- "412",
- "413",
- "414",
- "415",
- "416",
- "417",
- "500"
], - "tags": [
- "tag1",
- "tag2"
], - "timeout": 15,
- "trigger_rate": 0,
- "uptime": 99.9,
- "use_jar": true
}
}
Update an uptime check
Updates an uptime check with the given parameters.
path Parameters
test_id required | string Uptime check ID |
Request Body schema: application/x-www-form-urlencoded
name | string Name of the check |
website_url | string <uri> URL or IP address of the server under test |
check_rate | integer (UptimeTestCheckRate) Enum: 0 30 60 300 900 1800 3600 86400 Number of seconds between checks |
basic_username | string Basic authentication username |
basic_password | string Basic authentication password |
confirmation | integer <int32> [ 0 .. 3 ] Number of confirmation servers to confirm downtime before an alert is triggered |
contact_groups | Array of strings List of contact group IDs |
custom_header | string JSON object. Represents headers to be sent when making requests |
do_not_find | boolean Whether to consider the check as down if the content is present within the response |
dns_ips | Array of strings List of IP addresses to compare against returned DNS records |
dns_server | string FQDN or IP address of the nameserver to query |
enable_ssl_alert | boolean Whether to send an alert if the SSL certificate is soon to expire |
final_endpoint | string Specify where the redirect chain should end |
find_string | string String to look for within the response. Considered down if not found |
follow_redirects | boolean Whether to follow redirects when testing. Disabled by default |
host | string Name of the hosting provider |
include_header | boolean Include header content in string match search |
paused | boolean Whether the check should be run |
port | integer <int32> >= 0 Destination port for TCP checks |
post_body | string JSON object. Payload submitted with the request. Setting this updates the check to use the HTTP POST verb |
post_raw | string Raw HTTP POST string to send to the server |
regions | Array of strings List of regions on which to run checks. The values required for this
parameter can be retrieved from the |
status_codes_csv | string Comma separated list of status codes that trigger an alert |
tags | Array of strings List of tags |
timeout | integer <int32> [ 5 .. 75 ] The number of seconds to wait to receive the first byte |
trigger_rate | integer <int32> [ 0 .. 60 ] The number of minutes to wait before sending an alert |
use_jar | boolean Whether to enable cookie storage |
user_agent | string Custom user agent string set when testing |
Responses
Request samples
- cURL
- Go
curl -X PUT https://api.statuscake.com/v1/uptime/123 \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Example%20HTTP&check_rate=1800®ions[]=london®ions[]=paris"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Delete an uptime check
Deletes an uptime check with the given id.
path Parameters
test_id required | string Uptime check ID |
Responses
Request samples
- cURL
- Go
curl -X DELETE https://api.statuscake.com/v1/uptime/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Get all uptime check history
Returns a list of uptime check history results for a given id, detailing the runs performed on the StatusCake testing infrastruture.
The returned results are a paginated series. Alongside the response
data is a links
object referencing the current response document,
self
, and the next page in the series, next
.
path Parameters
test_id required | string Uptime check ID |
query Parameters
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of results to return per page |
before | integer <int64> >= 0 Only results created before this UNIX timestamp will be returned |
after | integer <int64> >= 0 Only results created after this UNIX timestamp will be returned |
Responses
Response Schema: application/json
required | Array of objects (UptimeTestHistoryResult) List of uptime check history results |
required | object (Links) |
object (Metadata) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/uptime/123/history \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "created_at": "2017-11-04T11:58:23+00:00",
- "location": "UKCON2",
- "performance": 579,
- "status_code": 200
}
], - "links": {
}
}
Get all uptime check periods
Returns a list of uptime check periods for a given id, detailing the creation time of the period, when it ended and the duration.
The returned results are a paginated series. Alongside the response
data is a links
object referencing the current response document,
self
, and the next page in the series, next
.
path Parameters
test_id required | string Uptime check ID |
query Parameters
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of uptime check periods to return per page |
before | integer <int64> >= 0 Only check periods created before this UNIX timestamp will be returned |
after | integer <int64> >= 0 Only check periods created after this UNIX timestamp will be returned |
Responses
Response Schema: application/json
required | Array of objects (UptimeTestPeriod) List of uptime check periods |
required | object (Links) |
object (Metadata) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/uptime/123/periods \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "created_at": "2013-02-25T14:42:41+00:00",
- "duration": 189000,
- "ended_at": "2013-02-25T14:45:50+00:00",
- "status": "down"
}
], - "links": {
}
}
Get all uptime check alerts
Returns a list of uptime check alerts for a given id.
The returned results are a paginated series. Alongside the response
data is a links
object referencing the current response document,
self
, and the next page in the series, next
.
path Parameters
test_id required | string Uptime check ID |
query Parameters
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of uptime alerts to return per page |
before | integer <int64> >= 0 Only alerts triggered before this UNIX timestamp will be returned |
after | integer <int64> >= 0 Only alerts triggered after this UNIX timestamp will be returned |
Responses
Response Schema: application/json
required | Array of objects (UptimeTestAlert) List of uptime check alerts |
required | object (Links) |
object (Metadata) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/uptime/123/alerts \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "status": "down",
- "status_code": 404,
- "triggered_at": "2013-02-25T14:42:41+00:00"
}
], - "links": {
}
}
The Contact Groups API provides methods to configure how StatusCake alerts are forwarded to the people that need to see them.
Get all contact groups
Returns a list of contact groups for an account.
query Parameters
page | integer <int32> >= 1 Default: 1 Page of results |
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of contact groups to return per page |
Responses
Response Schema: application/json
required | Array of objects (ContactGroup) List of contact groups |
required | object (Pagination) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/contact-groups \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "name": "Operations Team",
- "integrations": [
- "1",
- "2",
- "3"
], - "mobile_numbers": [
- "447712345678",
- "447987462344"
],
}
], - "metadata": {
- "page": 1,
- "per_page": 25,
- "page_count": 10,
- "total_count": 230
}
}
Create a contact group
Creates a contact group with the given parameters.
Request Body schema: application/x-www-form-urlencoded
name required | string Name of the contact group |
email_addresses | Array of strings List of email addresses |
integrations | Array of strings List of integration IDs |
mobile_numbers | Array of strings List of international format mobile phone numbers |
ping_url | string <uri> URL or IP address of an endpoint to push uptime events. Currently this only supports HTTP GET endpoints |
Responses
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/contact-groups \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Operations%20Team&email_addresses[][email protected]&email_addresses[][email protected]"
Response samples
- 201
- default
{- "data": {
- "new_id": "123"
}
}
Retrieve a contact group
Returns a contact group with the given id.
path Parameters
group_id required | string Contact group ID |
Responses
Response Schema: application/json
required | object (ContactGroup) | ||||||||||||
|
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/contact-groups/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": {
- "id": "123",
- "name": "Operations Team",
- "integrations": [
- "1",
- "2",
- "3"
], - "mobile_numbers": [
- "447712345678",
- "447987462344"
],
}
}
Update a contact group
Updates a contact group with the given parameters.
path Parameters
group_id required | string Contact group ID |
Request Body schema: application/x-www-form-urlencoded
name | string Name of the contact group |
email_addresses | Array of strings List of email addresses |
integrations | Array of strings List of integration IDs |
mobile_numbers | Array of strings List of international format mobile phone numbers |
ping_url | string <uri> URL or IP address of an endpoint to push uptime events. Currently this only supports HTTP GET endpoints |
Responses
Request samples
- cURL
- Go
curl -X PUT https://api.statuscake.com/v1/contact-groups/123 \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Operations%20Team&email_addresses[][email protected]&email_addresses[][email protected]"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Delete a contact group
Deletes a contact group with the given id.
path Parameters
group_id required | string Contact group ID |
Responses
Request samples
- cURL
- Go
curl -X DELETE https://api.statuscake.com/v1/contact-groups/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
The Maintenance Windows API provides methods to pause alerts from being sent for scheduled maintenance periods.
NOTE: the API endpoints concerned with maintenance windows will only work with accounts registed to use the newer version of maintenance windows. This version of maintenance windows is incompatible with the original version and all existing windows will require migrating to be further used. Presently a tool to automate the migration of maintenance windows is under development.
Get all maintenance windows
Returns a list of maintenance windows for an account.
query Parameters
page | integer <int32> >= 1 Default: 1 Page of results |
limit | integer <int32> [ 1 .. 100 ] Default: 25 The number of maintenance windows to return per page |
state | string Enum: "active" "paused" "pending" Maintenance window state |
Responses
Response Schema: application/json
required | Array of objects (MaintenanceWindow) List of maintenance windows |
required | object (Pagination) |
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/maintenance-windows \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "id": "123",
- "name": "Weekends",
- "end_at": "2020-10-25T23:59:59+00:00",
- "repeat_interval": "1w",
- "start_at": "2020-10-24T00:00:00+00:00",
- "state": "active",
- "tags": [
- "tag1",
- "tag2"
], - "tests": [
- "1",
- "2",
- "3",
- "4"
], - "timezone": "UTC"
}
], - "metadata": {
- "page": 1,
- "per_page": 25,
- "page_count": 10,
- "total_count": 230
}
}
Create a maintenance window
Creates a maintenance window with the given parameters.
Request Body schema: application/x-www-form-urlencoded
name required | string Name of the maintenance window |
end_at required | string <date-time> End of the maintenance window (RFC3339 format) |
repeat_interval | string (MaintenanceWindowRepeatInterval) Enum: "never" "1d" "1w" "2w" "1m" How often the maintenance window should occur |
start_at required | string <date-time> Start of the maintenance window (RFC3339 format) |
tags | Array of strings List of tags used to include matching uptime checks in this
maintenance window. At least one of |
tests | Array of strings List of uptime check IDs explicitly included in this maintenance
window. At least one of |
timezone required | string Standard timezone associated with this maintenance window |
Responses
Request samples
- cURL
- Go
curl -X POST https://api.statuscake.com/v1/maintenance-windows \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Weekends&start_at=2021-12-06T01:30:00Z&end_at=2021-07-11T06:00:00Z&repeat_interval=1w&tags[]=production&timezone=UTC"
Response samples
- 201
- default
{- "data": {
- "new_id": "123"
}
}
Retrieve a maintenance window
Returns a maintenance window with the given id.
path Parameters
window_id required | string Maintenance window ID |
Responses
Response Schema: application/json
required | object (MaintenanceWindow) | ||||||||||||||||||
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/maintenance-windows/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": {
- "id": "123",
- "name": "Weekends",
- "end_at": "2020-10-25T23:59:59+00:00",
- "repeat_interval": "1w",
- "start_at": "2020-10-24T00:00:00+00:00",
- "state": "active",
- "tags": [
- "tag1",
- "tag2"
], - "tests": [
- "1",
- "2",
- "3",
- "4"
], - "timezone": "UTC"
}
}
Update a maintenance window
Updates a maintenance window with the given parameters.
path Parameters
window_id required | string Maintenance window ID |
Request Body schema: application/x-www-form-urlencoded
name | string Name of the maintenance window |
end_at | string <date-time> End of the maintenance window (RFC3339 format) |
repeat_interval | string (MaintenanceWindowRepeatInterval) Enum: "never" "1d" "1w" "2w" "1m" How often the maintenance window should occur |
start_at | string <date-time> Start of the maintenance window (RFC3339 format) |
tags | Array of strings List of tags used to include matching uptime checks in this maintenance window |
tests | Array of strings List of uptime check IDs explicitly included in this maintenance window |
timezone | string Standard timezone associated with this maintenance window |
Responses
Request samples
- cURL
- Go
curl -X PUT https://api.statuscake.com/v1/maintenance-windows/123 \ -H "Authorization: Bearer ${API_TOKEN}" \ -d "name=Weekends&start_at=2021-12-06T01:30:00Z&end_at=2021-07-11T06:00:00Z&repeat_interval=1w&tags[]=production&timezone=UTC"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
Delete a maintenance window
Deletes a maintenance window with the given id.
path Parameters
window_id required | string Maintenance window ID |
Responses
Request samples
- cURL
- Go
curl -X DELETE https://api.statuscake.com/v1/maintenance-windows/123 \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- default
{- "message": "Something went wrong",
- "errors": {
- "field_name": [
- "field name is required",
- "field name is not a valid URL"
]
}
}
The Locations API returns details of our testing infrastructure. This may be used to gather information regarding IP addresses that may need to be allowed through firewalls for checks to be succesful.
Get all uptime monitoring locations
Returns a list of locations detailing server information for uptime monitoring servers. This information can be used to create further checks using the API.
query Parameters
region_code | string Server region code |
Responses
Response Schema: application/json
required | Array of objects (MonitoringLocation) List of monitoring locations | ||||||||||||
Array
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/uptime-locations \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "description": "United Kingdom, London - 5",
- "ipv4": "178.62.78.199",
- "ipv6": "2a03:b0c0:1:d0::5e:f001",
- "region": "United Kingdom / London",
- "region_code": "london",
- "status": "up"
}
]
}
Get all pagespeed monitoring locations
Returns a list of locations detailing server information for pagespeed monitoring servers. This information can be used to create further checks using the API.
query Parameters
location | string Alpha-2 ISO 3166-1 country code |
Responses
Response Schema: application/json
required | Array of objects (MonitoringLocation) List of monitoring locations | ||||||||||||
Array
|
Request samples
- cURL
- Go
curl https://api.statuscake.com/v1/pagespeed-locations \ -H "Authorization: Bearer ${API_TOKEN}"
Response samples
- 200
- default
{- "data": [
- {
- "description": "United Kingdom, London - 5",
- "ipv4": "178.62.78.199",
- "ipv6": "2a03:b0c0:1:d0::5e:f001",
- "region": "United Kingdom / London",
- "region_code": "london",
- "status": "up"
}
]
}