API Documentation

How to Use the Circonus API

REST

The Circonus API is a REST based API. Accessing and modifying a resource is achieved by using HTTP verbs on the URL that corresponds to the Circonus ID (cid) for that resource.

API base URL: https://api.circonus.com/v2/

A typical cid includes both a token representing the type of resource and an opaque identifier associated with the exact resource instance. You can use the resource type token independently from the identifier to either create new resources or search for existing resources.

Authentication

In order to access the Circonus API you must authenticate with a valid API token and App Name. There are two ways to achieve this: using basic authentication or custom Circonus headers.

Getting a Token and App Name

Tokens can be created and managed in the API Tokens section of your user profile. If your token has a "Default App State" of "Pending" your app will need to go through a 3 step verification process: creating your token, submitting your application request, and approving each token/application request combination.

If your token has a "Default App State" of "Allow" then any incoming request with any name for that token will be automatically allowed in. You can then manage the state after the app is created in the API Tokens section of your user profile.

A "Default App State" of "Deny" will keep track of new apps that attempt to use the token but it will not allow any access to any unknown app.

  1. Go to your user profile by clicking on your name in the upper right corner of the page.
  2. On the left side of the page, click "API Tokens."
  3. In the dropdown, select the account whose tokens you want to manage.
  4. Click the (+) button above the page; a new token will be created.
  5. Using your API client, make a request using the desired App Name. This initial request will fail with an HTTP 401 if your "Default App State" is "Pending", and it will fail with an HTTP 403 if your "Default App State" is "Deny". (please also note that app names in the format circonus:STRING:STRING are reserved for internal use)
  6. Reload the "API Tokens" page and click "allow" to authorize the newly logged application/token combination for "Default App State" other than "Allow".

Errors

When an API request is successful, a 2XX status code is returned (typically 200, but other codes like 204 are returned when applicable). When an error occurs, a status code in the 4XX or 5XX range is returned. When an error is returned, the body of the response contains a JSON object that provides more information on the error. The properties of this object are as follows:

code

The error code indicating the type of error. These are hierarchical, where each part of the code (separated by a period) is a more specific indication of the error. Similar to the way object polymorphism works, your client should be able to handle more specific versions of errors the way it can handle more general errors simply by ignoring rightmost sections of the error code. For example, the error "InputError.InvalidValue.MissingData" indicates that there is an "InputError," more specifically an "InvalidValue," and even more specifically that there is "MissingData."

explanation

A human readable description of what the error code actually means.

message

A human readable description that hopefully explains why this error happened this particular time. For example, a constraint violation error might tell you which part of the passed data structure does not match the type constraint.

reference

An internal code that may be useful to include in any Circonus support email requests. You should not rely on the value of this field in any way.

tag

A semi-unique code that identifies your API request. This may be useful to include in any Circonus support email requests. This contains the same value as the "X-Circonus-Tag" HTTP header.

server

The server that served your request. This may be useful to include in any Circonus support email requests. This contains the same value as the "X-Circonus-Server" HTTP header.

Searching

When listing resources via the API, you can narrow the results by including search terms with your GET call. Simply pass the "CGI" style parameter ?search= followed by your search term(s) in the URL. For example, performing a GET on:

/check?search=(check_bundle_id:123456)

where check_bundle_id is the field name and 123456 is the value, would retrieve all Check objects belonging to Check Bundle 123456.

