API docs by Redocly

Cognite API (v1)

Download OpenAPI specification:Download

Cognite Support: support@cognite.com URL: https://support.cognite.com

Introduction

This is the reference documentation for the Cognite API with an overview of all the available methods.

Postman

You can download our postman collection here. Open Postman, click Import -> Import From Link, insert the link and import.

You can read more about how to use Postman here

Pagination

Most resource types can be paginated, indicated by the field nextCursor in the response. By passing the value of nextCursor as the cursor you will get the next page of limit results. Note that all parameters except cursor has to stay the same.

Parallel retrieval

If you want to download a lot of resources (let's say events), paginating through millions of records can be slow. We support parallel retrieval through the partition parameter, which has the format m/n where n is the amount of partitions you would like to split the entire data set into. If you want to download the entire data set by splitting it into 10 partitions, you would do the following in parallel with m running from 1 to 10:

  • Make a request to /events with partition=m/10.
  • Paginate through the response by following the cursor as explained above. Note that the partition parameter needs to be passed to all subqueries.

Login

A user that is only manifested in an external IdP needs to authenticate towards that IdP and not Cognite directly. Our login endpoints gives some mechanism for both redirecting to the IdP for a given project as well as getting information about the currently authenticated user. For a service account manifested in CDF, there's no reason to logging in. To validate that the key is valid, you can ask for authentication information about the logged in entity.

Verify login status

Returns the authentication information about the asking entity.

Authorizations:
api-key

Responses

Request samples 

const status = await client.login.status();
// if status === null means you are not logged in

Response samples

Content type
application/json
{
  • "data": {
    }
}

Login with redirect

Redirects to a login URL. This endpoint is typically used by front-end services acting on behalf of users to log them in.

query Parameters
project
required
string

The project to login to.

redirectUrl
required
string

The url to send the user to after the login is successful.

errorRedirectUrl
string

The url to send the user to if the login fails or is aborted. If this is not passed in, the value of the redirectUrl will be used.

Responses

Request samples 

import { CogniteClient, REDIRECT } from '@cognite/sdk';

const client = new CogniteClient({ appId: '[YOUR APP NAME]' });

// using Cognite authentication flow
client.loginWithOAuth({
  project: '[PROJECT]',
  onAuthenticate: REDIRECT // optional, REDIRECT is by default
});

// or you can sign in using AzureAD authentication flow (in case your projects supports it)
client.loginWithOAuth({
  cluster: '[CLUSTER]',
  clientId: '[CLIENT_ID]', // client id of your AzureAD application
  tenantId: '[TENANT_ID]', // tenant id of your AzureAD tenant. Will be set to 'common' if not provided
});

// you also have ability to sign in using ADFS
client.loginWithOAuth({
  authority: https://example.com/adfs/oauth2/authorize,
  requestParams: {
    cluster: 'cluster-name',
    clientId: 'adfs-client-id',
  },
});

// after sign in you can do calls with the client
(async () => {
  await client.authenticate();
  client.setProject('project-name');
  const createdAsset = await client.assets.create([{ name: 'My first asset' }]);
})();

Obtain user information

Ask this with any valid credentials to obtain information about the current authenticated entity. The response is a decoded ID token.

Responses

Response samples

Content type
application/json
{
  • "sub": "tom@example.com",
  • "project_name": "digitalrevolution",
  • "groups": [
    ],
  • "signing_key": "a769f8ef-d5e3-4cf7-b914-2a6de189d942",
  • "exp": 1554897484
}

Logout

Logging out a user means invalidating the token granted by CDF on the behalf of the external IdP. Optionally, you can also get a logout url to log out of the IdP itself (Azure AD, Google etc.). Logging out is only effective for tokens (not api keys).

Logout

Invalidates a session and returns the authentication status of the asking entity.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a logout url

Get logout url of the given project.

Authorizations:
api-keyoidc-token
query Parameters
redirectUrl
string
Example: redirectUrl=https://mysite.com/loggedout

The url to send the user to after the logout is successful. If no url is passed, you will end up at the IdP's log out page.

Responses

Request samples 

// You can specify the url to send the user to after the logout is successful.
// If no url is passed, you will end up at the IDPs log out page.
const logoutUrl = await client.logout.getUrl({ redirectUrl: '[url to redirect]' });

Response samples

Content type
application/json
{}

Projects

Projects are used to isolate data in CDF from each other. All objects in CDF belong to a single project, and objects in different projects are generally isolated from each other.

List projects

The list of all projects that the user has the 'list projects' capability in. The user may not have access to any resources in the listed projects, even if they have access to list the project itself.

Authorizations:
api-keyoidc-token

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve a project

Retrieves information about a project given the project URL name.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Request samples 

const projectInfo = await client.projects.retrieve('publicdata');

Response samples

Content type
application/json
{
  • "name": "Open Industrial Data",
  • "urlName": "publicdata",
  • "defaultGroupId": 123871937,
  • "authentication": {
    },
  • "oidcConfiguration": {
    }
}

Update a project

Updates the project configuration.

Warning: Updating a project will invalidate active sessions within that project.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

Project url name

Request Body schema: application/json

Object with updated project configuration.

required
object (ProjectUpdateObjectDTO)

Contains the instructions on how to update the project. Note: azureADConfiguration, oidcConfiguration and oAuth2Configuration are mutually exclusive

Responses

Request samples

Content type
application/json
{
  • "update": {
    }
}

Response samples

Content type
application/json
{
  • "name": "Open Industrial Data",
  • "urlName": "publicdata",
  • "defaultGroupId": 123871937,
  • "authentication": {
    },
  • "oidcConfiguration": {
    }
}

Groups

Groups are used to give principals (service accounts or users) the capabilities to access CDF resources. One principal can be a member in multiple groups and one group can have multiple members. Note that having more than 20 groups per principal is not supported and may result in login issues.

List groups

Retrieves a list of groups the asking service account is a member of. Service accounts with groups:list capability can optionally ask for all groups in a project.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
all
boolean
Default: false

Whether to get all groups, only available with the groups:list acl.

Responses

Request samples 

const groups = await client.groups.list({ all: true });

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create groups

Creates one or more named groups, each with a set of capabilities.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of groups to create.

required
Array of objects (GroupSpec)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete groups

Deletes the groups with the given IDs.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of group IDs to delete

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

List service accounts in a group

Retrieve a list of service accounts that are members of the group with the given ID.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

groupId
required
integer <int64>

ID of the group

Responses

Request samples 

const serviceAccounts = await client.groups.listServiceAccounts(921923342342323);

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add service accounts to a group

Grant the service accounts with the given IDs membership in a group. This operation is not idempotent: if any of the given service accounts is already a member of the group, the operation will fail. Note that linking a service account to more than 20 groups is not supported and may result in login issues.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

groupId
required
integer <int64>

ID of the group

Request Body schema: application/json

IDs of service accounts to add

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "string",
  • "missingFields": [
    ]
}

Remove service accounts from a group

Revoke membership in a group from the given service accounts.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

groupId
required
integer <int64>

ID of the group

Request Body schema: application/json

List of service account IDs to remove

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Service accounts

Manage service accounts for a specific project. A service account can be used to give applications access to CDF through the use of API keys.

List service accounts

Lists all the service accounts of the project.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Request samples 

const serviceaccounts = await client.serviceAccounts.list();

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create service accounts

Creates new service accounts with the given names and group memberships. The names of the service accounts have to be unique. If any of the provided group IDs are not valid group IDs, the request will fail and no service accounts will be created.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of service accounts to create.

required
Array of objects (ServiceAccountInput)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete service accounts

Deletes the service accounts identified by the given IDs. API keys associated with those service accounts will also be deleted. If any of the provided IDs are not valid service account IDs, the request will fail and no resources will be deleted.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of service account IDs to delete

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

API keys

Manage API keys for a specific project. API keys are used to give service accounts access to the CDF API.

List API keys

Retrieves a list of all API keys connected to the current service account. Administrators can optionally list keys for all or individual service accounts that are not their own.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
all
boolean
Default: false

Only available with users:list ACL, returns all API keys for the project.

serviceAccountId
integer <int64>

Get API keys for a specific service account, only available to admin users.

includeDeleted
boolean
Default: false

Whether to include deleted API keys, or not. Deleted API keys can be listed for up to 90 days after deletion.

Responses

Request samples 

const apiKeys = await client.apiKeys.list({ all: true });

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create API keys

Creates one API key for each service account. If the ID of one service account appears multiple times in the request, then multiple API keys will be created for that service account.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of the service accounts to create API keys for.

required
Array of objects (ApiKeyRequest)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete API keys

Deletes one or more API keys with the specified API key IDs. The API key IDs were returned when the keys were created, or can be obtained by listing all API keys. Deleted API keys can be listed for up to 90 days after deletion.

Authorizations:
api-key
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of the IDs of the API keys to delete.

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Security categories

Manage security categories for a specific project. Security categories can be used to restrict access to a resource. Applying a security category to a resource means that only principals (users or service accounts) that also have this security category can access the resource. To learn more about security categories please read this page.

List security categories

Retrieves a list of all security categories for a project.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
sort
string
Default: "ASC"
Enum: "ASC" "DESC"

Sort descending or ascending.

cursor
string

Cursor to use for paging through results.

limit
integer <int32> <= 1000
Default: 25

Return up to this many results. Maximum is 1000. Default is 25.

Responses

Request samples 

const securityCategories = await client.securityCategories.list({ sort: 'ASC' });

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create security categories

Creates security categories with the given names. Duplicate names in the request are ignored. If a security category with one of the provided names exists already, then the request will fail and no security categories are created.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of categories to create

required
Array of objects (SecurityCategorySpecDTO) non-empty

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete security categories

Deletes the security categories that match the provided IDs. If any of the provided IDs does not belong to an existing security category, then the request will fail and no security categories are deleted.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of security category IDs to delete.

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Sessions

Sessions are used to maintain access to CDF resources for an extended period of time. The methods available to extend a sessions lifetime are client credentials and token exchange. Sessions depend on the project OIDC configuration and may become invalid in the following cases

  • Project OIDC configuration has been updated through the update project endpoint. This action invalidates all of the project's sessions.

  • The session was invalidated through the identity provider.

List sessions

List all sessions in the current project.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
status
string
Enum: "ready" "active" "cancelled" "revoked" "access_lost"

If given, only sessions with the given status are returned.

cursor
string

Cursor to use for paging through results.

limit
integer <int32> <= 1000
Default: 25

Return up to this many results. Maximum is 1000. Default is 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string",
  • "previousCursor": "string"
}

Create sessions

Create sessions

Authorizations:
oidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request containing the information needed to create a session.

Array of CreateSessionWithClientCredentialsRequest (object) or CreateSessionWithTokenExchangeRequest (object) (CreateSessionRequest) = 1 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve sessions with given IDs

Retrieves sessions with given IDs. The request will fail if any of the IDs does not belong to an existing session.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of session IDs to retrieve

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Revoke sessions

Revoke access to a session. Revocation of a session may in some cases take up to 1 hour to take effect.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request containing the information needed to revoke sessions.

Array of objects (RevokeSessionRequest)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Token

Access tokens issued by an IdP (Azure AD, Google, etc.) are used to access CDF resources.

Inspect

Inspect CDF access granted to an IdP issued token

Authorizations:
oidc-token

Responses

Response samples

Content type
application/json
{
  • "subject": "string",
  • "projects": [
    ],
  • "capabilities": [
    ]
}

Assets

The assets resource type stores digital representations of objects or groups of objects from the physical world. Assets are organized in hierarchies. For example, a water pump asset can be part of a subsystem asset on an oil platform asset.

List assets

List all assets, or only the assets matching the specified query.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

includeMetadata
boolean
Default: true

Whether the metadata field should be returned, or not.

name
string (AssetName) [ 1 .. 140 ] characters

The name of the asset.

parentIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: parentIds=[363848954441724, 793045462540095, 1261042166839739]

List only assets that have one of the parentIds as a parent. The parentId for root assets is null.

parentExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: parentExternalIds=[externalId_1, externalId_2, externalId_3]

List only assets that have one of the parentExternalIds as a parent. The parentId for root assets is null.

rootIds
string <jsonArray(int64)> (JsonArrayInt64)
Deprecated
Example: rootIds=[363848954441724, 793045462540095, 1261042166839739]

This parameter is deprecated. Use assetSubtreeIds instead. List only assets that have one of the rootIds as a root asset. A root asset is its own root asset.

assetSubtreeIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetSubtreeIds=[363848954441724, 793045462540095, 1261042166839739]

List only assets that are in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

assetSubtreeExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetSubtreeExternalIds=[externalId_1, externalId_2, externalId_3]

List only assets that are in a subtree rooted at any of these assetExternalIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

source
string <= 128 characters

The source of the asset, for example which database it's from.

root
boolean
Default: false

Whether the filtered assets are root assets, or not. Set to True to only list root assets.

minCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples 

const assets = await client.assets.list({ filter: { name: '21PT1019' } });

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create assets

You can create a maximum of 1000 assets per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of the assets to create. You can create a maximum of 1000 assets per request.

required
Array of objects (DataExternalAssetItem) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve an asset by its ID

Retrieve an asset by its ID. If you want to retrieve assets by externalIds, use Retrieve assets instead.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples 

const assets = await client.assets.retrieve([{id: 123}, {externalId: 'abc'}]);

Response samples

Content type
application/json
{
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "rootId": 1,
  • "aggregates": {
    },
  • "parentId": 1,
  • "parentExternalId": "my.known.id",
  • "externalId": "my.known.id",
  • "name": "string",
  • "description": "string",
  • "dataSetId": 1,
  • "metadata": {
    },
  • "source": "string",
  • "labels": [
    ],
  • "geoLocation": {
    },
  • "id": 1
}

Filter assets

Use advanced filtering options to find assets.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (Filter)

Filter on assets with strict matching.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
aggregatedProperties
Array of strings (AggregatedProperty)
Items Enum: "childCount" "path" "depth"

Set of aggregated properties to include

partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "aggregatedProperties": [
    ],
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Aggregate assets

Use advanced filtering options to agggregate assets.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (Filter)

Filter on assets with strict matching.

aggregate
string
Default: "count"
Enum: "metadataKeys" "metadataValues" "count"

Type of aggregation to apply. count - simple count of all assets permitted by the filter. metadataKeys - Get unique values (up to max 1000) of metadata keys ordered by frequency. metadataValues - Get unique values (up to max 1000) of values for a particular metadata key, ordered by frequency.

keys
Array of strings <= 1 items

For metadataValues aggregateType sets the metadata key(s) to apply the aggregation on. Currently supports exactly one key per request.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "aggregate": "metadataKeys",
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve assets

Retrieve assets by IDs or external IDs. If you specify to get aggregates then be aware that the aggregates are eventually consistent.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

All provided IDs and external IDs must be unique.

required
Array of AssetInternalId (object) or AssetExternalId (object) (AssetIdEither) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

aggregatedProperties
Array of strings (AggregatedProperty)
Items Enum: "childCount" "path" "depth"

Set of aggregated properties to include

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false,
  • "aggregatedProperties": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update assets

Update the attributes of assets.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

All provided IDs and external IDs must be unique. Fields that are not included in the request, are not changed.

required
Array of AssetChangeById (object) or AssetChangeByExternalId (object) (AssetChange) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Search assets

