API Documentation | Account

Provides API access to the Circonus account itself. Allows you to alter the basic contact details associated with the account and description of the account, the timezone used in the user interface, and control user access to the account.

Fields

_cid string
The primary key
"/account/1234"
A string containing a account cid
_contact_groups array
The contact groups for this account
["/contact_group/1701","/contact_group/3141"]
An array
string (zero or more times)
A contact group
A string containing a contact_group cid
_owner string
The user who owns this account
"/user/42"
A string containing a user cid
_ui_base_url string
The base URL for this account in the Circonus UI.
"https://example.circonus.com/"
A string containing freeform text
_usage array
A list of usage limits that apply to this account and their current values
[{"_used":7,"_type":"Host","_limit":50}]
An array
object (zero or more times)
An object representing a particular usage limit
An object
_limit number
The number of the item used up (e.g. the number of hosts assigned)
A number containing an integer greater than or equal to zero
_type string
The name of the usage limit
A string, e.g. 'Host'
_used number
The number of the item allowed (e.g. the total number of allowed hosts)
A number containing an integer greater than or equal to zero
address1 string
The first line of the address associated with the account. For example, the US president would use "1600 Pennsylvania Avenue"
"Hooper's Store"
A string containing freeform text
address2 string
The second line of the address associated with the account. For example, Hercule Poirot who runs his detective agency out of "Apt 56B, Whitehaven Mansions, Sandhurst Sq, London" might use "Apt 56B, Whitehaven Mansions" for address1, while using "Sandhurst Square" in address2
"Sesame Street"
A string containing freeform text
cc_email string
Circonus invoices and receipts will be automatically emailed to the account owner. You can optionally specify another email address (e.g., accounts_payable@yourdomain.com) to add to the CC field of those emails.
"accounts_payable@yourdomain.com"
A string containing an RFC822 compatible email address (e.g. "support@circonus.com")
city string
The city part of the address associated with the account. For example, Bruce Wayne would use "Gotham" for Wayne Enterprises here.
"New York City"
A string containing freeform text
country_code string
The country of the user's address.
"US"
A string containing an ISO3166 alpha 2 style country code, e.g. 'us' or 'gb'
description string
Description of the account
"Hooper's Store Account"
A string containing freeform text
invites array
[{"role":"Admin","email":"alan@example.com"},{"email":"chris.robinson@example.com","role":"Normal"}]
An array
object (zero or more times)

An object
email string

A string containing an RFC822 compatible email address (e.g. "support@circonus.com")
role string

A string containing 'Admin' (indicating the user can do anything), 'Normal' (indicating the user can do everything but administer access to the account itself) or 'Read Only' (indicating the user only has read only access to the account)
name string
The name of the account
"hoopers-store"
A string containing freeform text
state_prov string
The state or province of the address associated with the account. An american like Michael Bloomberg might use a two letter code like "NY" for the mayor's office whereas an englishman like Boris Johnson might use the county of their office like "Greater London".
"NY"
A string containing freeform text
timezone string
The timezone that events will be displayed in the web interface for this account (the API always displays times as epoch seconds since Jan 1st 1970 GMT)
"America/New_York"
A string containing an 'Olson timezone' from the IANA Time Zone Database, e.g. 'Europe/London'
users array
The users that have access to this account
[{"user":"/user/42","role":"Admin"}]
An array of users and the roles they have been granted. Each user may appear only once in this array. You can modify this data structure to change users' roles or remove roles, but you may not add new users to an account by altering this data structure unless they have previously accepted a role in this account.
object (zero or more times)
An object detailing the role a user has been granted within this account
An object
role string
The role (the level of access) the user has for the account
A string containing 'Admin' (indicating the user can do anything), 'Normal' (indicating the user can do everything but administer access to the account itself) or 'Read Only' (indicating the user only has read only access to the account)
user string
The user the role is assigned to
A string containing a user cid

Example

Fetching Accounts

Fetching details for an account is as simple as performing a GET on the account cid:

