API Documentation | Maintenance

Schedule a maintenance window for your account, check, rule set or host.


_cid string
The primary key
A string containing a maintenance cid
item string
The identifier for the item under maintenance.
A string. Must correspond to the type, i.e. an account cid of the form '/account/1234' for an account maintenance, a rule set cid of the form '/rule_set/12345_tt_bytes' for a rule set maintenance, a host name like 'www3.internal.example.com' for a host maintenance, a check cid of the form '/check/1234' for a check maintenance. Required.
notes string
User notes for the maintenance
"Internal shutdown for hardware upgrade"
A string containing freeform text
severities array or string
The severities that are prevented from being triggered due to this maintenance window. Alerts of severities not included will still be triggered.
An unordered array containing numbers, each number being an integer between 1 and 5 inclusive, with no number being repeated. For convenience you may also pass in a string containing a CSV format string of these numbers (e.g. "1,2,3") - however, the field will always return an array object. Optional, will default to all severities, i.e. to [1,2,3,4,5].
number (zero or more times)
An associated severity
A number containing an integer between 0 and 5 inclusive
start number
When the maintenance window starts
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom). Once a maintenance window has begun this value cannot be changed. Optional, will default to the current time.
stop number
When the maintenance windows ends
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom). Must be greater than start time. Once the maintenance window has stopped this value cannot be altered. Optional, will default to five minutes after the start of the maintenance window.
tags array
An array of tags. The tags in the array are automatically sorted, deduplicated and transformed into their lowercase canonical form.
string (zero or more times)
An associated tag
A tag is just a string, with or without a colon, such as 'foo', 'bar', 'datacenter:london', or 'os:linux'. The part of the string before the colon is considered the category the tag is in; Tag strings without a colon will place the string in the 'uncategorized' category. Circonus will lowercase the contents of the string before storing it.
type string
A field that describes the thing that is undergoing maintenance.
A string containing either 'account', 'rule_set', 'check', or 'host'. Required.


Fetching Maintenance Windows

Fetching details for a maintenance window is as simple as performing a GET on the maintenance cid:

GET /maintenance/21846
{"severities":["1","2","3","4","5"],"tags":["datacenter:primary"],"notes":"Internal shutdown for hardware upgrade","type":"host","stop":1383694718,"item":"www2.internal.example.com","_cid":"/maintenance/21847","start":1383694418}

From this we can see some important things:

  • The maintenance started at 1383694418 (2013-11-05T23:33:38Z) and ended five minutes later at 1383694718 (2013-11-05T23:38:38Z)
  • The host www2.internal.example.com was in maintenance
  • Since all five severity levels are listed, any alert caused by a rule set based on the given host will be ignored

Creating Maintenance Windows

Creating a new maintenance window is as simple as making a HTTP POST request to /maintenance and passing JSON representing the new maintenance window:

POST /maintenance

This puts the entire account into maintenance for the next five minutes for all severities (since start defaults to the current time, and stop defaults to five minutes from the start time, and severities defaults to all five severities)

As is usual, the POST request returns the full JSON in the response (including the new maintenance window's cid)

You can always be more explicit about the start and stop times, specify a particular host (or check, or rule set), and you can add tags:

POST /maintenance
{"stop":1608858000,"tags":["datacenter:primary","maintenance tasks:one hour maintenance"],"type":"host","item":"www3.internal.example.com","start":1608854400}

When creating a maintenance window you can't start or stop the maintenance window in the past (though you can specify a time in the past, it'll just set the start time or stop time to the current time). And obviously you can't create a maintenance window that stops before it starts.

Updating Maintenance Windows

Before we demonstrate how to update a maintenance window, it's important to cover a few basic rules:

  • You can't change what the maintenance window refers to (the "item" or the "type")
  • Once a maintenance window has started you can't change its start time
  • Once a maintenance window has stopped you can't change its stop time

And obviously you can't break any of the rules specified when creating the maintenance window above.

Maintenance windows can be updated simply by using the PUT HTTP method with new field values:

PUT /maintenance/90210
{"tags":["datacenter:primary","maintenance tasks:two hour maintenance"],"stop":1608861600}

As is normal with Circonus the PUT method returns the full JSON of the updated maintenance window in response.

Listing Maintenance Windows

It's only possible to use the API to list maintenance windows that have not yet stopped (you can still use the API to extract details on past maintenance windows if you know the maintenance window's cid as demonstrated above)

You can list all not yet stopped maintenance windows for your account simply by requesting the /maintenance path with a simple GET request.

GET /maintenance
[{"start":1383695107,"item":"www2.internal.example.com","_cid":"/maintenance/21848","stop":1383695407,"type":"host","notes":"Internal shutdown for hardware upgrade","tags":[],"severities":["1","2","3","4","5"]},{"stop":1608861600,"item":"www3.internal.example.com","_cid":"/maintenance/21846","start":1608854400,"severities":["1","2","3","4","5"],"tags":["datacenter:primary","maintenance tasks:two hour maintenance"],"notes":null,"type":"host"}]

By applying filters you can restrict which maintenance windows are returned. For example, you can list only those maintenance windows that will be active at a particular time:

GET /maintenance?f_start_le=1608854500&f_stop_ge=1608854500
[{"notes":null,"type":"host","tags":["datacenter:primary","maintenance tasks:two hour maintenance"],"severities":["1","2","3","4","5"],"start":1608854400,"item":"www3.internal.example.com","_cid":"/maintenance/21846","stop":1608861600}]

Removing Maintenance Windows

If the maintenance window hasn't yet started then you can simply delete it by sending a HTTP DELETE request to the cid:

DELETE /maintenance/90210

If the maintenance window has already started then it's a matter of historical record and you can't delete it. If it hasn't stopped yet you can stop it right away by just updating it to stop at the current time:

PUT /maintenance/1402