Fulltext search for assets based on result relevance. Primarily meant for human-centric use-cases, not for programs, since matching and ordering may change over time. Additional filters can also be specified. This operation does not support pagination.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Search query

object (Filter)

Filter on assets with strict matching.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

object (Search)

Fulltext search for assets. Primarily meant for for human-centric use-cases, not for programs. The query parameter uses a different search algorithm than the deprecated name and description parameters, and will generally give much better results.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "search": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete assets

Delete assets. By default, recursive=false and the request would fail if attempting to delete assets that are referenced as parent by other assets. To delete such assets and all its descendants, set recursive to true. The limit of the request does not include the number of descendants that are deleted.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of AssetInternalId (object) or AssetExternalId (object) (AssetIdEither) [ 1 .. 1000 ] items
recursive
boolean
Default: false

Recursively delete all asset subtrees under the specified IDs.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "recursive": false,
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Time series

A time series consists of a sequence of data points connected to a single asset.

For example: A water pump asset can have a temperature time series that records a data point in units of °C every second.

A single asset can have several time series. The water pump could have additional time series measuring pressure within the pump, rpm, flow volume, power consumption, and more.

Time series store data points as either number or strings. This is controlled by the is_string flag on the time series object. Numerical data points can be aggregated before they are returned from a query (e.g., to find the average temperature for a day). String data points, on the other hand, cannot be aggregated by CDF, but can store arbitrary information like states (e.g. “open”/”closed”) or more complex information (JSON).

Cognite stores discrete data points, but the underlying process measured by the data points can vary continuously. When interpolating between data points, we can either assume that each value stays the same until the next measurement, or that it linearly changes between the two measurements. This is controlled by the is_step flag on the time series object. For example, if we estimate the average over a time containing two data points, the average will either be close to the first (is step) or close to the mean of the two (not is step).

A data point stores a single piece of information, a number or a string, associated with a specific time. Data points are identified by their timestamps, measured in milliseconds since the unix epoch -- 00:00, January 1st, 1970. Timestamps are in the range from 00:00, January 1st, 1900 to 23:59, December 31st, 2050. Negative timestamps are used to define dates before 1970. Milliseconds is the finest time resolution supported by CDF i.e. fractional milliseconds are not supported. Leap seconds are not counted.

Numerical data points can be aggregated before they are retrieved from CDF. This allows for faster queries by reducing the amount of data transferred. You can aggregate data points by specifying one or more aggregates (e.g. average, minimum, maximum) as well as the time granularity over which the aggregates should be applied (e.g. “1h” for one hour).

Aggregates are aligned to the start time modulo the granularity unit. For example, if you ask for daily average temperatures since Monday afternoon last week, the first aggregated data point will contain averages for Monday, the second for Tuesday, etc. Determining aggregate alignment without considering data point timestamps allows CDF to pre-calculate aggregates (e.g. to quickly return daily average temperatures for a year). As a consequence, aggregating over 60 minutes can return a different result that aggregating over 1 hour because the two queries will be aligned differently.

Asset references obtained from a time series - through its asset id - may be invalid, simply by the non-transactional nature of HTTP. They are maintained in an eventual consistent manner.

List time series

List time series. Use nextCursor to paginate through the results.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return. CDF returns a maximum of 1000 results even if you specify a higher limit.

includeMetadata
boolean
Default: true

Whether the metadata field should be returned, or not.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

assetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetIds=[363848954441724, 793045462540095, 1261042166839739]

Get the time series related to the assets. The format is a list of IDs serialized as a JSON array(int64). Takes [ 1 .. 100 ] unique items.

rootAssetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: rootAssetIds=[363848954441724, 793045462540095, 1261042166839739]

Only include time series that have a related asset in a tree rooted at any of these root assetIds.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

Responses

Request samples 

const timeseries = await client.timeseries.list({ filter: { assetIds: [1, 2] }});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create time series

Create one or more time series.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (PostTimeSeriesMetadataDTO) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve time series

Retrieve one or more time series by ID or external ID. The time series are returned in the same order as in the request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of the IDs of the time series to retrieve.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) [ 1 .. 1000 ] items unique

List of ID objects

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter time series

Retrieves a list of time series matching the specified criteria. This operation supports pagination by cursor. Criteria can be applied to select a subset of time series.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (Filter)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Return up to this many results.

cursor
string
partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Aggregate time series

Count the number of time series that match the given filter

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Retrieves the count of time series matching the given criteria

object (Filter)

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Search time series

Fulltext search for time series based on result relevance. Primarily meant for human-centric use-cases, not for programs, since matching and ordering may change over time. Additional filters can also be specified. This operation does not support pagination.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (Filter)
object (Search)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Return up to this many results.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "search": {
    },
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update time series

Updates one or more time series. Fields that are not included in the request, are not changed.

For primitive fields (String, Long Int), use 'set': 'value' to update the value; use 'setNull': true to set the field to null.

For JSON Array fields (for example securityCategories), use 'set': [value1, value2] to update the value; use 'add': [v1, v2] to add values; use 'remove': [v1, v2] to remove values.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of changes.

required
Array of TimeSeriesUpdateById (object) or TimeSeriesUpdateByExternalId (object) (TimeSeriesUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete time series

Deletes the time series with the specified IDs and their datapoints.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Specify a list of the time series to delete.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) [ 1 .. 1000 ] items unique

List of ID objects

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Insert data points

Insert datapoints into a time series. You can do this for multiple time series. If you insert a datapoint with a timestamp that already exists, it will be overwritten with the new value.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema:

The datapoints to insert.

required
Array of DatapointsWithInternalId (object) or DatapointsWithExternalId (object) (DatapointsPostDatapoint) [ 1 .. 10000 ] items

Responses

Request samples

Content type
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve data points

Retrieves a list of data points from multiple time series in a project. This operation supports aggregation, but not pagination. A detailed description of how aggregates work can be found at our concept guide for aggregation.

Note: when the 'start' is not specified neither in top level and for individual item it will default to epoch 0 which is Jan 1st, 1970 thus, excluding potential existent datapoints before 1970. 'start' needs to be specified to get datapoints before 1970.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Specify parameters to query for multiple datapoints. If you omit fields in individual datapoint query items, the top-level field values are used. For example, you can specify a default limit for all items by setting the top-level limit field. If you request aggregates, only the aggregates are returned. If you don't request any aggregates, all data points are returned.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (DatapointsQuery) [ 1 .. 100 ] items
integer or string (TimestampOrStringStart)

Get datapoints starting from, and including, this time. The format is N[timeunit]-ago where timeunit is w,d,h,m,s. Example: '2d-ago' gets datapoints that are up to 2 days old. You can also specify time in milliseconds since epoch. Note that for aggregates, the start time is rounded down to a whole granularity unit (in UTC timezone). Daily granularities (d) are rounded to 0:00 AM; hourly granularities (h) to the start of the hour, etc.

integer or string (TimestampOrStringEnd)

Get datapoints up to, but excluding, this point in time. Same format as for start. Note that when using aggregates, the end will be rounded up such that the last aggregate represents a full aggregation interval containing the original end, where the interval is the granularity unit times the granularity multiplier. For granularity 2d, the aggregation interval is 2 days, if end was originally 3 days after the start, it will be rounded to 4 days after the start.

limit
integer <int32>
Default: 100

Return up to this number of datapoints. The maximum is 100000 non-aggregated data points and 10000 aggregated data points in total across all queries in a single request.

aggregates
Array of strings (Aggregate) [ 1 .. 10 ] items unique
Items Enum: "average" "max" "min" "count" "sum" "interpolation" "stepInterpolation" "totalVariation" "continuousVariance" "discreteVariance"

Specify the aggregates to return, or an empty array if this sub-query should return datapoints without aggregation. This value overrides a top-level default aggregates list.

granularity
string

The time granularity size and unit to aggregate over. Valid entries are 'day, hour, minute, second', or short forms 'd, h, m, s', or a multiple of these indicated by a number as a prefix. For 'second' and 'minute' the multiple must be an integer betwen 1 and 120 inclusive, for 'hour' and 'day' the multiple must be an integer between 1 and 100000 inclusive. For example, a granularity '5m' means that aggregates are calculated over 5 minutes. This field is required if aggregates are specified.

includeOutsidePoints
boolean
Default: false

Whether to include the last datapoint before the requested time period, and the first one after. This option can be useful for interpolating data. It is not available for aggregates. Note: If there are more than limit datapoints in the time period, we will omit the excess datapoints, and then append the first datapoint after the time period, thus causing a gap with omitted datapoints. When this is the case, we return up to limit+2 datapoints. Paging should be done from the second to last datapoint. That is, from the last datapoint in the requested time period.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "start": 0,
  • "end": 0,
  • "limit": 100,
  • "aggregates": [
    ],
  • "granularity": "1h",
  • "includeOutsidePoints": false,
  • "ignoreUnknownIds": false
}

Response samples

Content type
{
  • "items": [
    ]
}

Retrieve latest data point

Retrieves the latest data point in a time series.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The list of the queries to perform.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (LatestDataBeforeRequest) [ 1 .. 100 ] items

List of latest queries

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete datapoints

Delete datapoints from time series.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The list of delete requests to perform.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (DatapointsDeleteRequest) [ 1 .. 10000 ] items

List of delete filters

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Synthetic Time Series

Synthetic Time Series (STS) is a way to combine various input time series, constants and operators, to create completely new time series.

For example can we use the expression 24 * TS{externalId='production/hour'} to convert from hourly to daily production rates.

But STS is not limited to simple conversions.

  • We support combination of different time series TS{id=123} + TS{externalId='hei'}.
  • Functions of time series sin(pow(TS{id=123}, 2)).
  • Aggregations of time series TS{id=123, aggregate='average', granularity='1h'}+TS{id=456}

To learn more about synthetic time series please follow our guide.

Synthetic query

Execute an on-the-fly synthetic query

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The list of queries to perform

required
Array of objects (SyntheticQuery) [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Events

Event objects store complex information about multiple assets over a time period. For example, an event can describe two hours of maintenance on a water pump and some associated pipes, or a future time window where the pump is scheduled for inspection. This is in contrast with data points in time series that store single pieces of information about one asset at specific points in time (e.g., temperature measurements).

An event’s time period is defined by a start time and end time, both millisecond timestamps since the UNIX epoch. The timestamps can be in the future. In addition, events can have a text description as well as arbitrary metadata and properties.

Asset references obtained from an event - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are maintained in an eventual consistent manner.

Create events

Creates multiple event objects in the same project. It is possible to post a maximum of 1000 events per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of events to be posted. It is possible to post a maximum of 1000 events per request.

required
Array of objects (ExternalEvent) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter events

List events optionally filtered on query parameters

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

minStartTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxStartTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minEndTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxEndTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minActiveAtTime
integer <int64> >= 0

Event is considered active from its startTime to endTime inclusive. If startTime is null, event is never active. If endTime is null, event is active from startTime onwards. activeAtTime filter will match all events that are active at some point from min to max, from min, or to max, depending on which of min and max parameters are specified.

maxActiveAtTime
integer <int64> >= 0

Event is considered active from its startTime to endTime inclusive. If startTime is null, event is never active. If endTime is null, event is active from startTime onwards. activeAtTime filter will match all events that are active at some point from min to max, from min, or to max, depending on which of min and max parameters are specified.

assetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetIds=[363848954441724, 793045462540095, 1261042166839739]

Asset IDs of equipment that this event relates to. Format is list of IDs serialized as JSON array(int64). Takes [ 1 .. 100 ] of unique items.

assetExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetExternalIds=["externalId1", "externalId2", "externalId3"]

Asset external IDs of equipment that this event relates to. Takes 1..100 unique items.

assetSubtreeIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetSubtreeIds=[363848954441724, 793045462540095, 1261042166839739]

Only include events that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

assetSubtreeExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetSubtreeExternalIds=["externalId1", "externalId2", "externalId3"]

Only include events that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

source
string <= 128 characters

The source of this event.

type
string (EventType) <= 64 characters

Type of the event, e.g 'failure'.

subtype
string (EventSubType) <= 64 characters

SubType of the event, e.g 'electrical'.

minCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

includeMetadata
boolean
Default: true

Whether the metadata field should be returned, or not.

sort
Array of strings
Example: sort=endTime:desc

Sort by array of selected fields. Syntax: ["<fieldname>:asc|desc"]. Default sort order is asc with short syntax: ["<fieldname>"]. Filter accepts the following field names: externalId, type, subtype, startTime, endTime, createdTime, lastUpdatedTime, source, description, metadata. Partitions are done independently of sorting, there is no guarantee on sort order between elements from different partitions.

Responses

Request samples 

const events = await client.events.list({ filter: { startTime: { min: new Date('1 jan 2018') }, endTime: { max: new Date('1 jan 2019') } } });

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Receive event by ID

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples 

const events = await client.events.retrieve([{id: 123}, {externalId: 'abc'}]);

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "dataSetId": 1,
  • "startTime": 0,
  • "endTime": 0,
  • "type": "string",
  • "subtype": "string",
  • "description": "string",
  • "metadata": {
    },
  • "assetIds": [
    ],
  • "source": "string",
  • "id": 1,
  • "lastUpdatedTime": 0,
  • "createdTime": 0
}

Filter all events

Retrieve a list of all events in the same project. This operation supports pagination by cursor. Criteria can be applied to select a subset of events.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
One of
object (EventFilter)

Filter on events filter with exact match

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Limits the maximum number of results to be returned by single request. In case there are more results to the request 'nextCursor' attribute will be provided as part of response. Request may contain less results than request limit.

Array of objects (SortProperty)

Sort by array of selected properties. order field is optional and defaults to asc. Sorting can be done on the following properties: externalId, type, subtype, startTime, endTime, createdTime, lastUpdatedTime, source, description, metadata. Partitions are done independently of sorting, there is no guarantee on sort order between elements from different partitions. Example:

[
  {
    "property" : ["createdTime"],
    "order": "desc"
  },
  {
    "property" : ["metadata", "FooBar"]
  }
]
cursor
string
partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples

