StatusCake API (1.0.0-beta.3)

Introduction

The StatusCake API is organised around the features that we offer, with each feature providing a set of endpoints to perform operations on resources associated with your account.

Authentication

The StatusCake API uses API keys to authenticate requests. You can view and manage your API keys from the StatusCake account panel.

All API requests must be made over HTTPS. Calls made over plain HTTP will be redirected to the secure endpoint. API requests without authentication will fail unless otherwise stated in the documentation for the specific endpoint.

api_key

Security Scheme Type API Key
Header parameter name: Authorization

For example an authenticated request must contain an HTTP header of the form Authorization: Bearer <API KEY>.

NOTE: API keys must be kept private. In the event that is it exposed a new one should be generated.

Ratelimits

Ratelimits are applied to the API to prevent any one client degrading the overall system stability. StatusCake accounts without a subscription, or those on a free plan, can make a maximum of 10 requests per second. For accounts with a paid subscription this limit is increaed to 20 requests per second.

Authenticated requests are associated with the authenticated account, regardless of which API key was used. This means that all API clients share the same ratelimit quota per second when they authenticate with different API keys owned by the same StatusCake account.

When the ratelimit quota is exceeded all future requests will return an HTTP 429 status until the ratelimit window is reset.

Cross-Origin Resource Sharing

The StatusCake API features Cross-Origin Resource Sharing (CORS) implemented in compliance with the W3C specification. This allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone.

Errors

StatusCake uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted or malformed). Codes in the 5xx range indicate an error with StatusCake servers.

Handling Errors

Our client libraries raise exceptions, or return error types, depending on the control flow supported by the language. We recommend using these to write code that handles all possible API exceptions.

pagespeed

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) [ items ]

List of pagespeed checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/pagespeed \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

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

contact_groups_csv
string
Deprecated

Comma separated 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 -X POST https://api.statuscake.com/v1/pagespeed \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example&website_url=https://www.example.com&region=UK&check_rate=10"

Response samples

Content type
application/json
{
  • "data": {
    }
}

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 https://api.statuscake.com/v1/pagespeed/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

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

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

contact_groups_csv
string
Deprecated

Comma separated 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 -X PUT https://api.statuscake.com/v1/pagespeed/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example&region=UK&check_rate=10"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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 -X DELETE https://api.statuscake.com/v1/pagespeed/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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

Responses

Response Schema: application/json
required
Array of objects (PagespeedTestHistoryResult) [ items ]

List of pagespeed check history results

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/pagespeed/123/history \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

ssl

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) [ items ]

List of SSL checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/ssl \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

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
Array of integers <int32> [ items <int32 > ]

List representing when alerts should be sent (days). Must be exactly 3 numerical values

alert_at_csv
string
Deprecated

Comma separated 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

contact_groups_csv
string
Deprecated

Comma separated 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 -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

Content type
application/json
{
  • "data": {
    }
}

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 https://api.statuscake.com/v1/ssl/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

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
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_at_csv
string
Deprecated

Comma separated 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

contact_groups_csv
string
Deprecated

Comma separated 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 -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

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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 -X DELETE https://api.statuscake.com/v1/ssl/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

uptime

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. Pagination fields are only returned if the account associated with the API key is part of the uptime beta group.

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

nouptime
boolean
Default: false

Do not calculate uptime percentages for results

Responses

Response Schema: application/json
required
Array of objects (UptimeTestOverview) [ items ]

List of uptime checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/uptime \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

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

contact_groups_csv
string
Deprecated

Comma separated 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_ips_csv
string
Deprecated

Comma separated list of IP addresses to compare against returned DNS records

dns_server
string

Hostname 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 GET /v1/uptime-locations endpoint.

status_codes_csv
string

Comma separated list of status codes that trigger an alert

tags
Array of strings

List of tags

tags_csv
string
Deprecated

Comma separated 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 -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&regions[]=london&regions[]=paris"

Response samples

