NAV Navbar
shell

Introduction

Welcome to the cognity.io API! You can use our API to access all endpoints, which can help you start and build IoT applications in minutes!

Authentication

Login

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.cognity.io/v1/account/authenticate"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

{
    "response": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdmF0YXIiOiJodHRwczovL3MzLWFwLXNvdXRoZWFzdC0xLmFtYXpvbmF3cy5jb20vY29nbml0eS1maWxlLWltYWdlLXByb2Qvbmlrb2xhLnRlc2xhLzE1NDA5Nzc4MDM3NzcucG5nIiwiZGF0ZUNyZWF0ZWQiOjE1NDA4OTM0Mzk5MzUsImFjY291bnRJZCI6IjMwYmVkNGYwLWRjMmEtMTFlOC04Njc0LTc5NzU4ODdkMzllMSIsImdyb3VwSWQiOiJhZG1pbiIsInVzZXJuYW1lIjoibmlrb2xhLnRlc2xhIiwiZW1haWwiOiJuaWtvbGEudGVzbGFAZ21haWwuY29tIiwiZnVsbE5hbWUiOiJOaWtvbGEgVGVzbGEiLCJjdXN0b20iOnt9LCJkYXRlVXBkYXRlZCI6MTU0MDk3NzgwNjYzNSwidHlwZSI6ImRlZmF1bHQiLCJpYXQiOjE1NDA5OTQ1Mjl9.MPchrS-TsIMwU15U-C-7Co4uOTiszzseEtmD0Q1pKE4"
}

Make sure to replace <key> with your API key.

cognity.io uses API keys to allow access to the API. You can register a new cognity.io API key at our device cloud manager.

cognity.io expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-API-Key: <key>

HTTP Request

POST https://api.cognity.io/v1/account/authenticate

Body

Parameter Type Required Description
username string Required Input your username
password string Required Input your password

Devices

Get All Devices

curl "https://api.cognity.io/v1/my/devices"
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "enableStorage": false,
            "dateCreated": 1540895391019,
            "avatar": "null",
            "isPrivate": true,
            "deviceId": "rela-a",
            "description": "heyy",
            "name": "Light Bulb A",
            "custom": "{}",
            "ownerId": "nikola.tesla",
            "dateUpdated": 1540895391019
        },
        {
            "enableStorage": false,
            "dateCreated": 1540895707416,
            "avatar": "null",
            "isPrivate": true,
            "deviceId": "relay-a",
            "description": "heyy",
            "name": "Ligh Bulb - B",
            "custom": "{}",
            "ownerId": "nikola.tesla",
            "dateUpdated": 1540895707416
        }
    ],
    "lastEvaluatedKey": null
}

This endpoint retrieves all your devices.

HTTP Request

GET https://api.cognity.io/v1/my/devices

Query Parameters

Parameter Default Description
limit 100 The limit number of items to be returned

Get a Specific Device

curl "https://api.cognity.io/v1/my/devices/relay-a"
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

  {
    "data" : {
      "enableStorage": false,
      "dateCreated": 1540895707416,
      "avatar": "null",
      "isPrivate": true,
      "deviceId": "relay-a",
      "description": "heyy",
      "name": "Ligh Bulb - B",
      "custom": "{}",
      "ownerId": "nikola.tesla",
      "dateUpdated": 1540895707416
    }
  }

This endpoint retrieves a specific device.

HTTP Request

GET https://api.cognity.io/v1/my/devices/<deviceId>

URL Parameters

Parameter Description
deviceId The ID of the device to retrieve

Create a Device

curl "https://api.cognity.io/v1/my/devices"
  -H "Authorization: Bearer <token>"
  -H "Content-Type: application/json"
  -H "X-API-Key: <key>"
  -X "POST"
  -d '{
    "name": "test-device 2",
    "description": "test description 2",
    "avatar" : "<image_link>"
    "deviceId" : "123121001",
    "attributeNames" : ["Temperature","Humidity","Barometer","Rain Drop"]
  }'

The above command returns JSON structured like this:

  {
    "data" : {
      "enableStorage": false,
      "dateCreated": 1540895707416,
      "avatar": "<image_link>",
      "deviceId": "123121001",
      "description": "test description 2",
      "name": "test-device 2",
      "custom": "{}",
      "ownerId": "nikola.tesla",
      "attributeNames" : ["Temperature","Humidity","Barometer","Rain Drop"],
      "dateUpdated": 1540895707416
    }
  }

This endpoint creates a device.

HTTP Request

POST https://api.cognity.io/v1/my/devices

Body

Parameter Type Required Description
deviceId string Required A unique id for the device
name string Required Name for the device
description string Not Required Description for your device
avatar string Not Required Image for the device
attributeNames array[strings] Not Required Attributes for the device parameters

Update a Device

curl "https://api.cognity.io/v1/my/devices"
  -H "Authorization: Bearer <token>"
  -H "Content-Type: application/json"
  -H "X-API-Key: <key>"
  -X "PUT"
  -d '{
    "name": "test-device 2 (updated)",
    "description": "test description 2",
    "avatar" : "<image_link>"
    "attributeNames" : ["Temperature","Humidity","Barometer","Rain Drop"]
  }'

The above command returns JSON structured like this:

  {
    "data" : {
      "dateCreated": 1540895707416,
      "avatar": "null",
      "isPrivate": true,
      "deviceId": "relay-a",
      "description": "test description 2",
      "name": "test-device 2 (updated)",
      "custom": "{}",
      "ownerId": "nikola.tesla",
      "attributeNames" : ["Temperature","Humidity","Barometer","Rain Drop"],
      "dateUpdated": 1540895707416
    }
  }

