API Documentation

API Client Examples

Here are a few examples of how to access the Circonus API from some commonly used clients and languages.

curl

GET cid

curl --user ExampleApp:fb349ef1-91e4-4b05-aaa2-52246b77ea66 \
   -H "Accept: application/json" \
   https://api.circonus.com/user/current

PUT cid

curl --user ExampleApp:fb349ef1-91e4-4b05-aaa2-52246b77ea66 \
   -H "Accept: application/json" \
   -X PUT \
   --data-binary '{"firstname":"Gonzo"}' \
   https://api.circonus.com/user/current

DELETE cid

curl --user ExampleApp:fb349ef1-91e4-4b05-aaa2-52246b77ea66 \
   -H "Accept: application/json" \
   -X DELETE \
   https://api.circonus.com/graph/123456

POST type

curl --user ExampleApp:fb349ef1-91e4-4b05-aaa2-52246b77ea66 \
   -H "Accept: application/json" \
   -X POST \
   --data-binary '{"title":"Big Bird''s Birthday","description":"Big Bird is six (again)","start": 1332216000,"stop":1332302399}' \
   https://api.circonus.com/annotation

GET type

curl --user ExampleApp:fb349ef1-91e4-4b05-aaa2-52246b77ea66 \
   -H "Accept: application/json" \
   https://api.circonus.com/user

Node.js

GET cid

#!/usr/bin/env node

// load the https module
var https = require('https');

https.request({
  host: 'api.circonus.com',
  path: '/user/current',
  headers: {
    'X-Circonus-App-Name': 'ExampleApp',
    'X-Circonus-Auth-Token': 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
    'Accept': 'application/json'
  }
}, function (response) {

  // collect the body while we're getting chunks of it
  var body = '';
  response.on('data', function (chunk) { body += chunk; });

  // once we've got 'em all, handle them
  response.on('end', function () {
    // parse the JSON body
    result = JSON.parse(body);

    // handle errors by extracting the code/message from the response
    if (response.statusCode < 200 || response.statusCode >= 300) {
      console.log( response.statusCode + ": " 
        + result.code + " (" + result.message + ")");
      return;
    }

    // result holds the data from the server
    console.log("Hello "+result.firstname+" "+result.lastname);
  });
}).end();

PUT cid

#!/usr/bin/env node

// load the https module
var https = require('https');

var r = https.request({
  host: 'api.circonus.com',
  path: '/user/current',
  headers: {
    'X-Circonus-App-Name': 'ExampleApp',
    'X-Circonus-Auth-Token': 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
    'Accept': 'application/json'
  },
  method: "PUT"
}, function (response) {

  // collect the body while we're getting chunks of it
  var body = '';
  response.on('data', function (chunk) { body += chunk; });

  // once we've got 'em all, handle them
  response.on('end', function () {
    // parse the JSON body
    result = JSON.parse(body);

    // handle errors by extracting the code/message from the response
    if (response.statusCode < 200 || response.statusCode >= 300) {
      console.log( response.statusCode + ": " 
        + result.code + " (" + result.message + ")");
      return;
    }

    // print out the new name
    console.log("Your firstname is now " + result.firstname);
  });
});

// here's where we specify the updates for the user's firstname
r.write(JSON.stringify({
  'firstname': "Gonzo"
}));

r.end();

DELETE cid

#!/usr/bin/env node

// load the https module
var https = require('https');

https.request({
  host: 'api.circonus.com',
  path: '/graph/123456',
  headers: {
    'X-Circonus-App-Name': 'ExampleApp',
    'X-Circonus-Auth-Token': 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
    'Accept': 'application/json'
  },
  method: "DELETE"
}, function (response) {

  // collect the body while we're getting chunks of it
  var body = '';
  response.on('data', function (chunk) { body += chunk; });

  // once we've got 'em all, handle them
  response.on('end', function () {

    // handle errors by extracting the code/message from the response
    if (response.statusCode < 200 || response.statusCode >= 300) {
      result = JSON.parse(body);
      console.log( response.statusCode + ": " 
        + result.code + " (" + result.message + ")");
      return;
    }

     console.log("DELETED!");
  });
}).end();

