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, see our postman quickstart.

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

Is the IP address for the API static?

No, the IP addresses for our APIs will change as we evolve our architecture and extend our service offerings. We will do our best to keep the changes to a minimum.

If you want to limit outbound traffic to api.cognitedata.com only, the IP addresses for the current and future APIs are:

35.187.184.117
34.76.254.249
1
2

We are working on exposing updated lists of our API addresses automatically, but until that is in place, check back here once a month to verify if there are any changes.

Do I need to open up for other IP addresses to fully use the API?

Some of our API endpoints, such as the Files endpoint, return a link to a Google Cloud resource. This is important to ensure that uploads fully leverage the Google Cloud services as efficiently as possible.

To fully use all our API endpoints, most importantly Files, you must also open up for certain Google Cloud IP addresses. Google publishes a list of these IP ranges through DNS: https://cloud.google.com/compute/docs/faq#find_ip_range.

Because the Cognite Data Platform resides on the Google Cloud, you will also open for our API endpoints when you open for the Google Cloud IP ranges.

Last Updated: 2/8/2019, 3:06:21 PM