Frequently asked questions

General questions

How to use CDP versions?

Resources in the Cognite API are accessed under the https://api.cognitedata.com/api/{version}/projects/{project}/ URL. The {version} placeholder should be replaced with the version of the API, e.g. 0.5, and the {project} placeholder should be replaced with the project identifier.

Technical questions

How do I check if my API key is valid?

To use the Cognite API you must be authenticated, either by using an API key or retrieving a JWT through a configured active directory connection.

If you have an API key, you'll authenticate requests by sending the API key in the Api-Key header.

You can check whether your API key is valid like this:

POST /login HTTP/1.1
Content-Type: application/json
Host: api.cognitedata.com
Content-Length: 31

{
  "apiKey": "DEFAULTAPIKEY"
}
1
2
3
4
5
6
7
8

Post body field:

Path Type Description
apiKey String The API key to login with.

This should give a response similar to:

HTTP/1.1 200 OK
X-Request-Id: 08cb1eec0bc5529d
Content-Type: application/json

{
  "data": {
    "user": "defaultuser@test.com",
    "loggedIn": true,
    "project": "unit-test",
    "projectId": 2865847295223183
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

How does the REST API deal with errors?

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

For example, a request that attempts to access a project that doesn't exist will produce a 403 Forbidden response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": 401,
    "message": "HTTP 401 Unauthorized"
  }
}
1
2
3
4
5
6
7
8
9

Where is your OpenAPI spec?

We also publish an OpenAPI specification of the Cognite API, which is available at http://doc.cognitedata.com/openapi.json. Using Swagger codegen with this will allow you to generate client libraries to the Cognite API in your language of choice, effectively creating a simple SDK.

Do you have a Postman collection?

Yes, here. Download the file and import it into Postman to access our REST API through a nice graphical user interface.

How do I create a root asset?

Post the asset without parentId, parentName and parentRefId.

{
  "items": [
    {
      "name": "...",
      "description": "...",
      "metadata": {},
      "refId": "...",
      "source": "...",
      "sourceId": "..."
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
Last Updated: 11/12/2018, 9:22:06 AM