POST type

#!/usr/bin/env node

// load the https module
var https = require('https');

var r = https.request({
  host: 'api.circonus.com',
  path: '/annotation',
  headers: {
    'X-Circonus-App-Name': 'ExampleApp',
    'X-Circonus-Auth-Token': 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
    'Accept': 'application/json'
  },
  method: "POST"
}, function (response) {

  // collect the body while we're getting chunks of it
  var body = '';
  response.on('data', function (chunk) { body += chunk; });

  // once we've got 'em all, handle them
  response.on('end', function () {
    // parse the JSON body
    result = JSON.parse(body);

    // handle errors by extracting the code/message from the response
    if (response.statusCode < 200 || response.statusCode >= 300) {
      console.log( response.statusCode + ": " 
        + result.code + " (" + result.message + ")");
      return;
    }

    // print the new annotation details
    console.log("Created annotation: " + result['_cid'] +
      " (" + result.title + ")" );
  });
});

// here's where we specify the values for the new object
r.write(JSON.stringify({
    'title': "Big Bird's Birthday",
    'description': "Big Bird is six (again)",
    'start': 1332216000,
    'stop': 1332302399
}));

r.end();

GET type

#!/usr/bin/env node

// load the https module
var https = require('https');

https.request({
  host: 'api.circonus.com',
  path: '/user',
  headers: {
    'X-Circonus-App-Name': 'ExampleApp',
    'X-Circonus-Auth-Token': 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
    'Accept': 'application/json'
  }
}, function (response) {

  // collect the body while we're getting chunks of it
  var body = '';
  response.on('data', function (chunk) { body += chunk; });

  // once we've got 'em all, handle them
  response.on('end', function () {
    // parse the JSON body
    result = JSON.parse(body);

    // handle errors by extracting the code/message from the response
    if (response.statusCode < 200 || response.statusCode >= 300) {
      console.log( response.statusCode + ": " 
        + result.code + " (" + result.message + ")");
      return;
    }

    // print out each user's details
    console.log("Users with access to the account:");
    result.forEach(function(user) {
        console.log(" * " + user['_cid']
           + " ("+user.firstname + " " + user.lastname + ")");
    });
  });
}).end();

PHP

GET cid

<?php
    require_once 'HTTP/Request2.php';

    $APP   = "ExampleApp";
    $TOKEN = "fb349ef1-91e4-4b05-aaa2-52246b77ea66";

    # talk to the server
    $request = new HTTP_Request2(
    	"https://$APP:$TOKEN@api.circonus.com/user/current"
    );
    $request->setHeader("Accept","application/json");
    $response = $request->send();

    # decode the JSON
    $result = json_decode($response->getBody());

    # deal with exceptions by accessing the returned json and throwing why
    if (!preg_match("/^2/", $response->getStatus())) {
    	throw new Exception(
    		$response->getStatus().": ".$result->code." (".$result->message.")"
    	);
    }

    # Hello World
    print "Hello ".$result->firstname." ".$result->lastname;
?>

PUT cid

<?php
    require_once 'HTTP/Request2.php';

    $APP   = "ExampleApp";
    $TOKEN = "fb349ef1-91e4-4b05-aaa2-52246b77ea66";

    # talk to the server
    $request = new HTTP_Request2(
    	"https://$APP:$TOKEN@api.circonus.com/user/current",
    	HTTP_Request2::METHOD_PUT
    );
    $request->setHeader("Accept","application/json");
    $request->setBody(json_encode(array(
    	"firstname" => "Gonzo",
    )));
    $response = $request->send();

    # decode the JSON
    $result = json_decode($response->getBody());

    # deal with exceptions by accessing the returned json and throwing why
    if (!preg_match("/^2/", $response->getStatus())) {
    	throw new Exception(
    		$response->getStatus().": ".$result->code." (".$result->message.")"
    	);
    }

    # And access the updated result returned from the server
    print "Your first name is now ".$result->firstname."\n";