Content type
application/json
Example
{
  • "filter": {
    },
  • "limit": 100,
  • "sort": [
    ],
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Aggregate events

The aggregation API allows you to compute aggregated results on events like getting the count of all events in a project or checking what are all the different types and subtypes of events in your project, along with the count of events in each of those aggregations. By specifying an additional filter, you can also aggregate only among events matching the specified filter.

The default behavior, when you do not specify the aggregate field in the request body, is to return the count of events.

Setting aggregate to uniqueValues will return all unique values (up to a maximum of 1000) and the count of each in the field specified in fields: []. Note that, currently, you can only request for unique values on a single field. Also, in the case of text fields, the values are aggregated in a case-insensitive manner. For example:

{
  "aggregate": "uniqueValues",
  "fields": [ "type" ]
}

will return all unique 'types' in the events in your project.

Similarly,

{
  "aggregate": "uniqueValues",
  "fields": [ "dataSetId" ],
  "filter": {
    "subType": "subtype_1"
  }
}

will return all unique dataSetIds in events of subtype 'subtype_1'

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
One of
Deprecated
fields
required
Array of strings <= 1 items
Items Enum: "type" "subtype" "dataSetId"

The field name(s) to apply the aggregation on. Currently limited to one field.

object (EventFilter)

Filter on events filter with exact match

aggregate
required
string
Value: "uniqueValues"

Type of aggregation to apply. uniqueValues - Get unique values (upto max 1000) in the specified field ordered by frequency.

Responses

Request samples

Content type
application/json
Example
{
  • "filter": {
    },
  • "aggregate": "uniqueValues",
  • "fields": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "items": [
    ]
}

Retrieve events

Retrieves information about events in the same project. Events are returned in the same order as the ids listed in the query.

A maximum of 1000 event IDs may be listed per request and all of them must be unique.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of IDs of events to retrieve. Must be up to a maximum of 1000 IDs, and all of them must be unique.

required
Array of InternalId (object) or ExternalId (object) (EitherId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update events

Updates events in the same project. This operation supports partial updates; Fields omitted from queries will remain unchanged on objects.

For primitive fields (String, Long, Int), use 'set': 'value' to update value; use 'setNull': true to set that field to null.

For the Json Array field (e.g. assetIds), use 'set': [value1, value2] to update value; use 'add': [v1, v2] to add values to current list of values; use 'remove': [v1, v2] to remove these values from current list of values if exists.

A maximum of 1000 events can be updated per request, and all of the event IDs must be unique.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of changes. A maximum of 1000 events can be updated per request, and all of the event IDs must be unique.

required
Array of EventChangeById (object) or EventChangeByExternalId (object) (EventChange) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Search within events

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (EventFilter)

Filter on events filter with exact match

object (EventSearch)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Limits the maximum number of results to be returned by single request. Request may contain less results than request limit.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "search": {
    },
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete multiple events

Deletes events with the given ids. A maximum of 1000 events can be deleted per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of IDs to delete.

required
Array of InternalId (object) or ExternalId (object) (EitherId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Files

A file stores a sequence of bytes connected to one or more assets. For example, a file can contain a piping and instrumentation diagram (P&IDs) showing how multiple assets are connected.

Each file is identified by the 'id' field, which is generated internally for each new file. Each file's 'id' field is unique within a project.

The 'externalId' field is optional, but can also be used to identify a file. The 'externalId' (if used) must be unique within a project.

Files are created in two steps; First the metadata is stored in a file object, and then the file contents are uploaded. This means that files can exist in a non-uploaded state. The upload state is reflected in the 'uploaded' field in responses.

Asset references obtained from a file - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are maintained in an eventual consistent manner.

Upload file

Create metadata information and get an upload link for a file.

To upload the file, use the uploadUrl link in the response in a separate request. To upload a file, send an HTTP PUT request to the uploadUrl with the relevant 'Content-Type' and 'Content-Length' headers.

If the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request as documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.

The uploadUrl expires after one week. Any file info entry that does not have the actual file uploaded within one week will be automatically deleted.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
overwrite
boolean
Default: false

If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false.

If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after a successful upload with the uploadUrl from the response. If there is no successful upload, the current file contents will be kept.

File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

header Parameters
Origin
string

The 'Origin' header parameter is required if there is a Cross Origin issue.

Request Body schema: application/json

Fields to be set for the file.

externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

name
required
string (FileName) <= 256 characters

Name of the file.

directory
string (FileDirectory) <= 512 characters

Directory containing the file. Must be an absolute, unix-style path.

source
string (FileSource) <= 128 characters

The source of the file.

mimeType
string (MimeType) <= 256 characters

File type. E.g. text/plain, application/pdf, ..

object (FilesMetadataField)

Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

assetIds
Array of integers <int64> (CogniteInternalId) [ 1 .. 1000 ] items [ items <int64 > [ 1 .. 9007199254740991 ] ]
dataSetId
integer <int64> (DataSetId) [ 1 .. 9007199254740991 ]

The dataSet Id for the item.

sourceCreatedTime
integer <int64> >= 0

The timestamp for when the file was originally created in the source system.

sourceModifiedTime
integer <int64> >= 0

The timestamp for when the file was last modified in the source system.

securityCategories
Array of integers <int64> (CogniteInternalId) [ 0 .. 100 ] items [ items <int64 > [ 1 .. 9007199254740991 ] ]

The security category IDs required to access this file.

Array of objects (LabelList) [ 0 .. 10 ] items unique

A list of the labels associated with this resource item.

object (GeoLocation)

Geographic metadata.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    },
  • "assetIds": [
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    ],
  • "labels": [
    ],
  • "geoLocation": {
    }
}

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    },
  • "assetIds": [
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    ],
  • "labels": [
    ],
  • "geoLocation": {
    },
  • "id": 1,
  • "uploaded": true,
  • "uploadedTime": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "uploadUrl": "string"
}

List files

The GET /files operation can be used to return information for all files in a project.

Optionally you can add one or more of the following query parameters. The filter query parameters will filter the results to only include files that match all filter parameters.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

name
string (FileName) <= 256 characters

Name of the file.

mimeType
string (MimeType) <= 256 characters
Example: mimeType=image/jpeg

File type. E.g. text/plain, application/pdf, ..

source
string (FileSource) <= 128 characters

The source of the file.

assetIds
Array of integers <int64> (AssetIds) [ 1 .. 100 ] items unique [ items <int64 > [ 1 .. 9007199254740991 ] ]
Example: assetIds=363848954441724&assetIds=793045462540095&assetIds=1261042166839739

Only include files that reference these specific asset IDs.

assetExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetExternalIds=["externalId1", "externalId2", "externalId3"]

Asset external IDs of related equipment that this file relates to. Takes 1..100 unique items.

Array of DataSetInternalId (object) or DataSetExternalId (object) (DataSetIdEithers)
rootAssetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: rootAssetIds=[363848954441724, 793045462540095, 1261042166839739]

Only include files that have a related asset in a tree rooted at any of these root assetIds.

assetSubtreeIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetSubtreeIds=[363848954441724, 793045462540095, 1261042166839739]

Only include files that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

assetSubtreeExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetSubtreeExternalIds=["externalId1", "externalId2", "externalId3"]

Only include files that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

minCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minUploadedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxUploadedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minSourceCreatedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceCreatedTime set and with minimum this value.

maxSourceCreatedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceCreatedTime set and with maximum this value.

minSourceModifiedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceModifiedTime set and with minimum this value.

maxSourceModifiedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceModifiedTime set and with maximum this value.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

uploaded
boolean
Example: uploaded=true

Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.

partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples 

const files = await client.files.list({filter: {mimeType: 'image/png'}});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Retrieve file by id

Returns file info for the file ID

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples 

const files = await client.files.retrieve([{id: 123}, {externalId: 'abc'}]);

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    },
  • "assetIds": [
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    ],
  • "labels": [
    ],
  • "geoLocation": {
    },
  • "id": 1,
  • "uploaded": true,
  • "uploadedTime": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0
}

Filter files

Retrieves a list of all files in a project. Criteria can be supplied to select a subset of files. This operation supports pagination with cursors.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The project name

object
partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Maximum number of items that the client want to get back.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "partition": "1/10",
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Retrieve files

Retrieves metadata information about multiple specific files in the same project. Results are returned in the same order as in the request. This operation does not return the file contents.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of IDs of files to retrieve. Must be up to a maximum of 1000 IDs, and all of them must be unique.

required
Array of Select by Id (object) or Select by ExternalId (object) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Search files

Search for files based on relevance. You can also supply a strict match filter as in Filter files, and search in the results from the filter. Returns first 1000 results based on relevance. This operation does not support pagination.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object
object

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "search": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete files

Deletes the files with the given ids.

A maximum of 1000 files can be deleted per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of IDs of files to delete.

Array of FileInternalId (object) or FileExternalId (object) (FileIdEither) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Get icon

The GET /files/icon operation can be used to get an image representation of a file.

Either id or externalId must be provided as a query parameter (but not both). Supported file formats:

  • Normal jpeg and png files are currently fully supported.
  • Other image file formats might work, but continued support for these are not guaranteed.
  • Currently only supporting thumbnails for image files. Attempts to get icon for unsupported files will result in status 400.
Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
id
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

externalId
string (CogniteExternalId) <= 255 characters
Example: externalId=my.known.id

The external ID provided by the client. Must be unique for the resource type.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update files

Updates the information for the files specified in the request body.

If you want to update the file content, uploaded using the uploadUrl, please use the initFileUpload request with the query parameter 'overwrite=true'. Alternatively, delete and recreate the file.

For primitive fields (String, Long, Int), use 'set': 'value' to update value; use 'setNull': true to set that field to null.

For the Json Array field (e.g. assetIds and securityCategories): Use either only 'set', or a combination of 'add' and/or 'remove'.

AssetIds update examples:

Example request body to overwrite assetIds with a new set, asset ID 1 and 2.

{
  "items": [
    {
      "id": 1,
      "update": {
        "assetIds" : {
          "set" : [ 1, 2 ]
        }
      }
    }
  ]
}

Example request body to add one asset Id, and remove another asset ID.

{
  "items": [
    {
      "id": 1,
      "update": {
        "assetIds" : {
          "add" : [ 3 ],
          "remove": [ 2 ]
        }
      }
    }
  ]
}

Metadata update examples:

Example request body to overwrite metadata with a new set.

