Circonus | API Documentation

Loading... Loading Image

You are currently running Firebug, which can have a significant impact on Circonus performance.

Please disable Firebug to experience full UX awesomeness.

How to Use the Circonus API

Note: this info pertains to the new (current) version of the Circonus API. If you're still using version 1 (hopefully temporarily, since it's now deprecated and will be removed at some point in the future), check out the version 1 documentation.

REST

The Circonus API is a REST based API. Accessing and modifying a resource is achived 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/

  • To Read a Resource:
    Perform a GET on the resource cid URL; this request will return a representation of the current state of the resource as a JSON object. For example, doing a GET on /user/current will return a JSON object representing the user associated with the current authorization token.
  • To Delete a Resource:
    Perform a DELETE on the resource cid URL. For example, doing a DELETE on /graph/123456 will delete the graph associated with that cid.
  • To Update a Resource:
    Perform a PUT on the resource cid URL; this will update the resource with any data passed in the body of the request. The body of the request must be a JSON object containing the fields that should be updated (fields not passed will retain their existing values.) This request will return a representation of the new state of the resource as a JSON object. For example, doing a PUT containing { "firstname": "Gonzo" } on /current/user will change the first name of the user associated with the current authorization token.

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.

  • To Create a Resource:
    Perform a POST on the resource type URL; this will create a new resource using any data passed in the body of the request. As with updating, the request body must be a JSON object containing the mandatory fields (and any or all optional fields). Any optional fields that are not included will be given their default values. This request will return a respresentation of the state of the new resource as a JSON object. For example, doing a POST containing { "title": "Big Bird's Birthday", "description": "Big Bird is six (again)", "start": 1332216000, "stop": 1332302399 } on /annotation will create a new annotation.
  • To List Resources:
    Perform a GET on the resource type URL; this will list all resources of the specified type. Some types may be filtered by passing specific parameters. For example, doing a GET on /user will list all users on the account associated with the current authorization token.

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.

  • Basic Authentication
    Standard basic authentication may be used. The App Name should be the username, and the API token should be the password. Curl makes this simple: curl --user ExampleApp:A80BCD8F-F9A0-4264-BA68-1DCF5C0A98F2 https://api.circonus.com/v2/user/current, as do most graphical web browsers. However, be careful to use "Incognito" or "Private Browsing" mode to prevent them from caching your credentials and exposing you to cross site scripting attacks.
  • Custom Circonus Headers
    The Circonus API also allows you to authenticate via custom HTTP headers. You can use this when your client is unable to handle the encoding of the basic authentication for you.

    Custom HTTP request headers:

    X-Circonus-Auth-Token: <token_string>
    X-Circonus-App-Name: <app_name>

Getting a Token and App Name

Tokens can be created and managed in the API Tokens section of your user profile. Tokens must go through a 3-step initialization process: creating your token, submitting your application request, and approving each token/application request combination.

  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 (note: this initial request will fail).
  6. Reload the "API Tokens" page and click "allow" to authorize the newly logged application/token combination.

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

Filtering Listings (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."

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:

  • Adding an optional field to a JSON object.
  • Adding a new resource type.
  • Adding a filter parameter that you can pass when performing a GET.
  • Changing an error message to be more specific (e.g. changing "BadNoise.SqueekySaxophone" to "BadNoise.SqueekySaxophone.HoldingRubberDucky")

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

Oh Hey!


Would you like us to re-route you to the mobile site whenever you visit the main site in this browser?

Next Steps:

Circonus Keyboard Shortcuts

Application Shortcuts

?
Show this keyboard help screen.
feedback
Open feedback form panel.
<esc>
Close help screens and dialogs.
/
Focus on any available search field.

Jump Navigation

dash
Jump to the dashboard.
docs
Jump to the documentation.
alerts
Jump to alerts.
checks
Jump to checks.
metrics
Jump to metrics.
rules
Jump to rules.
graphs
Jump to graphs.
worksheets
Jump to worksheets.

Graph Shortcuts

<comma>
Hold down to show the date shifting toolbar for modifying the start date. Can be combined with <period>.
<period>
Hold down to show the date shifting toolbar for modifying the end date. Can be combined with <comma>.
<shift>+<left>
Nudge the date range for the current graph(s) backward.
<shift>+<right>
Nudge the date range for the current graph(s) forward.
h
Toggle the display of histogram sparklines (shown upon hovering over a graph when viewing or when on a dashboard).

Graph Grid Shortcuts

<shift>
On a worksheet, hold it down to invert the current legend hover setting.
On “My Graphs” and the “Trending & Analytics Dash,” hold it down to show the legend when hovering over a graph.

Worksheet Shortcuts

<alt>+1
Resize current worksheet graphs to “small” size.
<alt>+2
Resize current worksheet graphs to “medium” size.
<alt>+3
Resize current worksheet graphs to “large” size.