?>

DELETE cid

<?php
    require_once 'HTTP/Request2.php';

    $APP   = "ExampleApp";
    $TOKEN = "fb349ef1-91e4-4b05-aaa2-52246b77ea66";

    # talk to the server
    $request = new HTTP_Request2(
    	"https://$APP:$TOKEN@api.circonus.com/graph/123456",
    	HTTP_Request2::METHOD_DELETE
    );
    $request->setHeader("Accept","application/json");
    $response = $request->send();

    # decode the JSON
    $result = json_decode($response->getBody());

    # deal with exceptions by accessing the returned json and throwing why
    if (!preg_match("/^2/", $response->getStatus())) {
    	throw new Exception(
    		$response->getStatus().": ".$result->code." (".$result->message.")"
    	);
    }

    # Hello World
    print "DELETED!\n";
?>

POST type

<?php
    require_once 'HTTP/Request2.php';

    $APP   = "ExampleApp";
    $TOKEN = "fb349ef1-91e4-4b05-aaa2-52246b77ea66";

    # talk to the server
    $request = new HTTP_Request2(
    	"https://$APP:$TOKEN@api.circonus.com/annotation",
    	HTTP_Request2::METHOD_POST
    );
    $request->setHeader("Accept","application/json");
    $request->setBody(json_encode(array(
    	"title" => "Big Bird's Birthday",
    	"description" => "Big Bird is six (again)",
    	"start" => 1332216000,
    	"stop" => 1332302399,
    )));
    $response = $request->send();

    # decode the JSON
    $result = json_decode($response->getBody());

    # deal with exceptions by accessing the returned json and throwing why
    if (!preg_match("/^2/", $response->getStatus())) {
    	throw new Exception(
    		$response->getStatus().": ".$result->code." (".$result->message.")"
    	);
    }

    # print out the new cid (and other details)
    print "Created annotation: ".$result->_cid." (".$result->title.")\n";
?>

GET type

<?php
    require_once 'HTTP/Request2.php';

    $APP   = "ExampleApp";
    $TOKEN = "fb349ef1-91e4-4b05-aaa2-52246b77ea66";

    # talk to the server
    $request = new HTTP_Request2(
    	"https://$APP:$TOKEN@api.circonus.com/user"
    );
    $request->setHeader("Accept","application/json");
    $response = $request->send();

    # decode the JSON
    $result = json_decode($response->getBody());

    # deal with exceptions by accessing the returned json and throwing why
    if (!preg_match("/^2/", $response->getStatus())) {
    	throw new Exception(
    		$response->getStatus().": ".$result->code." (".$result->message.")"
    	);
    }

    # print out each user's details
    print "Users with access to the account:\n";
    foreach ($result as $user) {
    	print " * ".$user->_cid." (".$user->firstname." ".$user->lastname.")\n";
    }
?>

Perl

GET cid

#!/usr/bin/env perl

use strict;
use warnings;

# these are core modules since 5.13.9, or install them via the CPAN
# You'll also need to have installed IO::Socket::SSL 1.56 from the CPAN so we
# can talk over https
use HTTP::Tiny;
use JSON::PP qw(decode_json);

# create an agent
my $agent = HTTP::Tiny->new(
    default_headers => {
        'X-Circonus-App-Name' => 'ExampleApp',
        'X-Circonus-Auth-Token' => 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
        'Accept' => "application/json",
    },
);

# talk to the API over HTTP
my $response = $agent->get('https://api.circonus.com/user/current');

# parse the result as JSON
my $result = $response->{content} ? decode_json $response->{content} : {};

# handle errors
unless ($response->{success}) {
    die "$response->{status}: $result->{code} ($result->{message})\n";
}