{
  "items": [
    {
      "id": 1,
      "update": {
        "metadata": {
          "set": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      }
    }
  ]
}

Example request body to add two key-value pairs and remove two other key-value pairs by key for the metadata field.

{
  "items": [
    {
      "id": 1,
      "update": {
        "metadata": {
          "add": {
            "key3": "value3",
            "key4": "value4"
          },
          "remove": [
            "key1",
            "key2"
          ]
        }
      }
    }
  ]
}
Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The JSON request body which specifies which files and fields to update.

required
Array of FileChangeUpdateById (object) or FileChangeUpdateByExternalId (object) (FileChangeUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Aggregate files

Calculate aggregates for files, based on optional filter specification. Returns the following aggregates: count

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Files aggregate request body

object

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Sequences

A sequence stores a table with up to 400 columns indexed by row number. There can be at most 400 numeric columns and 200 string columns. Each of the columns has a pre-defined type which is a string, integer, or floating point number.

For example, a sequence can represent a curve, either with the dependent variable x as the row number and a single value column y, or can simply store (x,y) pair in the rows directly. Other potential applications include data logs in which the index is not time-based. To learn more about sequences, see the concept guide.

List sequences

List sequences. Use nextCursor to paginate through the results.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

limit
integer [ 1 .. 1000 ]
Default: 25

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses

Request samples 

const sequences = await client.sequences.list({ filter: { name: 'sequence_name' } });

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create sequences

Create one or more sequences.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Sequence to be stored

required
Array of objects (PostSequenceDTO) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter sequences

Retrieves a list of sequences matching the given criteria.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Retrieves a list of sequences matching the given criteria.

object (SequenceFilter)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Return up to this many results per page.

cursor
string
partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Aggregate sequences

Count the number of sequences that match the given filter

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Retrieves the count of sequences matching the given criteria.

object (SequenceFilter)

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve sequences

Retrieve one or more sequences by ID or external ID. The sequences are returned in the same order as in the request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Ids of the sequences

required
Array of Select by Id (object) or Select by ExternalId (object) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Search sequences

Retrieves a list of sequences matching the given criteria. This operation does not support pagination.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Retrieves a list of sequences matching the given criteria. This operation does not support pagination.

object (SequenceFilter)
object (SequenceSearch)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Return up to this many results.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "search": {
    },
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update sequences

Update one or more sequences. Fields that are not included in the request, are not changed.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Patch definition

required
Array of Select by Id (object) or Select by ExternalId (object) (SequencesUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete sequences

Deletes the sequences with the specified IDs. If one or more of the sequences do not exist, ignoreUnknownIds controls what will happen: if it is true, the sequences that do exist will be deleted, and the request succeeds; if it is false or absent, nothing will be deleted, and the request fails.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Ids of the sequences to delete

required
Array of Select by Id (object) or Select by ExternalId (object) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Insert rows

Inserts rows into a sequence. This overwrites data in rows and columns that exist.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Data posted

required
Array of Select by Id (object) or Select by ExternalId (object) (SequencePostData) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve rows

Processes data requests, and returns the result. NB - This operation uses a dynamic limit on the number of rows returned based on the number and type of columns, use the provided cursor to paginate and retrieve all data.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Description of data requested

One of
start
integer <int64>
Default: 0

Lowest row number included.

end
integer <int64>

Get rows up to, but excluding, this row number. Default - No limit

limit
integer <int32> [ 1 .. 10000 ]
Default: 100

Maximum number of rows returned in one request. Api might return less even if there is more data, but it will then provide a cursor for continuation. If there is more data beyond this limit, a cursor will be returned to simplify further fetching of data.

cursor
string

Cursor for pagination returned from a previous request. Apart from this cursor, the rest of the request object have be the same as for the original request.

columns
Array of strings [ 1 .. 400 ] items

Columns to be included. Specified as list of column externalIds. In case this filter is not set, all available columns will be returned.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

Content type
application/json
Example
{
  • "start": 0,
  • "end": 1,
  • "limit": 1,
  • "cursor": "string",
  • "columns": [
    ],
  • "id": 1
}

Response samples

Content type
application/json
{
  • "id": 1112,
  • "externalId": "DL/DRILL412/20190103/T3",
  • "columns": [
    ],
  • "rows": [
    ],
  • "nextCursor": "string"
}

Retrieve latest row

Retrieves the last row (i.e the row with the highest row number) in a sequence.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Description of data requested

One of
columns
Array of strings [ 1 .. 400 ] items

Columns to be included. Specified as list of column externalIds. In case this filter is not set, all available columns will be returned.

before
integer <int64> >= 1

Get rows up to but not including this row number.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

Content type
application/json
Example
{
  • "columns": [
    ],
  • "before": 1,
  • "id": 1
}

Response samples

Content type
application/json
{
  • "id": 1112,
  • "externalId": "DL/DRILL412/20190103/T3",
  • "columns": [
    ],
  • "rows": [
    ]
}

Delete rows

Deletes the given rows of the sequence. All columns are affected.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Indicate the sequences and the rows where data should be deleted

required
Array of Select by Id (object) or Select by ExternalId (object) (SequenceDeleteDataRequest) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Geospatial

The Geospatial API allows to model a problem domain when data has a geometric or geographic nature. The geospatial data is organized in feature types that are homogeneous collections of features (geospatial items), each having the same spatial representation, such as points, lines, or polygons, and a common set of typed properties. The Geospatial API is aware of Coordinate Reference Systems, and allows transformations. To learn more about geospatial concepts, see the concept guide.

List Coordinate Reference Systems

List the defined Coordinate Reference Systems. The list can be limited to the custom Coordinate Reference Systems defined for the tenant.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
filterOnlyCustom
boolean
Example: filterOnlyCustom=true

Optional parameter to only list custom Coordinate Reference Systems. Defaults to false.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create Coordinate Reference Systems

Creates custom Coordinate Reference Systems.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of custom Coordinate Reference Systems to be created.

required
Array of objects (GeospatialCoordinateReferenceSystem)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get Coordinate Reference Systems

Get Coordinate Reference Systems by their Spatial Reference IDs

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete Coordinate Reference Systems

Delete custom Coordinate Reference Systems.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of custom Coordinate Reference Systems to be deleted.

required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Create feature types

Creates feature types. Each tenant can have up to 100 feature types.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of feature types to be created. It is possible to create up to 100 feature types in one request provided the total number of feature types on the tenant will not exceed 100.

required
Array of objects (GeospatialFeatureTypeSpec) [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve feature types

Retrieves feature types by external ids. It is possible to retrieve up to 100 items per request, i.e. the maximum number of feature types for a tenant.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List feature types

List all feature types

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update feature types

Update one or more feature types

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of feature types to be updated. It is possible to add and remove properties and indexes. WARNING: removing properties will result in data loss in corresponding features.

required
Array of objects (GeospatialUpdateFeatureTypeSpec) [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete feature types

Delete feature types.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of feature types to be deleted. It is possible to delete a maximum of 10 feature types per request. Feature types must not have related features. Feature types with related features can be deleted using force flag.

recursive
boolean (GeospatialRecursiveDelete)

Indicates if feature types should be deleted together with all related features. Optional parameter, defaults to false.

required
Array of objects [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Create features

Create features

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json
allowCrsTransformation
boolean (GeospatialAllowCrsTransformation)

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

required
Array of objects (GeospatialFeatureSpec) [ 1 .. 1000 ] items [ items <= 200 properties ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get features

Get features with paging support

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer (SearchLimit) [ 1 .. 1000 ]
Default: 1000

Limits the number of results to be returned.

allowCrsTransformation
boolean (GeospatialAllowCrsTransformation)
Example: allowCrsTransformation=true

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

allowDimensionalityMismatch
boolean (GeospatialAllowDimensionalityMismatch)
Example: allowDimensionalityMismatch=true

Optional parameter indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. For instance, when set to true, if a feature type has a property of type POLYGONZM (4D), its features can be filtered using the stContains operator and a POLYGON (2D) value. This option defaults to false if not specified.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "pwGTFXeL-JiWO8CZpgP23g"
}

Filter all features

List features based on the feature property filter passed in the body of the request. This operation supports pagination by cursor.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json
allowCrsTransformation
boolean (GeospatialAllowCrsTransformation)

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

allowDimensionalityMismatch
boolean (GeospatialAllowDimensionalityMismatch)

Optional parameter indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. For instance, when set to true, if a feature type has a property of type POLYGONZM (4D), its features can be filtered using the stContains operator and a POLYGON (2D) value. This option defaults to false if not specified.

GeospatialFeatureNotFilter (object) or GeospatialFeatureAndFilter (object) or GeospatialFeatureOrFilter (object) or GeospatialFeatureEqualsFilter (object) or GeospatialFeatureMissingFilter (object) or GeospatialFeatureLikeFilter (object) or GeospatialFeatureRegexFilter (object) or GeospatialFeatureRangeFilter (object) or GeospatialFeatureContainsAnyFilter (object) or GeospatialFeatureInFilter (object) or GeospatialFeatureStIntersectsFilter (object) or GeospatialFeatureStIntersects3dFilter (object) or GeospatialFeatureStWithinFilter (object) or GeospatialFeatureStWithinProperlyFilter (object) or GeospatialFeatureStContainsFilter (object) or GeospatialFeatureStContainsProperlyFilter (object) or GeospatialFeatureStWithinDistanceFilter (object) or GeospatialFeatureStWithinDistance3dFilter (object) (GeospatialFeatureFilter)
limit
integer (SearchLimit) [ 1 .. 1000 ]
Default: 1000

Limits the number of results to be returned.

object (GeospatialOutput)

Desired output specification.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "pwGTFXeL-JiWO8CZpgP23g"
}

Retrieve features

Retrieves features by external ids. It is possible to retrieve up to 1000 items per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json
required
Array of objects (GeospatialItemExternalId) [ 1 .. 1000 ] items
object (GeospatialOutput)

Desired output specification.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update features

Update features. This is a replace operation, i.e., all feature properties have to be sent in the request body even if their values do not change.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json

List of features to update.

allowCrsTransformation
boolean (GeospatialAllowCrsTransformation)

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

required
Array of objects (GeospatialFeatureSpec) [ 1 .. 1000 ] items [ items <= 200 properties ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete features

Delete features.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json

List of features to be deleted. It is possible to post a maximum of 1000 items per request.

required
Array of objects (GeospatialItemExternalId) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Search features

Search for features based on the feature property filter passed in the body of the request. The result of the search is limited to a maximum of 1000 items. Results in excess of the limit are truncated. This means that the complete result set of the search cannot be retrieved with this method. However, for a given unmodified feature collection, the result of the search is deterministic and does not change over time.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json
allowCrsTransformation
boolean (GeospatialAllowCrsTransformation)

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

allowDimensionalityMismatch
boolean (GeospatialAllowDimensionalityMismatch)

Optional parameter indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. For instance, when set to true, if a feature type has a property of type POLYGONZM (4D), its features can be filtered using the stContains operator and a POLYGON (2D) value. This option defaults to false if not specified.

GeospatialFeatureNotFilter (object) or GeospatialFeatureAndFilter (object) or GeospatialFeatureOrFilter (object) or GeospatialFeatureEqualsFilter (object) or GeospatialFeatureMissingFilter (object) or GeospatialFeatureLikeFilter (object) or GeospatialFeatureRegexFilter (object) or GeospatialFeatureRangeFilter (object) or GeospatialFeatureContainsAnyFilter (object) or GeospatialFeatureInFilter (object) or GeospatialFeatureStIntersectsFilter (object) or GeospatialFeatureStIntersects3dFilter (object) or GeospatialFeatureStWithinFilter (object) or GeospatialFeatureStWithinProperlyFilter (object) or GeospatialFeatureStContainsFilter (object) or GeospatialFeatureStContainsProperlyFilter (object) or GeospatialFeatureStWithinDistanceFilter (object) or GeospatialFeatureStWithinDistance3dFilter (object) (GeospatialFeatureFilter)
limit
integer (SearchLimit) [ 1 .. 1000 ]
Default: 1000

Limits the number of results to be returned.

object (GeospatialOutput)

Desired output specification.

sort
Array of strings

Sort result by selected fields. Syntax: sort:["field_1","field_2:ASC","field_3:DESC"]. Default sort order is ascending if not specified. Available sort direction: ASC, DESC, ASC_NULLS_FIRST, DESC_NULLS_FIRST, ASC_NULLS_LAST, DESC_NULLS_LAST.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "sort": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Search and stream features

Search for features based on the feature property filter passed in the body of the request. The streaming response format can be length prefixed, new line delimited, record separator delimited or concatenated depending on requested output (see https://en.wikipedia.org/wiki/JSON_streaming).

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json
allowCrsTransformation
boolean (GeospatialAllowCrsTransformation)

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

allowDimensionalityMismatch
boolean (GeospatialAllowDimensionalityMismatch)

Optional parameter indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. For instance, when set to true, if a feature type has a property of type POLYGONZM (4D), its features can be filtered using the stContains operator and a POLYGON (2D) value. This option defaults to false if not specified.

GeospatialFeatureNotFilter (object) or GeospatialFeatureAndFilter (object) or GeospatialFeatureOrFilter (object) or GeospatialFeatureEqualsFilter (object) or GeospatialFeatureMissingFilter (object) or GeospatialFeatureLikeFilter (object) or GeospatialFeatureRegexFilter (object) or GeospatialFeatureRangeFilter (object) or GeospatialFeatureContainsAnyFilter (object) or GeospatialFeatureInFilter (object) or GeospatialFeatureStIntersectsFilter (object) or GeospatialFeatureStIntersects3dFilter (object) or GeospatialFeatureStWithinFilter (object) or GeospatialFeatureStWithinProperlyFilter (object) or GeospatialFeatureStContainsFilter (object) or GeospatialFeatureStContainsProperlyFilter (object) or GeospatialFeatureStWithinDistanceFilter (object) or GeospatialFeatureStWithinDistance3dFilter (object) (GeospatialFeatureFilter)
limit
number
object (GeospatialOutputStreaming)

Desired output specification for streaming.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "output": {
    }
}

Response samples

Content type
application/json-seq
{
  • "property1": "string",
  • "property2": "string",
  • "externalId": "my.known.id",
  • "createdTime": 0,
  • "lastUpdatedTime": 0
}

Aggregate features

Search for features based on the feature property filter and perform requested aggregations on a given property. Aggregations are supported for all filters that do not contain stWithin, stWithinProperly, stContains and stContainsProperly search in 3D geometries.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Request Body schema: application/json
allowDimensionalityMismatch
boolean (GeospatialAllowDimensionalityMismatch)

Optional parameter indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. For instance, when set to true, if a feature type has a property of type POLYGONZM (4D), its features can be filtered using the stContains operator and a POLYGON (2D) value. This option defaults to false if not specified.

GeospatialFeatureNotFilter (object) or GeospatialFeatureAndFilter (object) or GeospatialFeatureOrFilter (object) or GeospatialFeatureEqualsFilter (object) or GeospatialFeatureMissingFilter (object) or GeospatialFeatureLikeFilter (object) or GeospatialFeatureRegexFilter (object) or GeospatialFeatureRangeFilter (object) or GeospatialFeatureContainsAnyFilter (object) or GeospatialFeatureInFilter (object) or GeospatialFeatureStIntersectsFilter (object) or GeospatialFeatureStIntersects3dFilter (object) or GeospatialFeatureStWithinFilter (object) or GeospatialFeatureStWithinProperlyFilter (object) or GeospatialFeatureStContainsFilter (object) or GeospatialFeatureStContainsProperlyFilter (object) or GeospatialFeatureStWithinDistanceFilter (object) or GeospatialFeatureStWithinDistance3dFilter (object) (GeospatialFeatureFilter)
aggregates
Array of strings
Deprecated
Items Enum: "avg" "count" "max" "min" "stCentroid" "stCollect" "stConvexHull" "stIntersection" "stUnion" "sum" "variance"

This parameter is deprecated. Use output instead. Names of aggregate functions that are requested.

property
string
Deprecated

This parameter is deprecated. Use output instead. Property name.

outputSrid
integer (GeospatialReferenceId) [ 0 .. 1000000 ]

EPSG code, e.g. 4326. Only valid for geometry types. See https://en.wikipedia.org/wiki/Spatial_reference_system

groupBy
Array of strings

names of properties to be used for grouping by

sort
Array of strings

Sort result by the selected fields (properties or aggregates). Default sort order is ascending if not specified. Available sort direction: ASC, DESC, ASC_NULLS_FIRST, DESC_NULLS_FIRST, ASC_NULLS_LAST, DESC_NULLS_LAST.

object (GeospatialAggregateOutput)

A list of aggregations which are requested.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "groupBy": [
    ],
  • "sort": [
    ],
  • "output": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Put a raster into a feature property

Put a raster into a feature property. The feature property must be of type RASTER.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

featureExternalId
required
string <= 256 characters ^[A-Za-z][A-Za-z0-9_]{0,255}$
Example: ocean_measure_W87H62

External Id of the type provided by client. Must be unique among all feature external ids within a CDF project and feature type.

rasterPropertyName
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: bathymetry

Raster Id of the raster property provided by client. Must be unique among all feature property names within a feature type.

query Parameters
srid
required
integer [ 1 .. 999999 ]
Example: srid=3857

mandatory parameter that specifies the SRID of the coordinate reference system of a raster.

format
required
string
Value: "XYZ"
Example: format=XYZ

mandatory parameter that specifies the format of the input raster.

scaleX
number <double>
Example: scaleX=2

optional parameter that specifies the pixel scale x in storage. If not specified, the pixel scale remains the same as the input raster.

scaleY
number <double>
Example: scaleY=2

optional parameter that specifies the pixel scale y in storage. If not specified, the pixel scale remains the same as the input raster.

allowCrsTransformation
boolean
Example: allowCrsTransformation=true

Optional parameter indicating if the input raster coordinates should be transformed into the Coordinate Reference Systems defined for the raster property in the feature type specification. The transformation will typically impact the pixel values. When the parameter is false, requests with rasters in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code.

Request Body schema: application/octet-stream
any <binary>

Responses

Response samples

Content type
application/json
{
  • "srid": 3857,
  • "width": 4,
  • "height": 5,
  • "numBands": 1,
  • "scaleX": 1,
  • "scaleY": 1,
  • "skewX": 0,
  • "skewY": 0,
  • "upperLeftX": -0.5,
  • "upperLeftY": -0.5
}

Get a raster from a feature property

Get a raster from a feature property. The feature property must be of type RASTER.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

featureExternalId
required
string <= 256 characters ^[A-Za-z][A-Za-z0-9_]{0,255}$
Example: ocean_measure_W87H62

External Id of the type provided by client. Must be unique among all feature external ids within a CDF project and feature type.

rasterPropertyName
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: bathymetry

Raster Id of the raster property provided by client. Must be unique among all feature property names within a feature type.

Request Body schema: application/json
One of
srid
integer (GeospatialReferenceId) [ 0 .. 1000000 ]

EPSG code, e.g. 4326. Only valid for geometry types. See https://en.wikipedia.org/wiki/Spatial_reference_system

scaleX
number <double>
scaleY
number <double>
format
required
string
Value: "XYZ"
object

Responses

Request samples

Content type
application/json
{
  • "srid": 4326,
  • "scaleX": 0,
  • "scaleY": 0,
  • "format": "GTiff",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete a raster from a feature property

Delete a raster from a feature property. If there is no raster already, the operation is a no-op.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

featureTypeExternalId
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: ocean_measures

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

featureExternalId
required
string <= 256 characters ^[A-Za-z][A-Za-z0-9_]{0,255}$
Example: ocean_measure_W87H62

External Id of the type provided by client. Must be unique among all feature external ids within a CDF project and feature type.

rasterPropertyName
required
string <= 32 characters ^[A-Za-z][A-Za-z0-9_]{0,31}$
Example: bathymetry

Raster Id of the raster property provided by client. Must be unique among all feature property names within a feature type.

Responses

Response samples

Content type
application/json
{ }

Create MVT mapping definitions

Create Mapbox Vector Tile mapping definitions

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (GeospatialMapboxVectorTileSpec) [ 0 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete MVT mapping definitions

Delete Mapbox Vector Tile mapping definitions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of MVT mappings to delete.

required
Array of objects (GeospatialItemExternalId) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Get MVT mapping definitions by external ids

Get Mapbox Vector Tile mapping definitions by external ids.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of MVT mappings to retrieve.

required
Array of objects (GeospatialItemExternalId) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List MVT mapping definitions

List Mapbox Vector Tile mapping definitions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get MVT

Get Mapbox Vector Tile.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

mvtMappingExternalId
required
string
Example: mvt_1

External Id of MVT mapping to be used for tile retrieval.

z
required
integer

Tile zoom level (corresponding zoom level must be mapped to feature type in MVT mapping).

x
required
integer

Tile x coordinate. Must be between 0 and 2^z (z=zoom level).

y
required
integer

Tile y coordinate. Must be between 0 and 2^z (z=zoom level).

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

3D Models

List 3D models

Retrieves a list of all models in a project. This operation supports pagination. You can filter out all models without a published revision.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

published
boolean

Filter based on whether or not it has published revisions.

Responses

Request samples 

const models3D = await client.models3D.list({ published: true });

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create 3D models

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The models to create.

required
Array of objects (CreateModel3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update 3D models

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of changes.

required
Array of objects (UpdateModel3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete 3D models

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of models to delete.

required
Array of objects (DataIdentifier) [ 1 .. 1000 ] items unique

List of ID objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve a 3D model

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

Responses

Request samples 

await client.models3D.retrieve(3744350296805509);

Response samples

Content type
application/json
{
  • "name": "My Model",
  • "id": 1000,
  • "createdTime": 0,
  • "dataSetId": 1,
  • "metadata": {
    }
}

3D Model Revisions

List 3D revisions

Retrieves a list of all revisions of a model. This operation supports pagination. You can also filter revisions if they are marked as published or not by using the query param published.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

published
boolean

Filter based on published status.

Responses

Request samples 

const revisions3D = await client.revisions3D.list(324566546546346);

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create 3D revisions

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

The revisions to create.

required
Array of objects (CreateRevision3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update 3D revisions

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

List of changes.

required
Array of objects (UpdateRevision3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete 3D revisions

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

List of revisions ids to delete.

required
Array of objects (DataIdentifier) [ 1 .. 1000 ] items unique

List of ID objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve a 3D revision

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Responses

Request samples 

const revisions3D = await client.revisions3D.retrieve(8252999965991682, 4190022127342195)

Response samples

Content type
application/json
{
  • "id": 1000,
  • "fileId": 1000,
  • "published": false,
  • "rotation": [
    ],
  • "camera": {
    },
  • "status": "Done",
  • "metadata": {
    },
  • "thumbnailThreedFileId": 1000,
  • "thumbnailURL": "https://api.cognitedata.com/api/v1/project/myproject/3d/files/1000",
  • "assetMappingCount": 0,
  • "createdTime": 0
}

List 3D revision logs

List log entries for the revision

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
severity
integer <int64>
Default: 5

Minimum severity to retrieve (3 = INFO, 5 = WARN, 7 = ERROR).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update 3D revision thumbnail

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The request body containing the file ID of the thumbnail image (from Files API).

fileId
required
integer <int64>

File ID of thumbnail file in Files API. Only JPEG and PNG files are supported.

Responses

Request samples

Content type
application/json
{
  • "fileId": 0
}

Response samples

Content type
application/json
{ }

List available outputs

Retrieve a list of available outputs for a processed 3D model. An output can be a format that can be consumed by a viewer (e.g. Reveal) or import in external tools. Each of the outputs will have an associated version which is used to identify the version of output format (not the revision of the processed output). Note that the structure of the outputs will vary and is not covered here.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
format
string

Format identifier, e.g. 'ept-pointcloud' (point cloud). Well known formats are: 'ept-pointcloud' (point cloud data) or 'reveal-directory' (output supported by Reveal). 'all-outputs' can be used to retrieve all outputs for a 3D revision. Note that some of the outputs are internal, where the format and availability might change without warning.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List 3D nodes

Retrieves a list of nodes from the hierarchy in the 3D model. You can also request a specific subtree with the 'nodeId' query parameter and limit the depth of the resulting subtree with the 'depth' query parameter. By default, nodes are returned in order of ascending treeIndex. We suggest trying to set the query parameter sortByNodeId to true to check whether it makes your use case faster. The partition parameter can only be used if sortByNodeId is set to true. This operation supports pagination.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

depth
integer <int32>

Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.

nodeId
integer <int64>

ID of a node that are the root of the subtree you request (default is the root node).

sortByNodeId
boolean
Default: false

Enable sorting by nodeId. When this parameter is true, nodes will be listed in order of ascending nodeId. Enabling this option will likely result in faster response for many requests.

properties
string <jsonObject(jsonObject(string))>

Example: {"category1":{"property1":"value1"}}

Filter for node properties. Only nodes that match all the given properties exactly will be listed. The filter must be a JSON object with the same format as the properties field.

Responses

Request samples 

const nodes3d = await client.revisions3D.list3DNodes(8252999965991682, 4190022127342195);

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Filter 3D nodes

List nodes in a project, filtered by node property values specified by supplied filters. This operation supports pagination and partitions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json
object (Node3DPropertyFilter)

Filters used in the search.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get 3D nodes by ID

Retrieves specific nodes given by a list of IDs.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The request body containing the IDs of the nodes to retrieve.

required
Array of objects (Node3DId) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List 3D ancestor nodes

Retrieves a list of ancestor nodes of a given node, including itself, in the hierarchy of the 3D model. This operation supports pagination.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

nodeId
required
integer <int64>

ID of the node to get the ancestors of.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses

Request samples 

const nodes3d = await client.revisions3D.list3DNodeAncestors(8252999965991682, 4190022127342195, 572413075141081);

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

3D Files

Retrieve a 3D file

Retrieve the contents of a 3D file.

This endpoint supported tag-based caching.

This endpoint is only compatible with 3D file IDs from the 3D API, and not compatible with file IDs from the Files API.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

threedFileId
required
integer <int64>

The ID of the 3D file to retrieve.

Responses

Request samples 

await client.files3D.retrieve(3744350296805509);

Response samples

Content type
application/json
{
  • "error": {
    }
}

3D Asset Mapping

List 3D asset mappings

List all asset mappings

Asset references obtained from a mapping - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

nodeId
integer <int64>
assetId
integer <int64>
intersectsBoundingBox
string

Example: {"min":[0.0, 0.0, 0.0], "max":[1.0, 1.0, 1.0]}

If given, only return asset mappings for assets whose bounding box intersects the given bounding box.

Must be a JSON object with min, max arrays of coordinates.

Responses

Request samples 

const mappings3D = await client.assetMappings3D.list(3244265346345, 32423454353545);

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create 3D asset mappings

Create asset mappings

Asset references when creating a mapping - through asset ids - are allowed to be invalid. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The asset mappings to create.

required
Array of objects (CreateAssetMapping3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete 3D asset mappings

Delete a list of asset mappings

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The IDs of the asset mappings to delete.

required
Array of objects (DeleteAssetMapping3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Filter 3D asset mappings

Lists 3D assets mappings that match the specified filter parameter. Only one type of filter can be specified for each request, either assetIds, nodeIds or treeIndexes.

Asset references obtained from a mapping - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The filter for asset mappings to get.

AssetMapping3DAssetFilter (object) or AssetMapping3DNodeFilter (object) or AssetMapping3DTreeIndexFilter (object)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Entity matching

The entity matching contextualization endpoints lets you match CDF resources. For example, you can match time series to assets. The model uses similarity between string-fields from the source and the target to find potential matches, for instance the source name and the target name. The exact algorithm may change over time.

List entity matching models

List all available entity matching models.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create entity matcher model

Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint. Train a model that predicts matches between entities (for example, time series names to asset names). This is also known as fuzzy joining. If there are no trueMatches (labeled data), you train a static (unsupervised) model, otherwise a machine learned (supervised) model is trained.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
sources
required
Array of objects (Sources) [ 0 .. 2000000 ] items

List of custom source object to match from, for example, time series. String key -> value. Only string values are considered in the matching. Both id and externalId fields are optional, only mandatory if the item is to be referenced in trueMatches.

targets
required
Array of objects (Targets) [ 1 .. 2000000 ] items

List of custom target object to match to, for example, assets. String key -> value. Only string values are considered in the matching. Both id and externalId fields are optional, only mandatory if the item is to be referenced in trueMatches.

Array of objects or objects or objects or objects (TrueMatches) [ 1 .. 2000000 ] items [ items ]

List of objects of pairs of sourceId or sourceExternalId and targetId or targetExternalId, that corresponds to entities in source and target respectively, that indicates a confirmed match used to train the model. If omitted, an unsupervised model is used.

externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

name
string (ModelName) <= 256 characters

User defined name.

description
string (ModelDescription) <= 500 characters

User defined description.

featureType
string
Default: "simple"
Enum: "simple" "insensitive" "bigram" "frequencyweightedbigram" "bigramextratokenizers" "bigramcombo"

Each feature type defines one combination of features that will be created and used in the entity matcher model. All features are based on matching tokens. Tokens are defined at the top of the Entity matching section. The options are:

  • Simple: Calculates the cosine-distance similarity score for each of the pairs of fields defined in matchFields. This is the fastest option.
  • Insensitive: Similar to Simple, but ignores lowercase/uppercase differences.
  • Bigram: Similar to simple, but adds similarity score based on matching bigrams of the tokens.
  • FrequencyWeightedBigram: Similar to bigram, but give higher weights to less commonly occurring tokens.
  • BigramExtraTokenizers: Similar to bigram, but able to learn that leading zeros, spaces, and uppercase/lowercase differences should be ignored in matching.
  • BigramCombo: Calculates all of the above options, relying on the model to determine the appropriate features to use. Hence, this option is only appropriate if there are labeled data/trueMatches. This is the slowest option.
Array of objects (MatchFields)
Default: [{"source":"name","target":"name"}]

List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.

classifier
string (Classifier)
Default: "randomforest"
Enum: "randomforest" "decisiontree" "logisticregression" "augmentedlogisticregression" "augmentedrandomforest"

The classifier used in the model. Only relevant if there are trueMatches/labeled data and a supervised model is fitted.

ignoreMissingFields
boolean (IgnoreMissingFields)
Default: false

If True, replaces missing fields in sources or targets entities, for fields set in set in matchFields, with empty strings. Else, returns an error if there are missing data.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "targets": [
    ],
  • "trueMatches": [
    ],
  • "externalId": "my.known.id",
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    ],
  • "classifier": "randomforest",
  • "ignoreMissingFields": true
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "externalId": "my.known.id",
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    ],
  • "ignoreMissingFields": true,
  • "classifier": "randomforest",
  • "originalId": 111
}

Retrieve an entity matching model by the ID of the model

Shows the status of the model. If the status is completed, shows the parameters used to train the model.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "externalId": "my.known.id",
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    ],
  • "ignoreMissingFields": true,
  • "classifier": "randomforest",
  • "originalId": 111
}

Retrieve entity matching models

Retrieve entity matching models by IDs or external IDs.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects or objects (OneOfId)

List of ids or externalIds of models.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter models

Use filtering options to find entity matcher models.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Limits the number of results to return.

required
object

Filter on models with strict matching.

Responses

Request samples

Content type
application/json
{
  • "limit": 100,
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update entity matching models

Update entity matching models by IDs or external IDs.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of ModelChangeById (object) or ModelChangeByExternalId (object) (ModelChange)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete entity matcher model

Deletes an entity matching model. Currently, this is a soft delete, and only removes the entry from listing.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects or objects (OneOfId)

List of ids or externalIds of models.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Predict matches

Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint. Predicts entity matches using a trained model.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
One of
id
required
integer <int64> [ 1 .. 9007199254740991 ]

The ID of the model that is used to predict matches.

sources
Array of objects [ 0 .. 2000000 ] items

List of source entities to predict matches for, for example, time series. If omitted, will use sources from create.

targets
Array of objects [ 1 .. 2000000 ] items

List of potential target entities to match to one or more of the source entities, for example, assets. If omitted, will use targets from create.

numMatches
integer [ 0 .. 100 ]

The maximum number of results to return for each source entity.

scoreThreshold
number [ 0 .. 1 ]

Only return matches with score above this threshold.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "sources": [
    ],
  • "targets": [
    ],
  • "numMatches": 3,
  • "scoreThreshold": 0.7
}

Response samples

Content type
application/json
{
  • "jobId": 123,
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0
}

Retrieve entity matcher predict results

Get the results from a predict job.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

Responses

Response samples

Content type
application/json
{
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "jobId": 123,
  • "items": [
    ]
}

Re-fit entity matcher model

Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint. Creates a new model by re-training an existing model on existing data but with additional true matches. The old model is not changed. The new model gets a new id and new external id if newExternalId is set, or no external id if newExternalId is not set. Use for efficient re-training of the model after a user creates additional confirmed matches.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
One of
id
required
integer <int64> [ 1 .. 9007199254740991 ]

The ID of the original model.

newExternalId
string <= 255 characters

ExternalId for the new refitted model provided by client. Must be unique within the project.

required
Array of objects or objects or objects or objects [ 1 .. 2000000 ] items [ items ]

List of additional confirmed matches used to train the model. The new model uses a combination of this and trueMatches from the orginal model. If there are identical match-from ids, the pair from the original model is dropped.

sources
Array of objects [ 0 .. 2000000 ] items

List of source entities, for example, time series. If omitted, will use data from fit.

targets
Array of objects [ 1 .. 2000000 ] items

List of target entities, for example, assets. If omitted, will use data from fit.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "newExternalId": "my.known.id",
  • "trueMatches": [
    ],
  • "sources": [
    ],
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "externalId": "my.known.id",
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    ],
  • "ignoreMissingFields": true,
  • "classifier": "randomforest",
  • "originalId": 111
}

Engineering diagrams

Detect annotations in engineering diagrams

Detect annotations in engineering diagrams. Note: All users in a CDF project with assets read-all and files read-all capabilities can access data sent to this endpoint. Supported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects or objects (OneOfFileId) [ 1 .. 50 ] items

Files to run entity detection on.

entities
required
Array of objects (DiagramDetectEntities) [ 1 .. 500000 ] items [ items <= 256 properties ]

A list of entities to look for. For example, all the assets under a root node. The searchField determines the strings that identify the entities.

searchField
string (DiagramSearchField)
Default: "name"

This field determines the string to search for and to identify object entities.

partialMatch
boolean (DiagramPartialMatch)
Default: false

Allow partial (fuzzy) matching of entities in the engineering diagrams. Creates a match only when it is possible to do so unambiguously.

minTokens
integer (DiagramMinTokens)
Default: 2

Each detected item must match the detected entity on at least this number of tokens. A token is a substring of consecutive letters or digits.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "entities": [
    ],
  • "searchField": "userDefinedField",
  • "partialMatch": false,
  • "minTokens": 2
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "jobId": 123,
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "searchField": "userDefinedField",
  • "partialMatch": false,
  • "minTokens": 2
}

Retrieve engineering diagram detect results

Get the results from an engineering diagram detect job.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

Responses

Response samples

Content type
application/json
{
  • "jobId": 123,
  • "status": "Queued",
  • "items": [
    ],
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "searchField": "userDefinedField",
  • "partialMatch": false,
  • "minTokens": 2
}

Convert a diagram to image format

Convert interactive engineering diagrams to image format, with highlighted annotations. Supported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff. Supported output image formats are PNG and SVG, only the svg embeds the input annotations.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects or objects (DiagramConvertRequestSchema) [ 1 .. 50 ] items

An array of files and annotations to create interactive diagrams.

grayscale
boolean (Grayscale)
Default: true

Return the SVG version in grayscale colors only (reduces the file size).

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "grayscale": true
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "jobId": 123,
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "grayscale": true
}

Get the results for converting an engineering diagram to an image

Get the results for converting an engineering diagram to SVG and PNG formats.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

Responses

Response samples

Content type
application/json
{}

Vision

The Vision contextualization endpoints enable extraction of information from imagery data based on their visual content. For example, you can detect external ID or name of assets, detect and read value of gauges or identify common industrial objects in images.

This service has support for batch processing which enables processing of multiple image files via an asynchronous prediction request. A new contextualization job is triggered by sending a POST request to the service. The response of the POST request contains a job ID, which can then be used to make subsequent calls to check the status and retrieve the results of the job once it is completed.

Extract features from images

Start an asynchronous prediction job for extracting features such as text, asset tags or industrial objects from images. The response of the POST request contains a job ID, which can be used to make subsequent (GET) calls to check the status and retrieve the results of the job (see Retrieve results from a feature extraction job).

It is possible to have up to 20 concurrent jobs per CDF project.

The files referenced by items in the request body must fulfill the following requirements:

  • Must have file extension: .jpeg, .jpg or .png
  • Must have image/png or image/jpeg as mimeType

New feature extractors may be added in the future.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

header Parameters
cdf-version
string
Example: alpha

cdf version header. Use this to specify the requested CDF release.

Request Body schema: application/json

A request for running an extract job.

required
Array of objects or objects (FileReference) [ 1 .. 100 ]

List of image files to be analyzed by the feature extractors.

required
Array of TextDetection (string) or AssetTagDetection (string) or PeopleDetection (string) or IndustrialObjectDetection (string) or PersonalProtectiveEquipmentDetection (string) (VisionExtractFeature) unique

The type of detections to perform. New feature extractors may appear.

object (FeatureParameters)

Feature-specific parameters. New feature extractor parameters may appear.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "features": [
    ],
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "jobId": 123,
  • "items": [
    ],
  • "features": [
    ],
  • "parameters": {
    }
}

Retrieve results from a feature extraction job on images

Retrieve results from a feature extraction job on images.

Note that since files are split up into batches and processed independently of each other, the items in successfully completed batches will be returned even if files in other batches are still being processed. The job status will be Running until all batches have been processed. If one of the items in a batch fails, the results from items in other completed batches will still be returned. The corresponding items and error message(s) of failed batches will be populated in failedItems. Additionally, the status of the job is set to Completed if at least one batch is successfully completed, otherwise the status is set to Failed.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

header Parameters
cdf-version
string
Example: alpha

cdf version header. Use this to specify the requested CDF release.

Responses

Request samples 

// get an existing job, wait for it to complete, and get the results
const { items } = await client.vision.getExtractJob(1, true);
items.forEach((item) => {
  const predictions = item.predictions;
  // do something with the predictions
})

Response samples

Content type
application/json
{
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "jobId": 123,
  • "items": [
    ],
  • "failedItems": [
    ],
  • "parameters": {
    }
}

Documents

A document is a file that has been indexed by the document search engine. Every time a file is uploaded, updated or deleted in the Files API, it will also be scheduled for processing by the document search engine. After some processing, it will be possible to search for the file in the document search API.

The document search engine is able to extract content from a variety of document types, and perform classification, contextualization and other operations on the file. This extracted and derived information is made available in the form of a Document object.

The document structure consists of a selection of derived fields, such as the title, author and language of the document, plus some of the original fields from the raw file. The fields from the raw file can be found in the sourceFile structure.

File type support

Documents can be created from the following types of files:

  • PDF files
  • Spreadsheets, documents, and presentations from the Microsoft, Libre Office and macOS office suites
  • Plain text files
  • Images

Search for documents

This endpoint lets you search for documents by using advanced filters and free text queries. Free text queries are matched against the documents' filenames and contents.

Free text search

Boolean operators

The + symbol signifies an AND operation, and the | symbol signifies an OR. Searching for lorem + ipsum will match documents containing both "lorem" AND "ipsum" in the filename or content. Similarly, searching for lorem | ipsum will match documents containing either "lorem" OR "ipsum" in the filename or content.

The default operator between the search keywords is AND. That means that searching for two terms without any operator, like so: lorem ipsum, will match documents containing both the words "lorem" and "ipsum" in the filename or content.

To exclude documents containing a specific word, you can use the operator -. For instance, the search lorem -ipsum will match documents that contain the word "lorem", but does NOT contain the word "ipsum".

Phrases

Enclose multiple words inside double quotes " to group these words together. Normally, the search query lorem ipsum will match not only "lorem ipsum" but also "lorem cognite ipsum", and in general there can be any number of words between the two words in the query. The search query "lorem ipsum", however, will match only exactly "lorem ipsum" and not "lorem cognite ipsum".

Escape

To search for the special characters (+, |, -, ". \), escape with a preceding backslash ().

Ordering

When you search for a term, we try to return the most relevant documents first, and less relevant documents further down the list. There are a few factors that determine the relevance of a document:

  • If the search terms are found multiple times within a document, the relevance of that document is higher.
  • For searches with multiple terms, documents that contain all of the terms are considered more relevant than documents that only contain some of the terms.
  • Matches of the terms in the filename field of the document, count for more than matches in the content of the document.

Examples

{
    "search": {
        "query": "cognite \"lorem ipsum\""
    }
}

This request will return documents matching the search query, where the query behaves as described above.

{
    "search": {
        "query": "cognite \"lorem ipsum\""
    },
    "filter": {
        "prefix": {
            "property": ["externalId"],
            "value": "1"
        }
    }
}

This example combines a query with a filter. This search request will return documents matching the search query, and where externalId starts with "1". The results will be ordered by how well they match the query string.

Filtering

Filtering is done by using a special JSON filtering language. It is quite flexible and consists of a number of different "leaf" filters which can be combined together arbitrarily using the boolean clauses and, or and not.

The available leaf filters are: equals, in, containsAny, containsAll, range, prefix, exists, geojsonIntersects, geojsonDisjoint and geojsonWithin.

Properties

Below is an overview of all the properties that can be filtered on, and which filters are applicable to each property.

Property Type Applicable filters
["id"] integer equals, in, range, exists
["externalId"] string equals, in, prefix, exists
["title"] string equals, in, prefix, exists
["author"] string equals, in, prefix, exists
["createdTime"] integer equals, in, range, exists
["modifiedTime"] integer equals, in, range, exists
["lastIndexedTime"] integer equals, in, range, exists
["mimeType"] string equals, in, prefix, exists
["extension"] string equals, in, prefix, exists
["pageCount"] integer equals, in, range, exists
["type"] string equals, in, prefix, exists
["geoLocation"] geometry object geojsonIntersects, geojsonDisjoint, geojsonWithin, exists
["language"] string equals, in, prefix, exists
["assetIds"] array of integers containsAny, containsAll, exists
["assetExternalIds"] array of strings containsAny, containsAll, exists
["labels"] array of Labels containsAny, containsAll, exists
["sourceFile", "name"] string equals, in, prefix, exists
["sourceFile", "mimeType"] string equals, in, prefix, exists
["sourceFile", "size"] integer equals, in, range, exists
["sourceFile", "source"] string equals, in, prefix, exists
["sourceFile", "directory"] string equals, in, prefix, exists
["sourceFile", "assetIds"] array of integers containsAny, containsAll, exists
["sourceFile", "assetExternalIds"] array of strings containsAny, containsAll, exists
["sourceFile", "datasetId"] integer equals, in, range, exists
["sourceFile", "securityCategories"] array of integers containsAny, containsAll, exists
["sourceFile", "geoLocation"] geometry object geojsonIntersects, geojsonDisjoint, geojsonWithin, exists
["sourceFile", "labels"] array of Labels containsAny, containsAll, exists
["sourceFile", "metadata", *] string equals, in, prefix, exists

All filtering is done in a case-sensitive manner against the resource data. Note that some properties holds normalized data. E.g. a document with source file name FILE.PDF will have the extension property be pdf. A filter for extension equals to PDF will not match this document, as it must be specified as pdf.

Example

{
    "filter": {
        "and": [
            {
                "or": [
                    {
                        "equals": {
                            "property": ["type"],
                            "value": "PDF"
                        }
                    },
                    {
                        "prefix": {
                            "property": ["externalId"],
                            "value": "hello"
                        }
                    }
                ]
            },
            {
                "range": {
                    "property": ["createdTime"],
                    "lte": 1519862400000
                }
            },
            {
                "not": {
                    "in": {
                        "property": ["sourceFile", "name"],
                        "values": ["My Document.doc", "My Other Document.docx"]
                    }
                }
            }
        ]
    }
}

Aggregations

Aggregations can help provide useful information about your search results and about your whole data set. They can help answer questions such as "How many documents are there in total?" or "How many PDF documents matches my current query?"

The Documents API only supports one type of aggregation at the moment; the count aggregation. The count aggregation can give you a count of how many documents exist for the different values of a given property. If no property is given, the count aggregation gives you the total count of documents. More aggregation types may be added in the future.

Highlights

When you enable highlights for your search query, the response contains an additional highlight field for each search hit that includes the highlighted fragments for your query matches. However, this is a costly operation and we therefore limit the results to 20 documents.

Properties

Below is an overview of all the properties that can be aggregated on, and which aggregate is applicable to each property.

Property Applicable aggregation
["mimeType"] count
["pageCount"] count
["type"] count
["extension"] count
["author"] count
["language"] count
["sourceFile", "source"] count
["sourceFile", "mimeType"] count
["sourceFile", "labels"] count

Example

{
    "aggregates": [
        {
            "name": "countPerType",
            "aggregate": "count",
            "groupBy": [
                {
                    "property": ["type"]
                }
            ]
        }
    ]
}

Sorting

Search results are by default ordered by relevance, meaning how well they match the given query string. However, it is possible to specify a different property to sort by. Sorting can be ascending or descending. The default sort order is ascending, in case none is specified.

Properties

Below is an overview of all the properties that can be sorted on.

Property
["id"]
["externalId"]
["mimeType"]
["extension"]
["pageCount"]
["author"]
["title"]
["language"]
["type"]
["createdTime"]
["modifiedTime"]
["lastIndexedTime"]
["sourceFile", "name"]
["sourceFile", "mimeType"]
["sourceFile", "size"]
["sourceFile", "source"]
["sourceFile", "datasetId"]

Example

{
    "sort": [
        {
            "property": ["createdTime"],
            "order": "asc",
        }
    ]
}
Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Fields to be set for the search request.

object
(bool filters (and (object) or or (object) or not (object))) or (leaf filters (equals (object) or in (object) or containsAny (object) or containsAll (object) or range (object) or prefix (object) or exists (object) or geojsonIntersects (object) or geojsonDisjoint (object) or geojsonWithin (object))) (DocumentFilter)

A JSON based filtering language. See detailed documentation above.

Array of objects (DocumentSearchCountAggregate) [ 1 .. 5 ] items
Array of objects (DocumentSortItem) = 1 items

List of properties to sort by. Currently only supports 1 property.

limit
integer <int32> [ 0 .. 1000 ]
Default: 100

Maximum number of items. When using highlights the maximum value is reduced to 20.

cursor
string

Cursor for paging through results

Responses

Request samples

Content type
application/json
{
  • "search": {
    },
  • "filter": {
    },
  • "aggregates": [
    ],
  • "sort": [
    ],
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "aggregates": [
    ],
  • "nextCursor": "string"
}

Aggregate documents

The aggregation API allows you to compute aggregated results on documents like getting the count of all documents in a project or checking what are all the different authors of documents in a project, along with the count of documents in each of those aggregations. By specifying an additional filter or search, you can also aggregate only among documents matching the specified filter or search.

The default behavior, when you do not specify the aggregate field in the request body, is to return the count of all matched documents.

Setting aggregate to uniqueValues will return top unique values (up to the requested limit) and the count of each in the property specified in properties. The list will have the highest count first. For example:

{
  "aggregate": "uniqueValues",
  "properties": [
    {
      "property": ["author"]
    }
  ]
}

will return the top unique authors in the documents in your project. If the number of unique authors is less than the requested limit you will be receiving all unique authors ordered by the most frequent first.

Similarly,

{
  "aggregate": "uniqueValues",
  "properties": [
    {
      "property": ["author"]
    }
  ],
  "filter": {
      "equals": {
          "property": ["type"],
          "value": "PDF"
      }
  }
}

will return top unique authors in PDF documents.

Setting aggregate to allUniqueValues will return all unique values and the count of each. The response contains a cursor that must be used to fetch all pages of data. The data is not ordered by the count. This allows to retrieve all unique values for more than 10000 items.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
One of
object
(bool filters (and (object) or or (object) or not (object))) or (leaf filters (equals (object) or in (object) or containsAny (object) or containsAll (object) or range (object) or prefix (object) or exists (object) or geojsonIntersects (object) or geojsonDisjoint (object) or geojsonWithin (object))) (DocumentFilter)

A JSON based filtering language. See detailed documentation above.

aggregate
string
Default: "count"
Value: "count"

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "aggregate": "uniqueValues",
  • "properties": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "items": [
    ]
}

List documents

Retrieves a list of the documents in a project. You can use filters to narrow down the list. Unlike the search endpoint, the pagination is not restricted to 1000 documents in total, meaning this endpoint can be used to iterate through all the documents in your project.

For more information on how the filtering works, see the documentation for the search endpoint.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Fields to be set for the list request.

(bool filters (and (object) or or (object) or not (object))) or (leaf filters (equals (object) or in (object) or containsAny (object) or containsAll (object) or range (object) or prefix (object) or exists (object) or geojsonIntersects (object) or geojsonDisjoint (object) or geojsonWithin (object))) (DocumentFilter)

A JSON based filtering language. See detailed documentation above.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Maximum number of items per page. Use the cursor to get more pages.

cursor
string

Cursor for paging through results

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Retrieve document content

Returns extracted textual information for the given document.

The documents pipeline extracts up to 1MiB of textual information from each processed document. The search and list endpoints truncate the textual content of each document, in order to reduce the size of the returned payload. If you want the whole text for a document, you can use this endpoint.

The accept request header MUST be set to text/plain. Other values will give an HTTP 406 error.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Preview

The document preview service is a utility API that can render most document types as an image or PDF. This can be very helpful if you want to display a preview of a file in a frontend, or for other tasks that require one of these formats.

For both rendered formats there is a concept of a page. The actual meaning of a page depends on the source document. E.g. an image will always have exactly one page, while a spreadsheet will typically have one page representing each individual sheet.

The document preview service can only generate preview for document sizes that do not exceed 150 MiB. Trying to preview a larger document will give an error.

File type support

Previews can be created for the following types of files:

  • PDF files
  • Spreadsheets, documents and presentations from the Microsoft and Libre Office office suites
  • Images
  • CAD files (In beta. Available only when the cdf-version: beta header is provided.)

Retrieve a image preview of a page from a document

This endpoint returns a rendered image preview for a specific page of the specified document.

The accept request header MUST be set to image/png. Other values will give an HTTP 406 error.

The rendered image will be downsampled to a maximum of 2400x2400 pixels. Only PNG format is supported and only the first 10 pages can be rendered.

Previews will be rendered if neccessary during the request. Be prepared for the request to take a few seconds to complete.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

documentId
required
integer

Internal ID for document to preview

pageNumber
required
integer [ 1 .. 10 ]

Page number to preview. Starting at 1 for first page

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Retrieve a PDF preview of a document

This endpoint returns a rendered PDF preview for a specified document.

The accept request header MUST be set to application/pdf. Other values will give an HTTP 406 error.

This endpoint is optimized for in-browser previews. We reserve the right to adjust the quality and other attributes of the output with this in mind. Please reach out to us if you have a different use case and requirements.

Only the 100 first pages will be included.

Previews will be rendered if neccessary during the request. Be prepared for the request to take a few seconds to complete.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

documentId
required
integer

Internal ID for document to preview

header Parameters
cdf-version
string
Example: alpha

cdf version header. Use this to specify the requested CDF release.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Raw

Manage data in the raw NoSQL database. Each project will have a variable number of raw databases, each of which will have a variable number of tables, each of which will have a variable number of key-value objects. Only queries on key are supported through this API.

List databases

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]
Default: 25

Limit on the number of databases to be returned.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples 

const databases = await client.raw.listDatabases();

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create databases

Create databases in a project. It is possible to post a maximum of 1000 databases per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of names of databases to be created.

Array of objects (RawDB)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete databases

It deletes a database, but fails if the database is not empty and recursive is set to false (default).

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of names of the databases to be deleted.

Array of objects (RawDB)
recursive
boolean
Default: false

When true, tables of this database are deleted with the database.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "recursive": false
}

Response samples

Content type
application/json
{ }

List tables in a database

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string

The name of a database to retrieve tables from.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]
Default: 25

Limit on the number of tables to be returned.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples 

const tables = await client.raw.listTables('My company');

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create tables in a database

Create tables in a database. It is possible to post a maximum of 1000 tables per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string

Name of the database to create tables in.

query Parameters
ensureParent
boolean
Default: false

Create database if it doesn't exist already

Request Body schema: application/json

List of tables to create.

Array of objects (RawDBTable)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete tables in a database

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string

Name of the database to delete tables in.

Request Body schema: application/json

List of tables to delete.

Array of objects (RawDBTable)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve cursors for parallel reads

Retrieve cursors based on the last updated time range. Normally this endpoint is used for reading in parallel.

Each cursor should be supplied as the 'cursor' query parameter on GET requests to Read Rows. Note that the 'minLastUpdatedTime' and the 'maxLastUpdatedTime' query parameter on Read Rows are ignored when a cursor is specified.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string

Name of the database.

tableName
required
string

Name of the table.

query Parameters
minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An exclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An inclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

numberOfCursors
integer <int32> [ 1 .. 10000 ]

The number of cursors to return, by default it's 10.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve rows from a table

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string

Name of the database.

tableName
required
string

Name of the table.

query Parameters
limit
integer <int32> [ 1 .. 10000 ]
Default: 25

Limit the number of results.

columns
string
Example: columns=column1,column2

Ordered list of column keys, separated by commas. Leave empty for all, use single comma to retrieve only row keys.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An exclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An inclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Responses

Request samples 

await client.raw.listRows('My company', 'Employees', { columns: ['last_name'] });

Response samples

Content type
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Insert rows into a table

Insert rows into a table. It is possible to post a maximum of 10000 rows per request. It will replace the columns of an existing row if the rowKey already exists.

The rowKey is limited to 1024 characters which also includes Unicode characters. The maximum size of columns are 5 MiB, however the maximum size of one column name and value is 2621440 characters each. If you want to store huge amount of data per row or column we recommend using the Files API to upload blobs, then reference it from the Raw row.

The columns object is a key value object, where the key corresponds to the column name while the value is the column value. It supports all the valid types of values in JSON, so number, string, array, and even nested JSON structure (see payload example to the right).

Note There is no rollback if an error occurs, which means partial data may be written. However, it's safe to retry the request, since this endpoint supports both update and insert (upsert).

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string [ 1 .. 32 ] characters

Name of the database.

tableName
required
string [ 1 .. 64 ] characters

Name of the table.

query Parameters
ensureParent
boolean
Default: false

Create database/table if it doesn't exist already

Request Body schema:

List of rows to create.

Array of objects (RawDBRowInsert)

Responses

Request samples

Content type
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve row by key

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string [ 1 .. 32 ] characters

Name of the database to retrieve the row from.

tableName
required
string [ 1 .. 64 ] characters

Name of the table to retrieve the row from.

rowKey
required
string

Row key of the row to retrieve.

Responses

Request samples 

await client.raw.retrieveRow('My company', 'Customers', 'customer1');

Response samples

Content type
application/json
{
  • "key": "string",
  • "columns": { },
  • "lastUpdatedTime": 0
}

Delete rows in a table

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string [ 1 .. 32 ] characters

Name of the database containing the rows.

tableName
required
string [ 1 .. 64 ] characters

Name of the table containing the rows.

Request Body schema: application/json

Keys to the rows to delete.

Array of objects (RawDBRowKey)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Extraction Pipelines

Extraction Pipeline objects represent the applications and software that are deployed to ingest operational data into CDF. An extraction pipeline can consist of a number of different software components between the source system and CDF. The extraction pipeline object represents the software component that actually sends the data to CDF. Two examples are Cognite extractors and third party ETL tools such as Microsoft Azure or Informatica PowerCenter

List extraction pipelines

Returns a list of all extraction pipelines for a given project

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples 

ep_list = client.extraction_pipelines.list(limit=5)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create extraction pipelines

Creates multiple new extraction pipelines. A maximum of 1000 extraction pipelines can be created per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (CreateExtPipe) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Delete extraction pipelines

Delete extraction pipelines for given list of ids and externalIds. When the extraction pipeline is deleted, all extraction pipeline runs related to the extraction pipeline are automatically deleted.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of ExtPipeInternalId (object) or ExtPipeExternalId (object) (ExtPipeId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Update extraction pipelines

Update information for a list of extraction pipelines. Fields that are not included in the request, are not changed.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of ExtPipeUpdateById (object) or ExtPipeUpdateByExternalId (object) (ExtPipeUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve an extraction pipeline by its ID.

Retrieve an extraction pipeline by its ID. If you want to retrieve extraction pipelines by externalIds, use Retrieve extraction pipelines instead.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples 

res = client.extraction_pipelines.retrieve(id=1)

res = client.extraction_pipelines.retrieve(external_id="1")

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "name": "string",
  • "description": "string",
  • "dataSetId": 9007199254740991,
  • "rawTables": [
    ],
  • "schedule": "string",
  • "contacts": [
    ],
  • "metadata": {
    },
  • "source": "string",
  • "documentation": "string",
  • "notificationConfig": {
    },
  • "createdBy": "string",
  • "id": 9007199254740991,
  • "lastSuccess": 0,
  • "lastFailure": 0,
  • "lastMessage": "string",
  • "lastSeen": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0
}

Retrieve extraction pipelines

Retrieves information about multiple extraction pipelines in the same project. All ids and externalIds must be unique.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of ExtPipeInternalId (object) or ExtPipeExternalId (object) (ExtPipeId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter extraction pipelines

Use advanced filtering options to find extraction pipelines.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (ExtPipesFilter)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Extraction Pipelines Runs

Extraction Pipelines Runs are CDF objects to store statuses related to an extraction pipeline. The supported statuses are: success, failure and seen. The statuses are related to two different types of operation of the extraction pipeline. Success and failure indicate the status for a particular EP run where the EP attempts to send data to CDF. If the data is successfully posted to CDF the status of the run is ‘success’; if the run has been unsuccessful and the data is not posted to CDF, the status of the run is ‘failure’. Message can be stored to explain run status. Seen is a heartbeat status that indicates that the extraction pipeline is alive. This message is sent periodically on a schedule and indicates that the extraction pipeline is working even though data may not have been sent to CDF by the extraction pipeline.

List extraction pipeline runs

List of all extraction pipeline runs for a given extraction pipeline. Sorted by createdTime value with descendant order.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
externalId
required
string
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create extraction pipeline runs

Create multiple extraction pipeline runs. Current version supports one extraction pipeline run per request. Extraction pipeline runs support three statuses: success, failure, seen. The content of the Error Message parameter is configurable and will contain any messages that have been configured within the extraction pipeline.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (ExtPipeRunRequest) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter extraction pipeline runs

Use advanced filtering options to find extraction pipeline runs. Sorted by createdTime value with descendant order.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
object (RunsFilter)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Extraction Pipelines Config

Extraction Pipelines Configs are configuration file revisions tied to an extraction pipeline. Users can create new configuration revisions, and extractors can fetch the latest, making it easy to deploy configuration files from source control, automated scripts, etc.

Get a single configuration revision

Retrieves a single configuration revision. By default, the latest revision is retrieved.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
externalId
required
string
revision
integer <int32> >= 0
Default: 0
activeAtTime
integer <int64> >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "revision": 2147483647,
  • "createdTime": 0,
  • "description": "string"
}

Create extraction configuration revision

Creates a configuration revision for the given extraction pipeline.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
externalId
required
string [ 1 .. 255 ] characters

External ID of the extraction pipeline this configuration revision belongs to.

config
string

Configuration content.

description
string or null

A description of this configuration revision.

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "revision": 2147483647,
  • "createdTime": 0,
  • "description": "string"
}

List configuration revisions

Lists configuration revisions for the given extraction pipeline.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
externalId
required
string
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Revert configuration revision

Reverts the latest configuration revision to an older revision. Equivalent to creating a new revision identical to the old revision.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
externalId
required
string [ 1 .. 255 ] characters

External ID of the extraction pipeline to revert configurations for.

revision
integer <int32> [ 0 .. 2147483647 ]

Revision number of this configuration.

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "revision": 2147483647
}

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "revision": 2147483647,
  • "createdTime": 0,
  • "description": "string"
}

