First time users

If you've never used our API before we've put together a quick guide to get you started by listing devices from your account

1. Generating a token

In order to authenticate with our API you will need to create a token against your user in your account. This can be achieved by following Getting a token via the UI

Once you've created your token you can view it in your account by logging in and navigating to the Security section of your menu options (Click the cog in the top left).

Your token will look similar to b97da80a41c4f61bff05975ee51eb1aa. We will use this token as an example through the rest of this short guide.


A note about security

  • Tokens are generated for your user on your account and are only usable for that account
  • Tokens should be treated like passwords and should not be shared as they allow full access to the account and allow a user with the token to complete any action such as adding or deleting devices.

2. Listing all devices

In order to list all of the devices in your account we then need to send a request to a different endpoint, Listing all devices.

The above endpoint will only accept your token as a parameter and we can list all devices with a simple cURL command, as demonstrated below:

curl -v -X GET

This will generate a JSON response similar to the following (This example response only has one device):

        "_id": "51f6585e11f144673749afbb",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "agentKey": "22ddab237dff5cde07dc70a26e93c262",
        "agentVersion": "2.0.5", 
        "cId": "c16",
        "cloud": false,
        "cpuCores": null,
        "createdAt": "2016-02-29T12:19:11",
        "deleted": false,
        "group": "docs",
        "hostname": "docshost",
        "imageId": null,
        "installedRAM": "",
        "ip": null,
        "isMonitored": true,
        "isNew": true,
        "lastPayloadAt": {
            "sec": 1375179061,
            "usec": 0
        "location": {
            "countryCode": "gb",
            "countryName": "United Kingdom",
            "text": "Docs device"
        "name": "Llama",
        "os": {
            "code": "linux",
            "name": "Linux"
        "pluginsEnabled": [
                "DocsPlugin": [
                "TestPlugin": [
        "privateIPs": [],
        "provider": null,
        "publicIPs": [],
        "status": null,
        "swapSpace": "",
        "CPUCores": "",
        "type": "device",
        "updatedAt": "2016-02-30T10:11:01",
        "userId": "507ec4f48f4a5c547f000000",
        "tags": null,

Now you're all set and can begin to use the other API endpoints that are available. If you have any issues please let us know at [email protected]