# result holds the data from the server result
print "Hello $result->{firstname} $result->{lastname}\n";

PUT cid

#!/usr/bin/env perl

use strict;
use warnings;

# these are core modules since 5.13.9, or install them via the CPAN
# You'll also need to have installed IO::Socket::SSL 1.56 from the CPAN so we
# can talk over https
use HTTP::Tiny;
use JSON::PP qw(encode_json decode_json);

# create an agent
my $agent = HTTP::Tiny->new(
    default_headers => {
        'X-Circonus-App-Name' => 'ExampleApp',
        'X-Circonus-Auth-Token' => 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
        'Accept' => "application/json",
    },
);

# talk to the API over HTTP
my $response = $agent->put('https://api.circonus.com/user/current', {
    content => encode_json {
    	firstname => "Gonzo",
    },
});

# parse the result as JSON
my $result = $response->{content} ? decode_json $response->{content} : {};

# handle errors
unless ($response->{success}) {
    die "$response->{status}: $result->{code} ($result->{message})\n";
}

print "Your first name is now $result->{firstname}\n";

DELETE cid

#!/usr/bin/env perl

use strict;
use warnings;

# these are core modules since 5.13.9, or install them via the CPAN
# You'll also need to have installed IO::Socket::SSL 1.56 from the CPAN so we
# can talk over https
use HTTP::Tiny;
use JSON::PP qw(decode_json);

# create an agent
my $agent = HTTP::Tiny->new(
    default_headers => {
        'X-Circonus-App-Name' => 'ExampleApp',
        'X-Circonus-Auth-Token' => 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
        'Accept' => "application/json",
    },
);

# talk to the API over HTTP
my $response = $agent->delete('https://api.circonus.com/graph/123456');

# parse the result as JSON
my $result = $response->{content} ? decode_json $response->{content} : {};

# handle errors
unless ($response->{success}) {
    die "$response->{status}: $result->{code} ($result->{message})\n";
}

print "DELETED!\n";

POST type

#!/usr/bin/env perl

use strict;
use warnings;

# these are core modules since 5.13.9, or install them via the CPAN
# You'll also need to have installed IO::Socket::SSL 1.56 from the CPAN so we
# can talk over https
use HTTP::Tiny;
use JSON::PP qw(encode_json decode_json);

# create an agent
my $agent = HTTP::Tiny->new(
    default_headers => {
        'X-Circonus-App-Name' => 'ExampleApp',
        'X-Circonus-Auth-Token' => 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
        'Accept' => "application/json",
    },
);

# talk to the API over HTTP
my $response = $agent->post('https://api.circonus.com/annotation', {
    content => encode_json {
    	title => "Big Bird's Birthday",
    	description => "Big Bird is six (again)",
    	start => 1332216000,
    	stop => 1332302399,
    }
});

# parse the result as JSON
my $result = $response->{content} ? decode_json $response->{content} : {};

# handle errors
unless ($response->{success}) {
    die "$response->{status}: $result->{code} ($result->{message})\n";
}

# print out the new cid (and other details)
print "Created annotation: $result->{_cid} ($result->{title})\n";

GET type

#!/usr/bin/env perl

use strict;
use warnings;

# these are core modules since 5.13.9, or install them via the CPAN
# You'll also need to have installed IO::Socket::SSL 1.56 from the CPAN so we
# can talk over https
use HTTP::Tiny;
use JSON::PP qw(decode_json);

# create an agent
my $agent = HTTP::Tiny->new(
    default_headers => {
        'X-Circonus-App-Name' => 'ExampleApp',
        'X-Circonus-Auth-Token' => 'fb349ef1-91e4-4b05-aaa2-52246b77ea66',
        'Accept' => "application/json",
    },
);

# talk to the API over HTTP
my $response = $agent->get('https://api.circonus.com/user');

# parse the result as JSON
my $result = $response->{content} ? decode_json $response->{content} : {};

# handle errors
unless ($response->{success}) {
    die "$response->{status}: $result->{code} ($result->{message})\n";
}

