Documentation Powered by ReDoc

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.

Authentication

api-key

An admin can create API keys in the Cognite console.

Security Scheme Type API Key
Header parameter name: api-key

token

Human users log in via an OpenId/OAuth flow. Use the /login/redirect flow to obtain a bearer access token. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

oidc-token

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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
application/json
application/json
text/csv
{
  • "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-keytokenoidc-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
ensureParent
boolean
Default: false

Create database/table if it doesn't exist already

Request Body schema:
application/json
application/json
multipart/form-data

List of rows to create.

Array of objects (RawDBRowInsert)

Responses

Request samples

Content type
application/json
application/json
multipart/form-data
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{ }

Retrieve row by key

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

The project name.

dbName
required
string

Name of the database to retrieve the row from.

tableName
required
string

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-keytokenoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

dbName
required
string

Name of the database containing the rows.

tableName
required
string

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
{ }

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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": [
    ],
  • "id": 1
}

Filter assets

Use advanced filtering options to find assets.

Authorizations:
api-keytokenoidc-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

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-keytokenoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json
object (Filter)

Filter on assets with strict matching.

Responses

Request samples

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

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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. To delete all descendants, set recursive to true. The limit of the request does not include the number of descendants that are deleted.

Authorizations:
api-keytokenoidc-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. 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-keytokenoidc-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.

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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.

Authorizations:
api-keytokenoidc-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-keytokenoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema:
application/json
application/json
application/protobuf

The datapoints to insert.

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

Responses

Request samples

Content type
application/json
application/json
application/protobuf
{
  • "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.

Authorizations:
api-keytokenoidc-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. Maximum is 100000 non-aggregated data points and 10000 aggregated data points.

aggregates
Array of strings (Aggregate) [ 0 .. 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 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 is useful for interpolating data. It is not available for aggregates.

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
application/json
application/json
application/protobuf
{
  • "items": [
    ]
}

Retrieve latest data point

Retrieves the latest data point in a time series.

Authorizations:
api-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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.

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

This parameter is deprecated. Use assetSubtreeIds instead. Only include events 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 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: startTime, endTime, createdTime, lastUpdatedTime. 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-keytokenoidc-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-keytokenoidc-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

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.

sort
Array of strings

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: startTime, endTime, createdTime, lastUpdatedTime. Partitions are done independently of sorting, there is no guarantee on sort order between elements from different partitions.

cursor
string
partition
string

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,
  • "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-keytokenoidc-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

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.

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
aggregate
aggregate
default
{
  • "filter": {
    },
  • "aggregate": "uniqueValues",
  • "fields": [
    ]
}

Response samples

Content type
application/json
Example
CountAggregateResult
CountAggregateResult
ValuesAggregateResult
{
  • "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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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 upload link for one file.

The uploadUrl link which is returned in the response is a Google Cloud Storage (GCS) resumable upload URL. It should be used in a separate request to upload the file, 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 do not have the actual file uploaded within one week will be automatically deleted.

The 'Origin' header parameter is forwarded as a 'Origin' header to the GCS initiate upload session request. Also, the 'mimeType' query parameter is forwarded as a 'X-Upload-Content-Type' header.

Authorizations:
api-keytokenoidc-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 in a resumable upload request 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 32 bytes, value 512 bytes, up to 16 key-value pairs.

assetIds
Array of integers <int64> (CogniteInternalId) [ 1 .. 1000 ] items
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

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)

The geographic metadata of the file.

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-keytokenoidc-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
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-keytokenoidc-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-keytokenoidc-token
path Parameters
project
required
string
Example: publicdata

The project name.

Request Body schema: application/json

The project name

object
partition
string

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-keytokenoidc-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 supports limited pagination with the offset parameter, but does not support retrieving all files in a project.

Authorizations:
api-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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 200 columns indexed by row number. 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-keytokenoidc-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: 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-keytokenoidc-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-keytokenoidc-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

Cursor for paging trough results. Still keep the filter in subsequent requests.

Responses

Request samples

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

Response samples

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

Aggregate sequences

Count the number of sequences that match the given filter

Authorizations:
api-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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": [
    ]
}

Deletes sequences

Deletes the sequences with the specified IDs.

Authorizations:
api-keytokenoidc-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

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Insert rows

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

Authorizations:
api-keytokenoidc-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-keytokenoidc-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 .. 200 ] 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
Select by Id
Select by Id
Select by ExternalId
{
  • "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": [
    ]
}