You can search on multiple fields (AND'd together) by including more terms in parentheses:

/check?search=(name:123456)(host:prod.*.com)

Note: The search syntax varies, depending on the specific object type. The differences are explained below.

Metrics search differs from all other endpoints, and makes use of the new V3 Search syntax. When applying a search query on the /metric endpoint, a different format and set of terms is used.

/metric?search=and(__name:available,__check_target:10.9.8.7)

would retrieve all metrics named "available" where the target of the check is 10.9.8.7.

As with other endpoints, it does support paged results (see below, "Search Ordering and Paging").

The UI has an Metrics Explorer that can help you construct metric search queries.

Searching other object types via the API uses the V2 search format. For example, if you search for checks using the /checks section in the UI, you can use that search string in the API and get the same objects back.

For a reference on how to specify V2 search terms, including a list of search fields available for each API endpoint, please visit the V2 Search Documentation. The Advanced Search Builder is an excellent tool to learn how to devise text-based search queries for the API.

Search Paging and Ordering

If your search query returns a large number of objects, you can page through them by making subsequent GET calls including some result navigation parameters:

size (items per page)
By default, API search results are capped at 20 objects at a time. You can specify a different limit (up to 1000) by appending the "size" parameter to your query string:
/check?search=(host:prod.*.com)&size=10...
from (offset)
To move to the next page in your result set, specify the "from" parameter to correspond to size * (page - 1). For example, if you are limiting your results to 10 items per page, you can fetch the first three pages of the results as follows:
/check?search=(host:prod.*.com)&size=10&from=0...
/check?search=(host:prod.*.com)&size=10&from=10...
/check?search=(host:prod.*.com)&size=10&from=20...
order (sort order)
To assure proper paging, you should sort your results on one of the fields using the "order" parameter:
/check?search=(host:prod.*.com)&size=10&from=10&order=name
dir (sort direction)
By default, sorted results are in ascending order. You can change this behavior by including dir=desc in your query:
/check?search=(host:prod.*.com)&size=10&from=10&order=name&dir=desc

When navigating through paged results, Circonus will include a response header:

X-Circonus-More-Items: true

to indicate that more results are available. The absence of this header indicates you have reached the last page of search results.

Filtering

In addition to searching, when listing resources, Circonus allows you to filter the output to only contain resources that meet a certain criteria. This is achieved by passing an additional "CGI" style parameter in the URL that constrains the value of a particular field of that resource, where the parameter name should be set to the field name you want to constrain on prepended with "f_" and the value should be the constraining value. For example /annotation?f_category=sale would filter the list to only include annotations that had the category "sale."

Note on filtering, this feature is deprecated and will be removed. Please see the section on API searching.

Circonus supports the use of various suffixes to the field name in order to control how the field is constrained:

no suffix
Without a suffix the list will be filtered to contain entires for which the named field exactly equals the passed value. For example, /annotation?f_title=Deployment will only include annotations with a title of "Deployment" in the listing.
_lt
Less Than. Lists entires for which the named field value is less than the passed value. For example, /annotation?f_stop_lt=1356998400 will only include annotations stopping before 2013.
_ge
Greater Than or Equal. Lists entires for which the named field value is greater than or equal to the passed value. For example, /annotation?f_start_ge=1356998400 will only include annotations started since the start of 2013.
_le
Less Than or Equal. Lists entires for which the named field value is less than or equal to the passed value. For example, /annotation?f_start_ge=1356393600&f_start_le=1356479999 will only include annotations starting on Christmas Day 2012.
_gt
Greater Than. Lists entires for which the named field value is greater than the passed value. For example, /annotation?f_stop_gt=1356479999 will only include annotations that didn't stop until after Christmas Day 2012.
_has
Has Element. List entries for which the named multivalue field contains the passed value. For example, /maintenance?f_severities=1&f_severities=2 will only include maintenance windows that prevent both severity 1 and severity 2 alerts being triggered.
_wildcard
String Matches Wildcard Expression. List entries for which the field contains a value that matches the passed wildcard expression. In a wildcard expression the character "*" will match any number of characters (including zero) and "?" will match any single character. The whole string value of the field must be matched. For example, /graph?f_title_wildcard=Summary* would only include graphs that have a title starting with "Summary"

Versions

Circonus continues to gain new features and capabilities and over time these are made accessible over the Circonus API. Great care is taken by the Circonus developers to ensure that no incompatible changes are made to the API. Changes that would not be considered incompatible (and thus do not involve releasing a new version of the API) include:

When a incompatible change must be made, Circonus will release a new version of the API. Previous versions of the API will remain accessible via version-specific URLs. For example, in addition to accessing the current user by performing a GET on /user/current (a URL that will always use the latest version of the API) you can also access that user by using the version specific URL /v2/user/current

Rate Limiting

Circonus implements a rate limit on the number of requests we will process over a given time. If you are receiving a 429 status back from our servers, the client or clients should slow down their processing and try again.