This endpoint updates a specific device.

HTTP Request

Put https://api.cognity.io/v1/my/devices

Body

Parameter Type Required Description
name string Required Name for the device
description string Not Required Description for your device
avatar string Not Required Image for the device
attributeNames array[strings] Not Required Attributes for the device parameters

Delete a Specific Device

curl "https://api.cognity.io/v1/my/devices/<deviceId>"
  -X DELETE
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

{
  "deviceId" : "<deviceId>",
  "status" : "device deleted"
}

This endpoint deletes a specific device.

HTTP Request

DELETE https://api.cognity.io/v1/my/devices/<deviceId>

URL Parameters

Parameter Description
deviceId The ID of the device to delete

Storage

Get Device Storage

curl "https://api.cognity.io/v1/storage/my/device/<deviceId>"
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "dataType": "csv",
            "dateCreated": 1539242387436,
            "deviceId": "s6519",
            "id": "s6519#nikola_tesla",
            "data": "25.70,48.10,100.64,0.39,97"
        },
        {
            "dataType": "csv",
            "dateCreated": 1539242397165,
            "deviceId": "s6519",
            "id": "s6519#nikola_tesla",
            "data": "25.80,48.20,100.65,0.10,97"
        },
        {
            "dataType": "csv",
            "dateCreated": 1539242407487,
            "deviceId": "s6519",
            "id": "s6519#nikola_tesla",
            "data": "25.70,48.10,100.65,0.10,97"
        }
    ]
}

This endpoint retrieves all kittens.

HTTP Request

GET https://api.cognity.io/v1/storage/my/device/<deviceId>

Query Parameters

Parameter Type Default Required Description
deviceId string N/A Required The ID of the device for the storage logs
limit number 100 Not Required The limit number of items to be returned
dateFrom number N/A Not Required The start date of the logs
dateTo number N/A Not Required The end date of the logs
order string descending Not Required The order of the logs by date

Permissions

Get All Permissions

curl "https://api.cognity.io/v1/permissions/device"
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "permissionId": "e617a860-d03e-11e8-aef5-cb5f08eeb261",
            "username": "nikola.tesla",
            "ownerId": "alber.einstein",
            "groupId": "groupId",
            "deviceId": "dev1000",
            "dateCreated": 1540895707416,
            "dateCreated": 1540895391019
        },
        {
            "permissionId": "e617a860-d03e-11e8-aef5-cb5f08eeb261",
            "username": "isaac.newton",
            "ownerId": "alber.einstein",
            "groupId": "groupId",
            "deviceId": "dev1000",
            "dateCreated": 1540895707416,
            "dateCreated": 1540895391019
        }
    ],
    "lastEvaluatedKey": null
}

This endpoint retrieves all your permissions.

HTTP Request

GET https://api.cognity.io/v1/permissions/device

Query Parameters

Parameter Default Description
limit 100 The limit number of items to be returned

Get a Specific Permission

curl "https://api.cognity.io/v1/permissions/device/<deviceId>"
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

  {
    "data" : {
      "permissionId": "e617a860-d03e-11e8-aef5-cb5f08eeb261",
      "username": "isaac.newton",
      "ownerId": "alber.einstein",
      "groupId": "groupId",
      "deviceId": "dev1000",
      "dateCreated": 1540895707416,
      "dateCreated": 1540895391019
    }
  }

This endpoint retrieves a specific permission.

HTTP Request

GET https://api.cognity.io/v1/permissions/device/<deviceId>

URL Parameters

Parameter Description
deviceId The ID of the device to retrieve

Create a Permission

curl "https://api.cognity.io/v1/permissions/device"
  -H "Authorization: Bearer <token>"
  -H "Content-Type: application/json"
  -H "X-API-Key: <key>"
  -X "POST"
  -d '{
    "username": "nikola.teslas",
    "groupId": "<groupId>",
    "deviceId" : "<deviceId>"
  }'

The above command returns JSON structured like this:

  {
    "data" : {
      "permissionId": "e617a860-d03e-11e8-aef5-cb5f08eeb261",
      "username": "isaac.newton",
      "ownerId": "alber.einstein",
      "groupId": "groupId",
      "deviceId": "dev1000",
      "dateCreated": 1540895707416,
      "dateCreated": 1540895391019
    }
  }

This endpoint creates a permission for a device.

HTTP Request

POST https://api.cognity.io/v1/permissions/device

Body

Parameter Type Required Description
username string Required The username of the user to give the permission to
deviceId string Required The deviceId paired with the permission
groupId string Not Required The id used for group permission

Delete a Specific Permission

curl "https://api.cognity.io/v1/permissions/device/<deviceId>/<permissionId>/<username>"
  -X DELETE
  -H "Authorization: Bearer <token>"
  -H "X-API-Key: <key>"

The above command returns JSON structured like this:

{
  "permissionId" : "<permissionId>",
  "status" : "permission deleted"
}

This endpoint deletes a specific permission for a device.

HTTP Request

DELETE https://api.cognity.io/v1/permissions/device/<deviceId>/<permissionId>/<username>

URL Parameters

Parameter Description
deviceId The ID of the device paired with the permission
permissionId The id of the permission
username The username of the paired with the permission

Errors

The cognity.io API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The API requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're requesting too many resources at a time
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.