# print out each user's details
print "Users with access to the account:\n";
foreach my $user (@{ $result }) {
    print " * $user->{_cid} ($user->{firstname} $user->{lastname})\n";
}

Python

GET cid

import requests;

try:
    response = requests.get(
    	"https://api.circonus.com/user/current",
    	auth=("ExampleApp","fb349ef1-91e4-4b05-aaa2-52246b77ea66"),
    	headers={'Accept': "application/json"}
    );
    response.raise_for_status()

    print "Hello %s %s" % (
    	response.json['firstname'],
    	response.json['lastname']
    )

# deal with exceptions by accessing the returned json and printing out why
except requests.exceptions.HTTPError as e:
     print "%s: %s (%s)" % (
    	e.response.status_code,
    	e.response.json['code'],
    	e.response.json['message']
    )

PUT cid

import requests;
import json;

try:
    response = requests.put(
    	"https://api.circonus.com/user/current",
    	json.dumps({
    		'firstname': 'Gonzo'
    	}),
    	auth=("ExampleApp","fb349ef1-91e4-4b05-aaa2-52246b77ea66"),
    	headers={'Accept': "application/json"}
    )
    response.raise_for_status()

    print "Your first name is now %s" % response.json['firstname']

# deal with exceptions by accessing the returned json and printing out why
except requests.exceptions.HTTPError as e:
     print "%s: %s (%s)" % (
    	e.response.status_code,
    	e.response.json['code'],
    	e.response.json['message']
    )

DELETE cid

import requests;

try:
    response = requests.delete(
    	"https://api.circonus.com/graph/123456",
    	auth=("ExampleApp","fb349ef1-91e4-4b05-aaa2-52246b77ea66"),
    	headers={'Accept': "application/json"}
    )
    response.raise_for_status()

    print "DELETED!"

# deal with exceptions by accessing the returned json and printing out why
except requests.exceptions.HTTPError as e:
     print "%s: %s (%s)" % (
    	e.response.status_code,
    	e.response.json['code'],
    	e.response.json['message']
    )

POST type

import requests;
import json;

try:
    response = requests.post(
    	"https://api.circonus.com/annotation",
    	json.dumps({
    		"title": "Big Bird's Birthday",
    		"description": "Big Bird is six (again)",
    		"start": 1332216000,
    		"stop": 1332302399
    	}),
    	auth=("ExampleApp","fb349ef1-91e4-4b05-aaa2-52246b77ea66"),
    	headers={'Accept': "application/json"}
    )
    response.raise_for_status()

    print "Created annotation: %s (%s)" % (
    	response.json["_cid"],
    	response.json["title"]
    )

# deal with exceptions by accessing the returned json and printing out why
except requests.exceptions.HTTPError as e:
     print "%s: %s (%s)" % (
    	e.response.status_code,
    	e.response.json['code'],
    	e.response.json['message']
    )

GET type

import requests;

try:
    response = requests.get(
    	"https://api.circonus.com/user",
    	auth=("ExampleApp","fb349ef1-91e4-4b05-aaa2-52246b77ea66"),
    	headers={'Accept': "application/json"}
    );
    response.raise_for_status()

    # print out each user's details
    print "Users with access to the account:"
    for user in response.json:
    	print " * %s (%s %s)" % (
    		user['email'],
    		user['firstname'],
    		user['lastname'],
    	)

# deal with exceptions by accessing the returned json and printing out why
except requests.exceptions.HTTPError as e:
     print "%s: %s (%s)" % (
    	e.response.status_code,
    	e.response.json['code'],
    	e.response.json['message']
    )

Ruby

GET cid

#!/usr/bin/ruby

require 'rubygems'
require 'json'
require 'rest_client'

# setup client
circonus = RestClient::Resource.new("https://api.circonus.com", :headers => {
    :x_circonus_app_name => "ExampleApp",
    :x_circonus_auth_token => "fb349ef1-91e4-4b05-aaa2-52246b77ea66",
    :accept => :json,
})