GET /account/1234
{"_usage":[{"_used":7,"_type":"Host","_limit":50}],"cc_email":"accounts_payable@yourdomain.com","name":"hoopers-store","invites":[{"email":"alan@example.com","role":"Admin"},{"role":"Normal","email":"chris.robinson@example.com"}],"timezone":"America/New_York","city":"New York City","description":"Hooper's Store Account","_contact_groups":["/contact_group/1701","/contact_group/3141"],"users":[{"role":"Admin","user":"/user/42"}],"address2":"Sesame Street","state_prov":"NY","address1":"Hooper's Store","_owner":"/user/42","_cid":"/account/1234","country_code":"US"}

However, you can only access information on accounts which the user associated with the API token you are using is a member of (which means most users only have access to one account object.)

You can see from the above example a few key things about the account:

As well as using a known numerical account cid, you can also get the current account - the account your API token is associated with - by requesting the special /account/current cid:

GET /account/current
{"timezone":"America/New_York","invites":[{"email":"alan@example.com","role":"Admin"},{"email":"chris.robinson@example.com","role":"Normal"}],"name":"hoopers-store","cc_email":"accounts_payable@yourdomain.com","_usage":[{"_type":"Host","_used":7,"_limit":50}],"description":"Hooper's Store Account","_contact_groups":["/contact_group/1701","/contact_group/3141"],"city":"New York City","address2":"Sesame Street","users":[{"role":"Admin","user":"/user/42"}],"_cid":"/account/1234","country_code":"US","_owner":"/user/42","state_prov":"NY","address1":"Hooper's Store"}

Updating Accounts

Changing the basic details for your account is as simple as using a PUT command to change the details:

PUT /account/current
{"address1":"Hooper's Store and Laundrymat"}

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

Likewise you can configure the timezone that the user interface uses (maybe you prefer UTC so everything lines up with the times in your internal logs.)

PUT /account/current
{"timezone":"Etc/UTC"}

The API can also be used to manage the users that are able to access the account. Users with access to the account are listed in the "users" field. However, new users cannot be directly added to this array; Circonus needs to send a user and email invite and the user needs to accept the role before a user is associated with an account. To do this via the API you can simply add a new entry to the invites list:

PUT /account/current
{"invites":[{"email":"alan@example.com","role":"Admin"},{"email":"chris.robinson@example.com","role":"Normal"},{"email":"natalie.portman@example.com","role":"Read Only"}]}

This will cause the invite email to be sent out. Altering the list to no longer contain an entry has the effect of cancelling the invite (so if someone follows an invite email they'll be unable to accept it.)

The invites have three defined roles: A large account with many users typically has many "Normal" users who have full access to modify and update the dashboards, trending, alerts and data sections of the GUI. The account will also have one or more "Admin" users who also have the ability to admin the account itself - to add and remove users from the account. There also might be a few "Read Only" users (which might be used for example by non technical staff who might need to observe KPIs but shouldn't be allowed make changes.)

Once an invitee has accepted a role, they will be removed from the invites field and added to the users field:

GET /account/current
{"timezone":"Etc/UT","invites":[{"email":"alan@example.com","role":"Admin"},{"email":"natalie.portman@example.com","role":"Read Only"}],"name":"hoopers-store","_usage":[{"_used":7,"_type":"Host","_limit":50}],"cc_email":"accounts_payable@yourdomain.com","description":"Hooper's Store Account","_contact_groups":["/contact_group/1701","/contact_group/3141"],"city":"New York City","address2":"Sesame Street","users":[{"role":"Admin","user":"/user/42"},{"user":"/user/411","role":"Normal"}],"country_code":"US","_owner":"/user/42","_cid":"/account/1234","state_prov":"NY","address1":"Hooper's Store"}

Manipulating this field allows you to change a user's role, for example giving them "Admin" access when they'd previously only had "Normal" access...

PUT /account/current
{"users":[{"user":"/user/42","role":"Admin"},{"user":"/user/411","role":"Admin"}]}

...or even removing them from the account:

PUT /account/current
{"users":[{"role":"Admin","user":"/user/42"}]}

Creating and Deleting Accounts

Currently accounts can only be opened and closed via the GUI. It is not foreseen that there will be a need to do this on an automated basis.