Data sets

Data sets let you document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to a Cognite Data Fusion (CDF) project.

Data sets group and track data by its source. For example, a data set can contain all work orders originating from SAP. Typically, an organization will have one data set for each of its data ingestion pipelines in CDF.

A data set consists of metadata about the data set, and the data objects that belong to the data set. Data objects, for example events, files, and time series, are added to a data set through the dataSetId field of the data object. Each data object can belong to only one data set.

To learn more about data sets, see getting started guide

Create data sets

You can create a maximum of 10 data sets per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of the data sets to create.

required
Array of objects (DataSetSpec) [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter data sets

Use advanced filtering options to find data sets.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of IDs of the data sets to retrieve. You can retrieve a maximum of 1000 data sets per request. All IDs must be unique.

object (DataSetFilter)

Filter on data sets with strict matching.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Aggregate data sets

Aggregate data sets in the same project. Criteria can be applied to select a subset of data sets.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (DataSetFilter)

Filter on data sets with strict matching.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve data sets

Retrieve data sets by IDs or external IDs.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of the IDs of the data sets to retrieve. You can retrieve a maximum of 1000 data sets per request. All IDs must be unique.

required
Array of DataSetInternalId (object) or DataSetExternalId (object) (DataSetIdEither) [ 1 .. 1000 ] items unique
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update the attributes of data sets.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

All provided IDs and external IDs must be unique. Fields that are not included in the request, are not changed.

required
Array of DataSetChangeById (object) or DataSetChangeByExternalId (object) (DataSetUpdate)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Labels

Create label definitions.

Creates label definitions that can be used across different resource types. The label definitions are uniquely identified by their external id.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of label definitions to create

required
Array of objects (ExternalLabelDefinition) [ 1 .. 1000 ] items unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter labels

Use advanced filtering options to find label definitions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (Filter)

Filter on labels definitions with strict matching.

cursor
string
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Delete label definitions.

Delete all the label definitions specified by their external ids. The resource items that have the corresponding label attached remain unmodified. It is up to the client to clean up the resource items from their attached labels if necessary.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of external ids of label definitions to delete.

required
Array of objects (LabelDefinitionExternalId) [ 1 .. 1000 ] items unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Relationships

The relationships resource type represents connections between resource objects in CDF. Relationships allow you to organize assets in other structures in addition to the standard hierarchical asset structure. Each relationship is between a source and a target object and is defined by a relationship type and the external IDs and resource types of the source and target objects. Optionally, a relationship can be time-constrained with a start and end time. To define and manage the available relationship types, use the labels resource type. The externalId field uniquely identifies each relationship.

Create relationships

List of the relationships to create. You can create a maximum of 1000 relationships per request. Relationships should be unique, but CDF does not prevent you from creating duplicates where only the externalId differs.

Relationships are uniquely identified by their externalId. Non-unique relationships will not be created.

The order of relationships in the response equals the order in the request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Data required to create relationships. You can request a maximum of 1000 relationships per request.

required
Array of objects (relationship) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List relationships

Lists all relationships. The order of retrieved objects may change for two calls with the same parameters. The endpoint supports pagination. The initial call to this endpoint should not contain a cursor, but the cursor parameter should be used to retrieve further pages of results.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

partition
string
Example: partition=1/10

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Update relationships

Update relationships between resources according to the partial definitions of the relationships given in the payload of the request. This means that fields not mentioned in the payload will remain unchanged. Up to 1000 relationships can be updated in one operation. To delete a value from an optional value the setNull field should be set to true. The order of the updated relationships in the response equals the order in the request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Data required to update relationships.

required
Array of objects (relationshipUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete relationships

Delete the relationships between resources identified by the external IDs in the request. You can delete a maximum of 1000 relationships per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Data required to delete relationships. You can delete a maximum of 1000 relationships per request.

required
Array of objects (itemsArray) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean (ignoreUnknownIds)
Default: false

Ignore external IDs that are not found.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Retrieve relationships

Retrieve relationships by external IDs. You can retrieve a maximum of 1000 relationships per request. The order of the relationships in the response equals the order in the request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Data required to list relationships.

required
Array of objects (itemsArray) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean (ignoreUnknownIds)
Default: false

Ignore external IDs that are not found.

fetchResources
boolean (fetchResources)
Default: false

If true, will try to fetch the resources referred to in the relationship, based on the users access rights. Will silently fail to attatch the resources if the user lacks access to some of them.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false,
  • "fetchResources": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter relationships

Lists relationships matching the query filter in the request. You can retrieve a maximum of 1000 relationships per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

Data required to filter relationships. Combined filters are interpreted as an AND operation (not OR). Only relationships that match ALL the provided filters are returned.

object (advancedListFilter)

Filter on relationships with exact match. Multiple filter elements in one property, for example sourceExternalIds: [ "a", "b" ], returns all relationships where the sourceExternalId field is either aorb`. Filters in multiple properties return relationships that match all criteria. If the filter is not specified, it defaults to an empty filter.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
fetchResources
boolean (fetchResources)
Default: false

If true, will try to fetch the resources referred to in the relationship, based on the users access rights. Will silently fail to attatch the resources if the user lacks access to some of them.

partition
string (Partition)

Splits the data set into N partitions. You need to follow the cursors within each partition in order to receive all the data. Example: 1/10

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "fetchResources": false,
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Annotations

Annotations reflect contextual information in base CDF resource types, such as Files and Time series, that are not present on the object itself. The benefits of the annotations concept are threefold:

  • The annotations concept is a good fit for enriching the base resources themselves, so that the overall data quality is higher in a given project.
  • It is also a good fit for building reference datasets for data problems uniformly across customer projects. Product teams can then use those reference datasets to train machine learning models or validate the performance of their algorithms on actual customer data.
  • Given a uniform way of labelling similar concepts across projects, it becomes easy for apps to agree on a consistent visual representation of those concepts.

Create annotations

Creates the given annotations.

Identifiers

An annotation must reference an annotated resource.

The reference can be made by providing the internal ID of the annotated resource.

Status

The annotation must have the status field set to either "suggested", "rejected", or "approved"

Access control

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Annotation types and Data

The annotation type property must be set to one of the globally available annotation types. See the documentation of the annotationType and data attributes for details.

The annotation data must conform to the schema provided by the annotation type.

Creating Application and User

The creating application and its version must be provided. The creating user must be provided, but if the annotation is being created by a service, this can be set to null.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request for creating annotations

required
Array of objects (AnnotationsV2CreateSchema) [ 1 .. 1000 ]

A list of annotations to create

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Suggest annotations

Suggests the given annotations, i.e. creates them with status set to "suggested"

Identifiers

An annotation must reference an annotated resource.

The reference can be made by providing the internal ID of the annotated resource.

Access control

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Annotation types and Data

The annotation type property must be set to one of the globally available annotation types. See the documentation of the annotationType and data attributes for details.

The annotation data must conform to the schema provided by the annotation type.

Creating Application and User

The creating application and its version must be provided. The creating user must be provided, but if the annotation is being created by a service, this can be set to null.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request for suggesting annotations, i.e., creating them with the "suggested" status

required
Array of objects (AnnotationsV2SuggestSchema) [ 1 .. 1000 ]

A list of annotations to suggest

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get an annotation

Retrieves the referenced annotation.

The caller must have read-access on the annotated resource, otherwise the call will fail.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

annotationId
required
integer <int64> (AnnotationId) [ 1 .. 9007199254740991 ]
Example: 4096

The internal ID of the annotation

Responses

Response samples

Content type
application/json
{
  • "id": 4096,
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "annotatedResourceType": "file",
  • "annotatedResourceId": 1337,
  • "annotationType": "images.ObjectDetection",
  • "creatingApp": "cognite-vision",
  • "creatingAppVersion": "1.2.1",
  • "creatingUser": "john.doe@cognite.com",
  • "data": {
    },
  • "status": "approved"
}

Filter annotations

Lists the annotations the caller has access to, based on a filter.

The caller must have read-access on the annotated resources listed in the filter, otherwise the call will fail.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request specifying the annotation listing behavior

cursor
string or null [ 1 .. 255 ] characters

A cursor pointing to another page of results

limit
integer [ 1 .. 1000 ]
Default: 25
required
object (AnnotationsV2FilterSchema)

A filter to apply on annotations

Responses

Request samples

Content type
application/json
{
  • "cursor": "MzE1NjAwMDcxNzQ0ODI5",
  • "limit": 25,
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": null
}

Retrieve annotations

Retrieves the referenced annotations.

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request referencing existing annotations

required
Array of objects (AnnotationsV2ReferenceSchema) [ 1 .. 1000 ]

A list of existing annotation references

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete annotations

Deletes the referenced annotations completely.

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request referencing existing annotations

required
Array of objects (AnnotationsV2ReferenceSchema) [ 1 .. 1000 ]

A list of existing annotation references

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update annotations

Updates the referenced annotations.

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

A request for updating existing annotations

required
Array of objects (AnnotationsV2UpdateItemSchema) [ 1 .. 1000 ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Transformations

Transformations enable users to use Spark SQL queries to transform data from the CDF staging area, RAW, into the CDF data model.

List transformations

List transformations. Use nextCursor to paginate through the results.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

includePublic
boolean

Whether public transformations should be included in the results. The default is true.

withJobDetails
boolean

Whether transformations should contain information about jobs. The default is true.

Responses

Request samples 

transformations_list = client.transformations.list()

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create transformations

Create a maximum of 1000 transformations per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of objects (TransformationCreate) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve transformations

Retrieve a maximum of 1000 transformations by ids and externalIds per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

withJobDetails
required
boolean

Whether the transformations will be returned with running job and last created job details.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": true,
  • "withJobDetails": true
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter transformations

Filter transformations. Use nextCursor to paginate through the results.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
required
object (TransformationFilter)
limit
integer <int32>
cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 0,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Delete transformations

Delete a maximum of 1000 transformations by ids and externalIds per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{ }

Update transformations

Update the attributes of transformations, maximum 1000 per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of UpdateItemWithExternalId_TransformationUpdate (object) or UpdateItemWithId_TransformationUpdate (object) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Run a transformation

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
One of
externalId
required
string
object (NonceCredentials)

Responses

Request samples

Content type
application/json
Example
{
  • "externalId": "string",
  • "nonce": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "string",
  • "transformationId": 0,
  • "transformationExternalId": "string",
  • "sourceProject": "string",
  • "destinationProject": "string",
  • "destination": {
    },
  • "conflictMode": "abort",
  • "query": "string",
  • "createdTime": 0,
  • "startedTime": 0,
  • "finishedTime": 0,
  • "lastSeenTime": 0,
  • "error": "string",
  • "ignoreNullFields": true,
  • "status": "Completed"
}

Cancel a transformation

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
One of
externalId
required
string

The external ID provided by the client. Must be unique for the resource type.

Responses

Request samples

Content type
application/json
Example
{
  • "externalId": "string"
}

Response samples

Content type
application/json
{ }

Transformation Jobs

Transformation jobs let you execute transformations asynchronously.

List jobs

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

query Parameters
transformationId
integer <int32>

List only jobs for the specified transformation. The transformation is identified by ID.

transformationExternalId
string

List only jobs for the specified transformation. The transformation is identified by external ID.

limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

Responses

Request samples 

transformation_jobs_list = client.transformations.jobs.list()

transformation_jobs_list = client.transformations.jobs.list(transformation_id = 1)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Retrieve jobs by ids

Retrieve a maximum of 1000 jobs by ids per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of objects (TransformationCogniteInternalId)
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List job metrics by job id

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

id
required
integer <int32>

The job id.

Responses

Request samples 

res = client.transformations.jobs.list_metrics(id=1)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Transformation Schedules

Transformation schedules allow you to run transformations with a specific input at intervals defined by a cron expression. These transformation jobs will be asynchronous and show up in the transformation job list. Visit http://www.cronmaker.com to generate a cron expression with a UI.

List all schedules

List all transformation schedules. Use nextCursor to paginate through the results.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

includePublic
boolean

Whether public transformations should be included in the results. The default is true.

Responses

Request samples 

schedules_list = client.transformations.schedules.list()

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Schedule transformations

Schedule transformations with the specified configurations.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of the schedules to create. Must be up to a maximum of 1000 items.

Array of ScheduleParametersWithExternalId (object) or ScheduleParametersWithId (object)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve schedules

Retrieve transformation schedules by transformation IDs or external IDs.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of transformation IDs of schedules to retrieve. Must be up to a maximum of 1000 items and all of them must be unique.

Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Unschedule transformations

Unschedule transformations by IDs or externalIds.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of transformation IDs of schedules to delete. Must be up to a maximum of 1000 items and all of them must be unique.

Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{ }

Update schedules

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of schedule updates. Must be up to a maximum of 1000 items.

Array of UpdateItemWithExternalId_ScheduleUpdate (object) or UpdateItemWithId_ScheduleUpdate (object)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Transformation Notifications

Transformation notifications let users know when a job fails if subscribed.

List notification subscriptions

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

query Parameters
transformationId
integer <int32>

List only notifications for the specified transformation. The transformation is identified by ID.

transformationExternalId
string

List only notifications for the specified transformation. The transformation is identified by external ID.

destination
string

Filter by notification destination.

limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

Responses

Request samples 

notifications_list = client.transformations.notifications.list()

notifications_list = client.transformations.notifications.list(transformation_id = 1)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Subscribe for notifications

Subscribe for notifications on the transformation errors.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of the notifications for new subscriptions. Must be up to a maximum of 1000 items.

Array of NotificationCreateWithExternalId (object) or NotificationCreateWithId (object) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete notification subscriptions by notification ID

Deletes the specified notification subscriptions on the transformation. Requests to delete non-existing subscriptions do nothing, but do not throw an error.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of IDs to be deleted.

Array of objects (TransformationCogniteInternalId)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Query

Query lets the users preview the result of their queries.

Run query

Preview a SQL query.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

Request Body schema: application/json
query
required
string

SQL query to run for preview.

convertToString
required
boolean

Stringify values in the query results.

limit
integer <int32>

End-result limit of the query.

sourceLimit
integer <int32>

Limit for how many rows to download from the data sources.

inferSchemaLimit
integer <int32>

Limit for how many rows that are used for inferring schema. Default is 10,000.

timeout
integer <int32>

Number of seconds to wait before cancelling a query. The default, and maximum, is 240.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "convertToString": true,
  • "limit": 0,
  • "sourceLimit": 0,
  • "inferSchemaLimit": 0,
  • "timeout": 0
}

Response samples

Content type
application/json
{
  • "schema": {
    },
  • "results": {
    }
}

Schema

Schema provides the expected schema for CDF resources.

Get the schema of a sequence

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

query Parameters
externalId
required
string non-empty

External ID of the Sequence

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get the schema of resource type

Authorizations:
api-keyoidc-token
path Parameters
project
required
string

The project name.

schemaType
required
string

Name of the target schema type, please provide one of the following: assets, timeseries, asset_hierarchy, events, datapoints string_datapoints, sequences, files, labels, relationships, raw, data_sets

query Parameters
conflictMode
string

One of the following conflictMode types can be provided: abort, upsert, update, delete

Responses

Request samples 

from cognite.client.data_classes import TransformationDestination
client.lumns = client.transformations.schema.retrieve(destination = TransformationDestination.assets())

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Functions

Functions enables Python code to be hosted and executed in the cloud, on demand or by using a schedule. Execution, status and logs are available through the API. A function is uploaded to the Files API as a zip file with at least a Python file called handler.py (unless specified otherwise through the functionPath-argument) that must contain a function named handle with any of the following arguments: data, client, secrets, or 'function_call_info', which are passed into the function. The latest version of Cognite SDK's are available, and additional python packages and version specifications can be defined in a requirements.txt in the root of the zip.

List functions

List functions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create functions

You can only create one function per request.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (Function) = 1 items

Array of functions to create.

Responses

Request samples

Content type
application/json
Example
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Functions limits

Service limits for the associated project.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Request samples 

limits = client.functions.limits()

Response samples

Content type
application/json
{
  • "timeoutMinutes": 15,
  • "cpuCores": {
    },
  • "memoryGb": {
    },
  • "runtimes": [
    ],
  • "responseSizeMb": 1
}

Filter functions

Use advanced filtering options to find functions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (FunctionFilter)
limit
integer <int32> >= 1
Default: 100

Limits the number of results to be returned.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete functions

Delete functions. You can delete a maximum of 10 functions per request. Function source files stored in the Files API must be deleted separately.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of FunctionId (object) or FunctionExternalId (object) (FunctionIdEither) [ 1 .. 10 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Retrieve a function by its id

Retrieve a function by its id. If you want to retrieve functions by names, use Retrieve functions instead.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

functionId
required
integer

The function id.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "createdTime": 123455234,
  • "status": "Queued",
  • "name": "myfunction",
  • "externalId": "my.known.id",
  • "fileId": 1,
  • "owner": "user@cognite.com",
  • "description": "My fantastic function with advanced ML",
  • "metadata": {
    },
  • "apiKey": "***",
  • "secrets": {
    },
  • "functionPath": "myfunction/handler.py",
  • "envVars": {
    },
  • "cpu": 0.25,
  • "memory": 1,
  • "runtime": "py38",
  • "runtimeVersion": "Python 3.8.13",
  • "error": {
    }
}

Retrieve functions

Retrieve functions by ids.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of FunctionId (object) or FunctionExternalId (object) (FunctionIdEither) [ 1 .. 10 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Activate Functions

Activate Cognite Functions. This will create the necessary backend infrastructure for Cognite Functions.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Response samples

Content type
application/json
{
  • "status": "inactive"
}

Get activation status

Get activation status

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Responses

Response samples

Content type
application/json
{
  • "status": "inactive"
}

Function calls

Function calls let you execute functions asynchronously with a timeout of 15 minutes.

Call a function asynchronously

Perform a function call. To provide input data to the function, add the data in an object called data in the request body. It will be available as the data argument into the function. Info about the function call at runtime can be obtained through the function_call_info argument if added in the function handle. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to "Create functions" for this purpose.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

functionId
required
integer

The function id.

Request Body schema: application/json
data
object (data)

Input data to the function. This data is passed deserialized into the function through one of the arguments called data. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to "Create functions" for this purpose.'

nonce
string (nonce)

Nonce retrieved from sessions API when creating a session. This will be used to bind the session before executing the function. The corresponding access token will be passed to the function and used to instantiate the client of the handle() function. You can create a session via the Sessions API. When using the Python SDK, the session will be created behind the scenes when creating the schedule.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "nonce": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "Running",
  • "startTime": 0,
  • "endTime": 0,
  • "error": {
    },
  • "scheduleId": 1,
  • "functionId": 1,
  • "scheduledTime": 0
}

List function calls

List function calls.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

functionId
required
integer

The function id.

query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples 

logs = client.functions.calls.get_logs(call_id=2, function_id=1)

client.ll = client.functions.calls.retrieve(call_id=2, function_id=1)
logs = client.ll.get_logs()

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Retrieve calls

Retrieve function calls by call ids.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

functionId
required
integer

The function id.

Request Body schema: application/json

List of IDs of calls to retrieve. Must be up to a maximum of 10000 items and all of them must be unique.

required
Array of objects (FunctionCallId) [ 1 .. 10000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve a function call by its id

Retrieve function calls.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

callId
required
integer

The function call id.

functionId
required
integer

The function id.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "Running",
  • "startTime": 0,
  • "endTime": 0,
  • "error": {
    },
  • "scheduleId": 1,
  • "functionId": 1,
  • "scheduledTime": 0
}

Retrieve logs for function call

Get logs from a function call.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

callId
required
integer

The function call id.

functionId
required
integer

The function id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve response for function call

Retrieve response from a function call.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

callId
required
integer

The function call id.

functionId
required
integer

The function id.

Responses

Request samples 

response = client.functions.calls.get_response(call_id=2, function_id=1)

client.ll = client.functions.calls.retrieve(call_id=2, function_id=1)
response = client.ll.get_response()

Response samples

Content type
application/json
{
  • "response": {
    }
}

Filter function calls

Use advanced filtering options to find function calls.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

functionId
required
integer

The function id.

Request Body schema: application/json
object (FunctionCallFilter)
limit
integer <int32> >= 1
Default: 100

Limits the number of results to be returned.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Function schedules

Function schedules allow you to run functions with a specific input at intervals defined by a cron expression. These function calls will be asynchronous and show up in the function call list. Visit http://www.cronmaker.com to generate a cron expression with a UI.

List schedules

List function schedules in project.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create schedules

Create function schedules. Function schedules trigger asynchronous calls with specific input data, based on a cron expression that determines when these triggers should be fired. Use e.g. http://www.cronmaker.com to be guided on how to generate a cron expression. One of FunctionId or FunctionExternalId (deprecated) must be set (but not both). When creating a schedule with a session, i.e. with a nonce, FunctionId must be used. The nonce will be used to bind the session before function execution, and the session will be kept alive for the lifetime of the schedule. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to "Create functions" for this purpose.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (FunctionSchedule) = 1 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Filter function schedules

Use advanced filtering options to find function schedules. At most one of FunctionId or FunctionExternalId can be specified.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (FunctionScheduleFilter)
limit
integer <int32> >= 1
Default: 100

Limits the number of results to be returned.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Retrieve a function schedule by its id

Retrieve a function schedule by its id.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

scheduleId
required
integer

The function schedule id.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "My schedule",
  • "createdTime": 0,
  • "description": "This is a nice schedule",
  • "cronExpression": "* * * * *",
  • "when": "Every hour",
  • "functionId": 1,
  • "functionExternalId": "my.known.id",
  • "sessionId": "string"
}

Retrieve schedules

Retrieve function schedules by schedule ids.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

List of IDs of schedules to retrieve. Must be up to a maximum of 10000 items and all of them must be unique.

required
Array of objects [ 1 .. 10000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete schedules

Delete function schedules.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
required
Array of objects (FunctionScheduleId) [ 1 .. 10000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve function input data

Retrieve the input data to the associated function.

Authorizations:
api-keyoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

scheduleId
required
integer

The function schedule id.

Responses

Request samples 

client.functions.schedules.get_input_data(id = 123)

Response samples

Content type
application/json
{
  • "id": 1,
  • "data": {
    }
}