begin
    # get and parse
    response = circonus["/user/current"].get;
    result = JSON.parse(response);

    # print out the result
    puts "Hello #{result['firstname']} #{result['lastname']}";

rescue RestClient::Exception => ex
    # deal with exceptions by accessing the returned json and printing out why
    result = JSON.parse(ex.http_body)
    puts "#{ex.http_code}: #{result['code']} (#{result['message']})"
end

PUT cid

#!/usr/bin/ruby

require 'rubygems'
require 'json'
require 'rest_client'

# setup client
circonus = RestClient::Resource.new("https://api.circonus.com", :headers => {
    :x_circonus_app_name => "ExampleApp",
    :x_circonus_auth_token => "fb349ef1-91e4-4b05-aaa2-52246b77ea66",
    :content_type => :json,
    :accept => :json,
})

begin
    # put and parse the updated object
    response = circonus["/user/current"].put(
        { :firstname => "Gonzo" }.to_json()
    );
    result = JSON.parse(response);

    puts "Your first name is now #{result['firstname']}";

rescue RestClient::Exception => ex
    # deal with exceptions by accessing the returned json and printing out why
    result = JSON.parse(ex.http_body)
    puts "#{ex.http_code}: #{result['code']} (#{result['message']})"
end

DELETE cid

#!/usr/bin/ruby

require 'rubygems'
require 'json'
require 'rest_client'

# setup client
circonus = RestClient::Resource.new("https://api.circonus.com", :headers => {
    :x_circonus_app_name => "ExampleApp",
    :x_circonus_auth_token => "fb349ef1-91e4-4b05-aaa2-52246b77ea66",
    :accept => :json,
})

begin
    # delete
    response = circonus["/graph/123456"].delete;

    puts "DELETED!"

rescue RestClient::Exception => ex
    # deal with exceptions by accessing the returned json and printing out why
    result = JSON.parse(ex.http_body)
    puts "#{ex.http_code}: #{result['code']} (#{result['message']})"
end


POST type

#!/usr/bin/ruby

require 'rubygems'
require 'json'
require 'rest_client'

# setup client
circonus = RestClient::Resource.new("http://api.circonus.com", :headers => {
    :x_circonus_app_name => "ExampleApp",
    :x_circonus_auth_token => "fb349ef1-91e4-4b05-aaa2-52246b77ea66",
    :content_type => :json,
    :accept => :json,
})

begin
    # put and parse the updated object
    response = circonus["/annotation"].post(
        {
            :title => "Big Bird's Birthday",
            :description => "Big Bird is six (again)",
            :start => 1332216000,
            :stop => 1332302399,
        }.to_json()
    );
    result = JSON.parse(response);

    puts "Created annotation: #{result['_cid']} (#{result['title']})";

rescue RestClient::Exception => ex
    # deal with exceptions by accessing the returned json and printing out why
    result = JSON.parse(ex.http_body)
    puts "#{ex.http_code}: #{result['code']} (#{result['message']})"
end

GET type

#!/usr/bin/ruby

require 'rubygems'
require 'json'
require 'rest_client'

# setup client
circonus = RestClient::Resource.new("https://api.circonus.com", :headers => {
    :x_circonus_app_name => "ExampleApp",
    :x_circonus_auth_token => "fb349ef1-91e4-4b05-aaa2-52246b77ea66",
    :accept => :json,
})

begin
    # get and parse
    response = circonus["/user"].get;
    result = JSON.parse(response);

    # print out each user's details
    puts "Users with access to the account:";
    result.each { |user|
        puts " * #{user['_cid']} (#{user['firstname']} #{user['lastname']})\n";
    }

rescue RestClient::Exception => ex
    # deal with exceptions by accessing the returned json and printing out why
    result = JSON.parse(ex.http_body)
    puts "#{ex.http_code}: #{result['code']} (#{result['message']})"
end