Delete rows

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

Authorizations:
api-keytokenoidc-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
{ }

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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 eitheraorb`. 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.

Responses

Request samples

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

Response samples

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

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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,
  • "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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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), 'reveal-directory' (output supported by Reveal), 'nodes-json' (a JSON dump of all nodes in the file) and 'preview-glb' (a GLTF preview of the 3D model). In addition, 'all-outputs' can be provided to return all outputs. Note that many of the outputs are internal, where the format might change without any 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-keytokenoidc-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-keytokenoidc-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

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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 Array of objects or objects or objects or objects (TrueMatches) [ 1 .. 2000000 ] 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
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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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 Array of objects or objects or objects or objects [ 1 .. 2000000 ] 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
}

Template Groups

The Template Groups resource allows structuring of data in a domain specific language.

Create Template Groups

Create new Template Groups. The user creating a Template Group is automatically added as an owner of that Template Group, however more owners can optionally be added by setting the 'owners' field.

You can create a maximum of 10 Template Groups per request.

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

The project name.

Request Body schema: application/json

A list of Template Groups to create. You can create a maximum of 10 Template Groups per request.

Array of objects (DomainCreate)

Responses

Request samples

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

Response samples

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

Upsert Template Groups

Create or update Template Groups.

The user creating a Template Group is automatically added as an owner of that Template Group, however more owners can optionally be added by setting the 'owners' field.

You can create or update a maximum of 10 Template Groups per request.

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

The project name.

Request Body schema: application/json

A list of Template Groups to create or update. You can create or update a maximum of 10 Template Groups per request.

Array of objects (DomainCreate)

Responses

Request samples

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

Response samples

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

Retrieve Template Groups

Retrieve Template Groups.

Retrieve Template Groups by external IDs.

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

The project name.

Request Body schema: application/json

A list of external IDs.

Array of objects (ExternalIdItem)
ignoreUnknownIds
boolean

Ignore External IDs that are not found.

Responses

Request samples

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

Response samples

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

Filter Template Groups

Filter Template Groups

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

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

The project name.

Request Body schema: application/json

A filter to be applied.

object (DomainFilter)
limit
integer

Return up to this many results.

cursor
string

The cursor used to paginate.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 0,
  • "cursor": "string"
}

Response samples

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

Delete Template Groups

Delete Template Groups.

Delete Template Groups by external IDs.

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

The project name.

Request Body schema: application/json

A list of external IDs.

Array of objects (ExternalIdItem)
ignoreUnknownIds
boolean

Ignore External IDs that are not found.

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Upsert a Template Group version

Create or update a Template Group version.

A Template Group update supports specifying different conflict modes, which is used when an existing schema already exists.

  • Patch -> It diffs the new schema with the old schema and fails if there are breaking changes.
  • Update -> It sets the new schema as schema of a new version.
  • Force -> It ignores breaking changes and replaces the old schema with the new schema.

The default mode is "patch".

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

The project name.

externalId
required
string

The external ID of the template group.

Request Body schema: application/json

The new version to create or update.

schema
required
string

The GraphQL schema of this version.

conflictMode
string
Enum: "Patch" "Update" "Force"

The conflict mode to use.

version
integer

Responses

Request samples

Content type
application/json
{
  • "schema": "string",
  • "conflictMode": "Patch",
  • "version": 0
}

Response samples

Content type
application/json
{
  • "version": 0,
  • "schema": "string",
  • "createdTime": {
    },
  • "lastUpdatedTime": {
    }
}

Filter Template Group versions

Filter versions

Retrieves a list of versions sorted in descending order. This operation supports pagination by cursor.

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

The project name.

externalId
required
string

The external ID of the template group.

Request Body schema: application/json

A filter to be applied.

object (DomainVersionFilter)
limit
integer
cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 0,
  • "cursor": "string"
}

Response samples

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

Delete a Template Group version

Delete a Template Group version.

Note: Deleting a version that is in use might cause issues for clients depending on it.

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

The project name.

externalId
required
string

The external ID of the template group.

Request Body schema: application/json

A version to delete.

version
required
integer

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Create Template instances

Create new Template instances.

You can create a maximum of 1000 instances per request. Each template can have a maximum of 100000 instances for a given version.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of instances. You can create a maximum of 1000 instances per request.

Array of objects (TemplateInstanceCreate)

Responses

Request samples

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

Response samples

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

Upsert Template instances

Create or update Template instances. You can upsert a maximum of 1000 instances per request.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of instances. You can create or update a maximum of 1000 instances per request.

Array of objects (TemplateInstanceCreate)

Responses

Request samples

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

Response samples

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

Update Template instances

Create or update Template instances. You can upsert a maximum of 1000 instances per request.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of updates. You can update a maximum of 1000 instances per request.

Array of objects (TemplateInstanceUpdate)

Responses

Request samples

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

Response samples

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

Retrieve Template instances

Retrieve Template instances.

Retrieve Template instances by external IDs.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of external IDs.

Array of objects (ExternalIdItem)
ignoreUnknownIds
boolean

Ignore External IDs that are not found.

Responses

Request samples

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

Response samples

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

Filter Template Instances

Filter Template Instances

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

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A filter to be applied.

object (InstanceFilter)
limit
integer

Return up to this many results.

cursor
string

The cursor used to paginate.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 0,
  • "cursor": "string"
}

Response samples

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

Delete Template instances

Delete Template instances.

Delete Template instances by external IDs.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of external IDs.

Array of objects (ExternalIdItem)
ignoreUnknownIds
boolean

Ignore External IDs that are not found.

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Run a GraphQL Query

Run a GraphQL Query.

To learn more see https://graphql.org/learn/

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

The GraphQL query to run.

query
required
string
variables
any (Json)
operationName
string

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "variables": null,
  • "operationName": "string"
}

Response samples

Content type
application/json
{
  • "data": null,
  • "errors": [
    ]
}

Create Views

Create new Views.

You can create a maximum of 1000 Views per request.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of views. You can create a maximum of 1000 Views per request.

Array of objects (ViewCreate)

Responses

Request samples

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

Response samples

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

Upsert Views

Create or update Views.

You can create or update a maximum of 1000 Views per request.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of views. You can create or update a maximum of 1000 Views per request.

Array of objects (ViewCreate)

Responses

Request samples

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

Response samples

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

Filter Views

Filter Views.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

Filter to apply.

filter
object (Unit)
limit
integer
cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": { },
  • "limit": 0,
  • "cursor": "string"
}

Response samples

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

Resolve a View

Resolves a View.

It resolves the source specified in a View with the provided input and applies the mapping rules to the response.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json
externalId
required
string
object (Map_Json)
cursor
string
limit
integer

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "input": {
    },
  • "cursor": "string",
  • "limit": 0
}

Response samples

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

Delete Views

Delete Views.

Delete Views by externalIds. A maximum of 1000 views can be deleted per request.

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

The project name.

externalId
required
string

The external ID of the template group.

version
required
integer

The version of the template group.

Request Body schema: application/json

A list of external IDs.

Array of objects (ExternalIdItem)
ignoreUnknownIds
boolean

Ignore External IDs that are not found.

Responses

Request samples

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

Response samples

Content type
application/json
{ }

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-keytoken

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.

Authorizations:
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-keytokenoidc-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-keytokenoidc-token

Responses

Response samples

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

Retrieve a project

Retrieves information about a project given the project URL name.

Authorizations:
api-keytokenoidc-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": {
    }
}

Legacy update of a project

Updates the project configuration. Warning: This endpoint does not support partial updates, so all fields must be set when updating the project, otherwise the existing values will be lost. Ensure you set validDomains and applicationDomains correctly. If you set applicationDomains to be empty, any domains previously set will be removed, and you may lock yourself out of your project.

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

The project name.

Request Body schema: application/json

Object with updated project configuration.

name
string (ProjectName)

The user-friendly name of the project.

defaultGroupId
integer <int64> (DefaultGroupId)

The default group for users in the project. Users that do not belong to a specific group will automatically inherit all capabilities in this group.

Note: The group set as the default group can't be deleted.

required
AzureADInputProjectAuthentication (object) or OAuth2InputProjectAuthentication (object) (InputProjectAuthentication)

Configuration of user authentication for the project.

Responses

Request samples

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

Response samples

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

Update a project

Updates the project configuration.

Authorizations:
api-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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

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-keytoken
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-keytoken
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

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-keytokenoidc-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

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-keytoken
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-keytoken
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-keytoken
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

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-keytoken
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-keytoken
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-keytoken
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

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-keytokenoidc-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-keytokenoidc-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-keytokenoidc-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

Responses

Request samples

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

Response samples

Content type
application/json
{ }

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": [
    ]
}