API reference
Every operation an API key can call: sites and their checks, heartbeats, groups, maintenance windows, status pages and incidents, with the access each one needs and the fields to send.
Last reviewed
On this page
This page lists the operations that take an API key, grouped by what they work on. It shows each operation's method, address, the access a key needs and its parameters. The API keys page covers how to create and send a key, the limits and the error codes. The group monthly summary has its own page.
How to read an operation
- A value in braces, such as
{webpage_id}, is an id that you replace. - Query parameters are optional unless the list says required. A value outside the range shown for a parameter is refused with 422.
- Access needed names the lowest key that can call the operation. A key with less access gets
insufficient_scope. A read and write key includes everything a read key can do, and an admin key includes everything a read and write key can do. - Send a request body as JSON, with
Content-Type: application/json. - A site, heartbeat, group, window or incident that isn't in your workspace answers 404, the same as one that doesn't exist. An id that can't be an id answers 422.
Sites and checks
A site is one URL that OctoPing checks. The operations below add, change, pause and delete sites, queue a check, and read what the checks recorded. The checks reference explains what each check measures and how often it runs.
A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ comes back as https://example.com/, wherever the address appears in a response. A read and write key or an admin key gets the whole address. The query string of an address is returned as stored, so keep secrets out of it.
Create a site
Only url is required. The first check runs straight away. SSL certificate and WHOIS checks start on, and the other checks start off, the same as in the web app.
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
url | text | Yes | None | The address to monitor. A site is one URL, so example.com and example.com/checkout are two sites. Up to 200 characters, counted the way OctoPing stores the address, so an address with accented or other non-ASCII characters counts longer than it looks. |
http_check_interval | text | No | 5min | How often the uptime check runs. The plan decides which intervals it offers. One of 30s, 1min, 2min, 5min, 30min, 60min. |
ssl_check_interval | text | No | 1d | How often the certificate check runs. One of 1h, 6h, 12h, 1d, 7d. |
dns_check_interval | text | No | 6h | How often the DNS checks run. One of 1h, 6h, 12h, 1d. |
content_check_interval | text | No | 30min | How often the page content check runs. One of 5min, 15min, 30min, 1h, 6h, 1d. |
robots_check_interval | text | No | 6h | How often the robots.txt check runs. One of 1h, 6h, 12h, 1d, 7d. |
ip_check_interval | text | No | 6h | How often the IP and hosting check runs. One of 1h, 6h, 12h, 1d. |
whois_check_interval | text | No | 7d | How often the domain registration check runs. One of 1d, 7d, 14d, 30d. |
feature_ssl_monitoring | true or false | No | true | Turns the SSL certificate check on or off. |
feature_whois_monitoring | true or false | No | true | Turns the domain registration (WHOIS) check on or off. |
feature_mx_monitoring | true or false | No | false | Turns on the check of the domain's mail (MX) records. |
feature_nameserver_monitoring | true or false | No | false | Turns on the check of the domain's name server (NS) records. |
feature_content_monitoring | true or false | No | false | Turns on the page content check. |
feature_robots_monitoring | true or false | No | false | Turns on the robots.txt check. |
feature_ip_monitoring | true or false | No | false | Turns on the IP and hosting check. |
group_id | id or null | No | None | The group to put the site in. Leave it out for no group. |
is_active | true or false | No | true | Set it to false to create the site paused. |
response_time_threshold_ms | whole number or null | No | None | A response slower than this many milliseconds marks the site Degraded. From 0 to 2,147,483,647. |
custom_headers | object | No | Empty | Request headers to send with every uptime and content check, as an object of names and values. A value is printable ASCII text with no line breaks and with no space or tab at its start or end, and the request schema gives the other limits. A header the checks could not send is refused with 422. |
basic_auth_username | text | No | Empty | A username for HTTP Basic Authentication on every uptime and content check. Up to 255 characters. |
basic_auth_password | text | No | Empty | The password for that username. Up to 303 bytes when written as UTF-8, which is that many characters of plain ASCII text and fewer for other characters. |
curl -fsS -X POST -H "X-API-Key: $OCTOPING_API_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://example.com", "http_check_interval": "5min"}' \
https://octoping.com/api/webpagesThe answer is the new site, with its id. Use it in the other operations. The request is refused with 409 when the workspace already monitors that URL. Replace a site's settings with the same fields, or change some of them with a partial update, where every field is optional.
Check a site now
Check now queues a full check of the site and answers at once. Requests for the same site within 10 seconds of each other share one check, and the later ones say so in message. Read the results from the check history when the check finishes.
curl -fsS -X POST -H "X-API-Key: $OCTOPING_API_KEY" https://octoping.com/api/webpages/$SITE_ID/check-nowRead a site's outages
The answer lists the site's outages, newest first, with the total downtime and the longest outage. days sets how far back to look.
curl -fsS -H "X-API-Key: $OCTOPING_API_KEY" "https://octoping.com/api/webpages/$SITE_ID/outages?days=30"Manage sites
GEThttps://octoping.com/api/webpages
List sites
Access needed: Read only
Returns the sites in the workspace with their settings and current status, in items, and the total number of sites in count. Sites are ordered by group and then newest first. Use group_id to list one group, or ungrouped for sites that are in no group, and limit and offset to page through the list. Set status_checks_limit to include that many of each site's most recent checks (at most 100). A page holds at most 1000 sites, and a value outside the allowed range is refused with 422. A read key gets custom_headers as null, because a header value can hold the site's own credentials, and feature_config without its webhook_secret entry. A read and write key or an admin key gets both as stored. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
group_id(query, string, optional)limit(query, integer, optional, default100, 1 to 1000)offset(query, integer, optional, default0, 0 to 10000000)status_checks_limit(query, integer, optional, default0, 0 to 100)
POSThttps://octoping.com/api/webpages
Create a site
Access needed: Read and write
Starts monitoring a URL and returns the new site. Only url is required. Optional fields choose which checks run, how often, any custom request headers, and the group (group_id). The first check runs straight away. The request is refused with 409 when the workspace already monitors that URL, with 422 when the URL cannot be monitored, and with 403 when the plan does not offer the requested check interval (interval_limit or fast_check_limit). The request is refused with 403 and a code when the creating person's email address is not verified (email_unverified), when the workspace's trial or subscription has ended (trial_expired, subscription_ended or payment_required), or when the plan's allowance is full. The site allowance is monitor_limit. An address can be at most 200 characters long. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
GEThttps://octoping.com/api/webpages/{webpage_id}
Get a site
Access needed: Read only
Returns one site with its settings and its current status. A read key gets custom_headers as null, because a header value can hold the site's own credentials, and feature_config without its webhook_secret entry. A read and write key or an admin key gets both as stored. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
webpage_id(path, string, required)
PUThttps://octoping.com/api/webpages/{webpage_id}
Replace a site's settings
Access needed: Read and write
Applies every setting in the body, so fields you leave out return to their defaults. The site's URL cannot be changed: send its current URL. The site moves to another group only when group_id is included, and null removes it from its group. Use the partial update operation to change one setting. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
webpage_id(path, string, required)
PATCHhttps://octoping.com/api/webpages/{webpage_id}
Update some of a site's settings
Access needed: Read and write
Changes only the fields in the body and leaves the rest alone. Set is_active to false to pause monitoring and to true to resume it. Send group_id to move the site, or null to remove it from its group. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
webpage_id(path, string, required)
DELETEhttps://octoping.com/api/webpages/{webpage_id}
Delete a site
Access needed: Admin
Deletes the site together with everything recorded for it, including its alert settings. This cannot be undone.
webpage_id(path, string, required)
POSThttps://octoping.com/api/webpages/{webpage_id}/check-now
Check a site now
Access needed: Read and write
Queues an immediate check of the site, running every check enabled for it, and returns at once. Read the results from the check history when it finishes. Requests for the same site within 10 seconds of each other share one check, and the later ones say so in message. A paused site is not checked, and success is false. A workspace whose trial or subscription has ended is refused with 403 and a code (trial_expired, subscription_ended or payment_required).
webpage_id(path, string, required)
Read checks and history
GEThttps://octoping.com/api/webpages/{webpage_id}/daily-status
Get a site's status by day
Access needed: Read only
Returns an entry, oldest first, for each of the last days days (90 by default, at most 365) on which the site was checked, with the worst status of that day, the number of checks, the number of failures and the number of content changes. The status is error, partial, maintenance, changed or success, in that order of severity. Days without checks are left out.
webpage_id(path, string, required)days(query, integer, optional, default90, 1 to 365)
GEThttps://octoping.com/api/webpages/{webpage_id}/dns-checks
Get a site's latest DNS checks
Access needed: Read only
Returns the most recent check of the domain's mail (MX) records and of its name server (NS) records. When a check found a change, it also returns the previous records and which records were added and removed. A record type that has not been checked yet is left out.
webpage_id(path, string, required)
GEThttps://octoping.com/api/webpages/{webpage_id}/history
List a site's check history
Access needed: Read only
Returns the checks recorded for the site, newest first, with the total in total_count. Narrow the list with start_date and end_date, status_codes, downtime_only (failed checks outside maintenance windows) or changes_only (checks that found the page content changed). Without start_date the list, total_count and offset cover the 30 days before end_date, or before now when you send neither. Send start_date to read further back. Page through it with limit (50 by default) and offset. A page holds at most 500 rows, and a value outside the allowed range is refused with 422. A row has has_body set when it stored the page text, and the history entry operation returns that text. Setting include_content puts every row's page text in the list, which makes the response large, so a page that includes it holds at most 50 rows. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
webpage_id(path, string, required)limit(query, integer, optional, default50, 1 to 500)offset(query, integer, optional, default0, 0 to 10000000)start_date(query, string, optional)end_date(query, string, optional)status_codes(query, string, optional)downtime_only(query, boolean, optional, defaultfalse)changes_only(query, boolean, optional, defaultfalse)include_content(query, boolean, optional, defaultfalse)
GEThttps://octoping.com/api/webpages/{webpage_id}/history/{content_id}
Get one check's stored page
Access needed: Read only
Returns the page text stored by one check, and the text of the earlier stored check it was compared against, so you can show what changed. Only checks that stored the page have a body.
webpage_id(path, string, required)content_id(path, string, required)
GEThttps://octoping.com/api/webpages/{webpage_id}/ip-checks
List a site's hosting checks
Access needed: Read only
Returns the history of where the site is hosted, newest first, as items with the total in count: its IP addresses, network, and whether a CDN is in front of it. Page through it with limit (100 by default) and offset. A page holds at most 500 rows, and a value outside the allowed range is refused with 422.
webpage_id(path, string, required)limit(query, integer, optional, default100, 1 to 500)offset(query, integer, optional, default0, 0 to 10000000)
GEThttps://octoping.com/api/webpages/{webpage_id}/ip-checks/latest
Get a site's latest hosting check
Access needed: Read only
Returns the most recent hosting check. When it found a change, it also returns the previous addresses and network. Answers 404 when the site has not been checked yet.
webpage_id(path, string, required)
GEThttps://octoping.com/api/webpages/{webpage_id}/outages
List a site's outages
Access needed: Read only
Returns the site's outages over the last days days (30 by default, at most 90), newest first, with the total downtime and the longest outage. items holds at most 100 outages and count is always the true total. Time inside a maintenance window is planned downtime and is never an outage.
webpage_id(path, string, required)days(query, integer, optional, default30)
GEThttps://octoping.com/api/webpages/{webpage_id}/probe-checks
List a site's checks from other locations
Access needed: Read only
Returns the checks made from OctoPing's regional locations, newest first, with totals for each region over the last 30 days in regions. Narrow the list with region, start_date and end_date. Without start_date the list and total_count cover the 30 days before end_date, or before now when you send neither. To read a longer period, send start_date as well. The totals in regions always cover the last 30 days. limit (200 by default) and offset apply to each region separately. A page holds at most 500 rows, and a value outside the allowed range is refused with 422.
webpage_id(path, string, required)limit(query, integer, optional, default200, 1 to 500)offset(query, integer, optional, default0, 0 to 10000000)region(query, string, optional)start_date(query, string, optional)end_date(query, string, optional)
GEThttps://octoping.com/api/webpages/{webpage_id}/robots-check
Get a site's latest robots.txt check
Access needed: Read only
Returns the most recent robots.txt check: how robots.txt was answered, what it says about each search engine and AI crawler for the monitored address, what the page itself says about being indexed, and what changed since the check before. robots.txt is a request to crawlers, so this does not show whether a firewall blocks them. Answers 404 when the site has not been checked yet.
webpage_id(path, string, required)
GEThttps://octoping.com/api/webpages/{webpage_id}/ssl-check
Get a site's latest certificate check
Access needed: Read only
Returns the most recent SSL certificate check: the issuer, the subject, when the certificate is valid and how many days are left. Answers 404 when the site has not been checked yet.
webpage_id(path, string, required)
GEThttps://octoping.com/api/webpages/{webpage_id}/ssl-checks
List a site's certificate checks
Access needed: Read only
Returns the site's SSL certificate checks, newest first, as items with the total in count. Page through them with limit (100 by default) and offset. A page holds at most 500 rows, and a value outside the allowed range is refused with 422. Use it to see when the certificate changed.
webpage_id(path, string, required)limit(query, integer, optional, default100, 1 to 500)offset(query, integer, optional, default0, 0 to 10000000)
GEThttps://octoping.com/api/webpages/{webpage_id}/stats
Get a site's summary numbers
Access needed: Read only
Returns the number of checks, the uptime percentage and the average response time over the last 30 days, when the site was last checked and last changed, and what each location that checks the site sees right now. For outages and downtime, use the outages operation. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
webpage_id(path, string, required)
GEThttps://octoping.com/api/webpages/{webpage_id}/status-checks
List a site's recent checks
Access needed: Read only
Returns the latest checks made from OctoPing's own checker, newest first, with the status code and response time of each. limit sets how many (50 by default, at most 500). A check made inside a maintenance window has in_maintenance set, and a failure that every other checking location contradicted has contradicted set.
webpage_id(path, string, required)limit(query, integer, optional, default50, 1 to 500)
GEThttps://octoping.com/api/webpages/{webpage_id}/whois-check
Get a site's latest domain registration check
Access needed: Read only
Returns the most recent domain registration check: the registrar, the creation, update and expiry dates, the days left, the name servers, the domain statuses and DNSSEC. When it found a change, it also returns the previous values. Answers 404 when the site has not been checked yet.
webpage_id(path, string, required)
Heartbeats
A heartbeat is a monitor for a job that has no URL to check. The job calls the heartbeat's ping URL, and OctoPing alerts when a ping doesn't arrive in time. These operations manage the heartbeat itself. The heartbeat ping page covers the ping URL, which needs no key. A read key gets ping_url as null. A read and write key or an admin key gets the address.
Create a heartbeat
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name | text | Yes | None | A label for the job, such as Nightly backup. Up to 255 characters. |
description | text | No | Empty | What the job does. |
expected_interval | text | No | 5min | How often the job should ping. One of 1min, 5min, 10min, 30min, 1h, 6h, 12h, 1d. |
grace_period_seconds | whole number | No | 300 | How many seconds OctoPing waits after the interval before it alerts. From 0 to 3,600. |
is_active | true or false | No | true | Set it to false to create the heartbeat paused. |
Updating a heartbeat takes the same fields.
curl -fsS -X POST -H "X-API-Key: $OCTOPING_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Nightly backup", "expected_interval": "1d", "grace_period_seconds": 600}' \
https://octoping.com/api/heartbeatsHeartbeat operations
GEThttps://octoping.com/api/heartbeats
List heartbeat monitors
Access needed: Read only
Returns the workspace's heartbeat monitors, newest first, as items with the total in count. Each has the ping URL your job calls. Page through the list with limit (100 by default) and offset. A page holds at most 500 rows, and a value outside the allowed range is refused with 422. A read key gets ping_url and secret_key as null, because anyone who holds the ping URL can send pings for the monitor. A read and write key or an admin key gets both.
limit(query, integer, optional, default100, 1 to 500)offset(query, integer, optional, default0, 0 to 10000000)
POSThttps://octoping.com/api/heartbeats
Create a heartbeat monitor
Access needed: Read and write
Creates a heartbeat monitor and returns it with the ping URL your job calls on every run. name is required. expected_interval and grace_period_seconds say how long the monitor waits before it alerts, and the grace period is 0 to 3600 seconds. Heartbeats have their own allowance, separate from sites (heartbeat_limit). The request is refused with 403 and a code when the creating person's email address is not verified (email_unverified), when the workspace's trial or subscription has ended (trial_expired, subscription_ended or payment_required), or when the plan's allowance is full. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
GEThttps://octoping.com/api/heartbeats/{heartbeat_id}
Get a heartbeat monitor
Access needed: Read only
Returns one heartbeat monitor with its ping URL, its expected interval and grace period, when it was last pinged and whether it is healthy. A read key gets ping_url and secret_key as null, because anyone who holds the ping URL can send pings for the monitor. A read and write key or an admin key gets both.
heartbeat_id(path, string, required)
PUThttps://octoping.com/api/heartbeats/{heartbeat_id}
Update a heartbeat monitor
Access needed: Read and write
Applies the name, description, expected interval, grace period and active state in the body. The ping URL does not change. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
heartbeat_id(path, string, required)
DELETEhttps://octoping.com/api/heartbeats/{heartbeat_id}
Delete a heartbeat monitor
Access needed: Admin
Deletes the monitor with its pings and alert settings. Its ping URL stops working. This cannot be undone.
heartbeat_id(path, string, required)
GEThttps://octoping.com/api/heartbeats/{heartbeat_id}/pings
List a heartbeat's pings
Access needed: Read only
Returns the pings the monitor has received, newest first, as items with the total in count: when each arrived, the address it came from, its user agent and any payload. Page through them with limit (100 by default) and offset. A page holds at most 500 rows, and a value outside the allowed range is refused with 422.
heartbeat_id(path, string, required)limit(query, integer, optional, default100, 1 to 500)offset(query, integer, optional, default0, 0 to 10000000)
GEThttps://octoping.com/api/heartbeats/{heartbeat_id}/stats
Get a heartbeat's summary numbers
Access needed: Read only
Returns the number of pings received, when the last one arrived, whether the monitor is healthy and its uptime percentage over the last 30 days. The uptime is null until a full interval has passed.
heartbeat_id(path, string, required)
PATCHhttps://octoping.com/api/heartbeats/{heartbeat_id}/toggle
Pause or resume a heartbeat monitor
Access needed: Read and write
Switches the monitor between active and paused and returns it. A paused monitor is not checked for missed pings, so it sends no alerts.
heartbeat_id(path, string, required)
Groups
A group organizes sites, and an agency usually keeps one group for each client. Deleting a group deletes none of its sites. A group's month as JSON is on the group monthly summary page.
Creating a group and renaming one take the same field.
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name | text | Yes | None | The group's name. It is unique in the workspace, so a name that another group already uses is refused with 409. Up to 100 characters. |
Group operations
GEThttps://octoping.com/api/groups
List groups
Access needed: Read only
Returns the workspace's groups, which organise sites, with their name and order.
POSThttps://octoping.com/api/groups
Create a group
Access needed: Read and write
Creates a group with the given name. Group names are unique in a workspace, and a name that is already used is refused with 409. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
PUThttps://octoping.com/api/groups/{group_id}
Rename a group
Access needed: Read and write
Changes the group's name. A name that is already used by another group is refused with 409. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
group_id(path, string, required)
DELETEhttps://octoping.com/api/groups/{group_id}
Delete a group
Access needed: Admin
Deletes the group. The sites in it are not deleted, they become ungrouped.
group_id(path, string, required)
Maintenance windows
A maintenance window holds back down alerts for the sites and heartbeats it covers and keeps the time out of uptime. Certificate, domain and change alerts still send. The maintenance windows page describes how a window behaves at its edges and on a status page.
Schedule a window
A request needs a name, a start date, a start time and a duration, and at least one site or heartbeat. The date and time are local to timezone. A window's name is shown on public status pages.
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name | text | Yes | None | The window's name, up to 120 characters once repeated spaces are removed. It is shown on public status pages. |
start_date | text | Yes | None | The first day of the window, as YYYY-MM-DD, in the window's time zone. |
start_time | text | Yes | None | The time the window starts, as HH:MM, in the window's time zone. |
duration_minutes | whole number | Yes | None | How long the window lasts, in minutes. A read and write key can schedule up to 24 hours and an admin key up to 7 days. |
timezone | text | No | UTC | An IANA time zone name, such as Europe/Madrid. The window follows its daylight saving changes. |
recurrence | text | No | once | once for a single window or weekly for one that repeats. |
weekdays | list of whole numbers | No | None | For a weekly window, the days it runs on, where 0 is Monday and 6 is Sunday. |
repeat_until | text or null | No | None | For a weekly window, the last day it can start. Leave it out and the window repeats with no end date. |
webpage_ids | list of ids | No | None | The sites the window covers. Up to 500 entries. |
heartbeat_ids | list of ids | No | None | The heartbeats the window covers. Up to 500 entries. |
Maintenance window operations
GEThttps://octoping.com/api/maintenance-windows
List maintenance windows
Access needed: Read only
Returns the workspace's maintenance windows: those in progress first, then scheduled ones with the soonest first, then finished ones with the newest first. Pass webpage_id or heartbeat_id to keep only the windows that cover that monitor. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
webpage_id(query, string, optional)heartbeat_id(query, string, optional)
POSThttps://octoping.com/api/maintenance-windows
Create a maintenance window
Access needed: Read and write
Schedules planned maintenance for the sites and heartbeat monitors in webpage_ids and heartbeat_ids, at least one of which is required. recurrence is once or weekly, and weekly windows take weekdays and an optional repeat_until. start_date and start_time are local to timezone. start_date and repeat_until must fall in the years 2000 to 2999. While a window runs, the monitors it covers send no down alerts, and the time counts neither against uptime nor as an outage. Certificate, domain and change alerts still send. The window's name is shown on public status pages and is at most 120 characters once repeated spaces are removed. A read and write key can schedule windows of up to 24 hours and an admin key up to 7 days. A request that cannot be accepted is refused with 422 and a code.
GEThttps://octoping.com/api/maintenance-windows/upcoming
List upcoming maintenance
Access needed: Read only
Returns the occurrences in progress now and those starting within days days (1 to 35, 7 by default), soonest first, at most 200 of them. Pass webpage_id or heartbeat_id to keep only those that cover that monitor.
days(query, integer, optional, default7)webpage_id(query, string, optional)heartbeat_id(query, string, optional)
GEThttps://octoping.com/api/maintenance-windows/{window_id}
Get a maintenance window
Access needed: Read only
Returns one window with its schedule, the sites and heartbeat monitors it covers, its state, and its current and next occurrence. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
window_id(path, string, required)
PUThttps://octoping.com/api/maintenance-windows/{window_id}
Update a maintenance window
Access needed: Read and write
Changes the fields in the body and leaves the others as they are. Send null for repeat_until to make a weekly window open ended. The dates follow the same limits as when a window is created. The occurrence in progress is retimed or ended, finished occurrences are kept as history, and later ones follow the new schedule.
window_id(path, string, required)
DELETEhttps://octoping.com/api/maintenance-windows/{window_id}
Delete a maintenance window
Access needed: Read and write
Deletes the window and its occurrences. The monitors it covered leave maintenance at once.
window_id(path, string, required)
POSThttps://octoping.com/api/maintenance-windows/{window_id}/end-now
End a maintenance window now
Access needed: Read and write
Ends the occurrence in progress. Later occurrences of a weekly window stay scheduled. Refused with 409 and the code not_in_progress when nothing is running.
window_id(path, string, required)
Status pages and incidents
A key reads status pages and manages their incidents. Creating or editing a page, its items and its custom domain stays in the web app. The status pages page describes what a page shows and how an incident moves from its first update to resolution.
Open an incident
Opening an incident creates it together with its first update, which is the body. If the page is published, the incident shows on it at once.
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
title | text | Yes | None | A short headline for the incident. Up to 255 characters. |
body | text | Yes | None | The text of the first update. |
impact | text | No | minor | How serious the incident is: none, minor, major or critical. |
status | text | No | investigating | Where the incident stands: investigating, identified, monitoring or resolved. |
started_at | text or null | No | None | When the incident began, as an ISO 8601 date and time with a UTC offset. Leave it out to start it now, or set an earlier time to backdate it. |
affected_items | list | No | Empty list | The components the incident affects, each as an object with item_id and impact_status. The item id is the id of an item on the page, from the get status page operation. List each component once, because a repeat is refused with 422. Up to 500 entries. The impact status is degraded_performance, partial_outage or major_outage. |
notify_subscribers | true or false | No | false | Set it to true to also email the first update to the page's subscribers. A page can email at most 20 updates in any 24 hours, counted over all its incidents, and a workspace at most 100 across all its pages. One more is refused with 409 and the code notify_daily_limit_reached. It is also refused with 409 when emailing subscribers isn't available. Nothing is created when it is refused, and the same request without this field is accepted. |
curl -fsS -X POST -H "X-API-Key: $OCTOPING_API_KEY" -H "Content-Type: application/json" \
-d '{"title": "Checkout is slow", "body": "We are looking into it.", "impact": "minor", "status": "investigating"}' \
https://octoping.com/api/status-pages/$STATUS_PAGE_ID/incidentsPost an update
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
body | text | Yes | None | The text of the update. |
status | text or null | No | None | Moves the incident to this status: investigating, identified, monitoring or resolved. Resolving it records when it was resolved. |
notify_subscribers | true or false | No | false | Set it to true to also email this update to the page's subscribers. One incident can email 10 updates, and one more is refused with 409 and the code notify_limit_reached. A page can email at most 20 updates in any 24 hours, counted over all its incidents, and a workspace at most 100 across all its pages. One more is refused with 409 and the code notify_daily_limit_reached. Nothing is posted when it is refused, and the same request without this field is accepted. |
Status page operations
GEThttps://octoping.com/api/status-pages
List status pages
Access needed: Read only
Returns the workspace's status pages with their name, address, whether they are published, and their custom domain settings. Creating and editing pages is done in the web app.
GEThttps://octoping.com/api/status-pages/{status_page_id}
Get a status page
Access needed: Read only
Returns one status page with its settings and the sites and heartbeat monitors it shows. Creating and editing pages is done in the web app. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
status_page_id(path, string, required)
GEThttps://octoping.com/api/status-pages/{status_page_id}/incidents
List a status page's incidents
Access needed: Read only
Returns every incident on the page, most recent first. The list is not paged. Use the get operation for an incident's timeline.
status_page_id(path, string, required)
POSThttps://octoping.com/api/status-pages/{status_page_id}/incidents
Create an incident
Access needed: Read and write
Creates an incident together with its first update, which is the body. If the page is published, the incident shows on it at once. impact and status set how serious it is and where it stands, affected_items names the components it affects, and started_at backdates it, within the years 2000 to 2999. Set notify_subscribers to also email the first update to the page's subscribers. That is refused with 409 and the code notify_unavailable when emailing subscribers is not available. A page can email at most 20 updates in any 24 hours, counted over all its incidents, and a workspace at most 100 across all its pages. One more is refused with 409 and the code notify_daily_limit_reached. Nothing is created when it is refused, and the same request without notify_subscribers is accepted. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
status_page_id(path, string, required)
GEThttps://octoping.com/api/status-pages/{status_page_id}/incidents/{incident_id}
Get an incident
Access needed: Read only
Returns one incident with its full timeline of updates, the components it affects, and how many more updates can be emailed to subscribers. A read key gets a site's address without any user name and password written into it, so https://user:pass@example.com/ is returned as https://example.com/. The rest of the address, including its query string, is returned as stored, and a read and write key or an admin key gets the whole address.
status_page_id(path, string, required)incident_id(path, string, required)
PUThttps://octoping.com/api/status-pages/{status_page_id}/incidents/{incident_id}
Edit an incident
Access needed: Read and write
Changes the incident's title, impact, start time and affected components. To change its status, post an update instead. The start time is limited to the years 2000 to 2999. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
status_page_id(path, string, required)incident_id(path, string, required)
DELETEhttps://octoping.com/api/status-pages/{status_page_id}/incidents/{incident_id}
Delete an incident
Access needed: Admin
Deletes the incident and its timeline, and removes it from the public page. This cannot be undone.
status_page_id(path, string, required)incident_id(path, string, required)
POSThttps://octoping.com/api/status-pages/{status_page_id}/incidents/{incident_id}/updates
Post an incident update
Access needed: Read and write
Adds an update to the incident's timeline. Include status to move the incident to that status, and resolving it records when it was resolved. Set notify_subscribers to also email the update to the page's subscribers. An incident can email at most 10 updates, and one more is refused with 409 and the code notify_limit_reached. A page can email at most 20 updates in any 24 hours, counted over all its incidents, and a workspace at most 100 across all its pages. One more is refused with 409 and the code notify_daily_limit_reached. The code is notify_unavailable when emailing subscribers is not available. Nothing is posted when it is refused, and the same request without notify_subscribers is accepted. A value that is longer than its field holds, or outside its range, is refused with 422. The limits are in the request schema.
status_page_id(path, string, required)incident_id(path, string, required)
Related
- DocsAPI overviewHow the OctoPing API works: the endpoints that need no key, the operations that take an API key, how to authenticate, a first request, the limits and the errors.
- DocsAPI keysCreate an API key, choose what it can do, send it in the X-API-Key header, and read about its limits, error codes, rotation, revocation and what happens when people change roles or a workspace pauses.
- DocsGroup monthly summaryRead one client group's month as JSON: uptime, outages with their cause, certificate and domain expiry, and DNS, hosting and content changes, with every field explained.
- DocsChecks referenceWhat each of the eight checks and heartbeats measures, whether it is on by default, how often it runs and what counts as a failure or a change.
- DocsMaintenance windowsSchedule planned work so down alerts are held back and the time stays out of uptime, with the rules for the edges of a window and how it shows on a status page.
- DocsStatus pagesCreate, brand and publish a status page, choose what it shows and run an incident from first update to resolution.