Content type
application/json
{
  • "data": {
    }
}

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 https://api.statuscake.com/v1/uptime/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

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

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

contact_groups_csv
string
Deprecated

Comma separated 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_ips_csv
string
Deprecated

Comma separated list of IP addresses to compare against returned DNS records

dns_server
string

Hostname 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 GET /v1/uptime-locations endpoint.

status_codes_csv
string

Comma separated list of status codes that trigger an alert

tags
Array of strings

List of tags

tags_csv
string
Deprecated

Comma separated 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 -X PUT https://api.statuscake.com/v1/uptime/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example%20HTTP&check_rate=1800&regions[]=london&regions[]=paris"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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 -X DELETE https://api.statuscake.com/v1/uptime/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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

Responses

Response Schema: application/json
required
Array of objects (UptimeTestHistoryResult) [ items ]

List of uptime check history results

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/uptime/123/history \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

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

Responses

Response Schema: application/json
required
Array of objects (UptimeTestPeriod) [ items ]

List of uptime check periods

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/uptime/123/periods \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

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

Responses

Response Schema: application/json
required
Array of objects (UptimeTestAlert) [ items ]

List of uptime check alerts

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/uptime/123/alerts \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

contact groups

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) [ items ]

List of contact groups

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/contact-groups \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

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

email_addresses_csv
string
Deprecated

Comma separated list of email addresses

integrations
Array of strings

List of integration IDs

integrations_csv
string
Deprecated

Comma separated list of integration IDs

mobile_numbers
Array of strings

List of international format mobile phone numbers

mobile_numbers_csv
string
Deprecated

Comma separated 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 -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

Content type
application/json
{
  • "data": {
    }
}

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 -X POST https://api.statuscake.com/v1/contact-groups/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

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

email_addresses_csv
string
Deprecated

Comma separated list of email addresses

integrations
Array of strings

List of integration IDs

integrations_csv
string
Deprecated

Comma separated list of integration IDs

mobile_numbers
Array of strings

List of international format mobile phone numbers

mobile_numbers_csv
string
Deprecated

Comma separated 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 -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

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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 -X DELETE https://api.statuscake.com/v1/contact-groups/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

maintenance windows

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) [ items ]

List of maintenance windows

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/maintenance-windows \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

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 and tags must be present in the request

tags_csv
string
Deprecated

Comma separated list of tags used to include matching uptime checks in this maintenance window. At least one of tests_csv and tags_csv must be present in the request

tests
Array of strings

List of uptime check IDs explicitly included in this maintenance window. At least one of tests and tags must be present in the request

tests_csv
string
Deprecated

Comma separated list of uptime check IDs explicitly included in this maintenance window. At least one of tests_csv and tags_csv must be present in the request

timezone
required
string

Standard timezone associated with this maintenance window

Responses

Request samples

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

Content type
application/json
{
  • "data": {
    }
}

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 https://api.statuscake.com/v1/maintenance-windows/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "tests": [
    ],
  • "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

tags_csv
string
Deprecated

Comma separated 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

tests_csv
string
Deprecated

Comma separated list of uptime check IDs explicitly included in this maintenance window

timezone
string

Standard timezone associated with this maintenance window

Responses

Request samples

curl -X POST 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

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

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 -X DELETE https://api.statuscake.com/v1/maintenance-windows/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

locations

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
best
boolean
Default: false

Return only locations with the least number of checks

location
string

Alpha-3 ISO 3166-1 country code

Responses

Response Schema: application/json
required
Array of objects (MonitoringLocation) [ items ]

List of monitoring locations

Request samples

curl https://api.statuscake.com/v1/uptime-locations \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ]
}

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
best
boolean
Default: false

Return only locations with the least number of checks

location
string

Alpha-2 ISO 3166-1 country code

Responses

Response Schema: application/json
required
Array of objects (MonitoringLocation) [ items ]

List of monitoring locations

Request samples

curl https://api.statuscake.com/v1/pagespeed-locations \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ]
}