Upgrade JavaScript SDK - Cognite Docs

Upgrade JavaScript SDK 2.x to 3.x

How to upgrade from SDK version 2.x to 3.x.

Renamed interfaces

Some TypeScript interfaces have been renamed to have consistency between different resource types. The most used ones are:

GetTimeSeriesMetadataDTO -> Timeseries
PostTimeSeriesMetadataDTO -> ExternalTimeseries
DatapointsGetAggregateDatapoint -> DatapointAggregates
FilesMetadata -> FileInfo

You can find a comprehensive list in the changelog.

Events aggregate endpoints moved to a sub-API

client.events.aggregate(...) -> client.events.aggregate.count()
client.events.uniqueValuesAggregate(...) -> client.events.aggregate.uniqueValues(...)

Timestamp-to-Date auto-conversion

The JavaScript SDK automatically converts response timestamp values to date objects. This caused a bug in the Raw API. The fix can introduce a breaking change if you use the Raw API, and possibly in other places.

Helper classes removed

AssetClass, TimeSeriesClass, TimeSeriesList, and AssetList contained some helper methods that have been removed. Most of these helpers can be re-implemented using other SDK calls. Some examples: Asset.delete()

public async delete(options: DeleteOptions = {}) {
  return this.client.assets.delete(
    [{ id: this.id }],
    options
  );
}

Asset.subtree()

public async subtree() {
  const { items } = await client.assets.list({
    filter: {
      assetSubtreeIds: [{ id: this.id }],
    }
  });
}

TimeSeriesList.getAllDatapoints(…)

public getAllDatapoints = async (options: DatapointsMultiQueryBase = {}) => {
  const tsIds = this.map(({ id }) => ({ id }));
  return this.client.datapoints.retrieve({
    items: tsIds,
    ...options,
  });
};

Removed client.assets.retrieveSubtree(…)

Copies the functionality of Asset.subtree() (read above).

Change filter passing to client.timeseries.list

The function previously took a TimeseriesFilter as input and now takes a TimeseriesFilterQuery, which corresponds to the API spec. All filter-related fields should now be in the filter object.

Example

// Old way
const timeseries = await client.timeseries.list({
  assetIds: [1, 2],
  unit: 'liter',
  limit: 100,
});

//New way
const timeseries = await client.timeseries.list({
  filter: { assetIds: [1, 2], unit: 'liter' },
  limit: 100,
});

Upgrade JavaScript SDK 1.x to 2.x

How to upgrade from SDK version 1.x to 2.x.

Constructor

In 2.x.x, you need to create a new SDK instance before you can use the SDK:

const client = new CogniteClient({ appId: 'YOUR APPLICATION NAME' });

Next, you need to authenticate your client by calling one of these methods on the client: With API key:

client.loginWithApiKey({ project, apiKey });

With OAuth:

client.loginWithOAuth({
  project: 'publicdata',
});

For more info about OAuth-authentication, see here.

Changes

1.x.x	2.x.x
AUTHENTICATION
`sdk.Login.authorize(...)`	See constructor-section
`sdk.Login.loginWithApiKey(...)`	See constructor-section
`sdk.Logout.logout()`	Removed
`sdk.Logout.retrieveLogoutUrl(...)`	Removed
ASSETS
`sdk.Assets.create([...])`	`client.assets.create([...])`
`sdk.Assets.retrieve(123)`	`client.assets.retrieve([{id: 123}])`
`sdk.Assets.retrieveMultiple([123, 456])`	`client.assets.retrieve([{id: 123}, {id: 456}])`
`sdk.Assets.update(id, changes)`	`client.assets.update([{id, update: changes}])`
`sdk.Assets.updateMultiple([{id, ...changes}])`	`client.assets.update([{id, update: changes}])`
`sdk.Assets.overwriteMultiple(...)`	Removed
`sdk.Assets.delete([id])`	`client.assets.delete([{id: 123}])`
`sdk.Assets.list({name: 'abc'})`	`client.assets.list({filter: {name: 'abc'}}).autoPagingToArray({limit: 1000})`
`sdk.Assets.listDescendants(id, params)`	Not implemented yet. Follow issue here
`sdk.Assets.search({name: 'abc'})`	`client.assets.search({search: {name: 'abc'})`
TIME SERIES
`sdk.TimeSeries.create([...])`	`client.timeseries.create([...])`
`sdk.TimeSeries.retrieve(123)`	`client.timeseries.retrieve([{id: 123}])`
`sdk.TimeSeries.retrieveMultiple([123, 456])`	`client.timeseries.retrieve([{id: 123}, {id: 456}])`
`sdk.TimeSeries.update(id, changes)`	`client.timeseries.update([{id, update: changes}])`
`sdk.TimeSeries.updateMultiple([{id, ...changes}])`	`client.timeseries.update([{id, update: changes}])`
`sdk.TimeSeries.list({limit: 20})`	`client.timeseries.list().autoPagingToArray({limit: 20})`
`sdk.TimeSeries.search({name: 'abc'})`	`client.timeseries.search({search: {name: 'abc'}})`
DATA POINTS
`sdk.Datapoints.insert(id, datapoints)`	`client.datapoints.insert([{id, datapoints}])`
`sdk.Datapoints.insertByName(...)`	Removed
`sdk.Datapoints.insertMultiple([{name, datapoints}])`	Not supported using name. Use IDs instead: `client.datapoints.insert([{id, datapoints}])`
`sdk.Datapoints.retrieve(id, params)`	`client.datapoints.retrieve({items: [{id}], ...params})`
`sdk.Datapoints.retrieveByName(...)`	Removed (use ID instead)
`sdk.Datapoints.retrieveMultiple(...)`	Not directly supported. Use `client.datapoints.retrieve`
`sdk.Datapoints.retrieveLatest(name, before)`	Use IDs: `client.datapoints.retrieveLatest([{id, before}])`
`client.datapoints.retrieveCSV(...)`	Removed
`sdk.Datapoints.delete(name, timestamp)`	Use IDs: `client.datapoints.delete([{id, inclusiveBegin: timestamp, exclusiveEnd: timestamp}])`
`sdk.Datapoints.deleteRange(name, inclusiveBegin, exclusiveEnd)`	Use IDs: `client.datapoints.delete([{id, inclusiveBegin, exclusiveEnd}])`
EVENTS
`sdk.Events.create([...])`	`client.events.create([...])`
`sdk.Events.retrieve(id)`	`client.events.retrieve([{id}])`
`sdk.Events.retrieveMultiple([123, 456])`	`client.events.retrieve([{id: 123}, {id: 456}])`
`sdk.Events.update([{id, ...changes}])`	`client.events.update([{id, update: changes}])`
`sdk.Events.delete([id])`	`client.events.delete([{id}])`
`sdk.Events.list({limit: 20})`	`client.events.list().autoPagingToArray({limit: 20})`
`sdk.Events.search({name: 'abc'})`	`client.events.search({search: {name: 'abc'}})`
FILES
`sdk.Files.upload(fileMetadata, params)`	`client.files.upload(fileMetadata, fileContent?, overwrite?, waitUntilAcknowledged?)`
`sdk.Files.download(id)`	`client.files.getDownloadUrls([{id}])`
`sdk.Files.retrieveMetadata(id)`	`client.files.retrieve([{id}])`
`sdk.Files.retrieveMultipleMetadata([123, 456])`	`client.files.retrieve([{id: 123}, {id: 456}])`
`sdk.Files.updateMetadata(id, changes)`	`client.files.update([{id, update: changes}])`
`sdk.Files.updateMultipleMetadata([id, ...changes])`	`client.files.update([{id, update: changes}])`
`sdk.Files.delete([id])`	`client.files.delete([{id}])`
`sdk.Files.list({limit: 20})`	`client.files.list().autoPagingToArray({limit: 20})`
`sdk.Files.search({name: 'abc'})`	`client.files.search({search: {name: 'abc'}})`
`sdk.Files.replaceMetadata(...)`	Removed
3D
`sdk.ThreeD.createAssetMappings(modelId, revisionId, mappings)`	`client.assetMappings3D.create(modelId, revisionId, mappings)`
`sdk.ThreeD.createModels([name])`	`client.models3D.create([{name}])`
`sdk.ThreeD.createRevisions(modelId, revisions)`	`client.revisions3D.create(modelId, revisions)`
`sdk.ThreeD.retrieveFile(fileId, responseType)`	`client.files3D.retrieve(fileId)`
`sdk.ThreeD.retrieveModel(modelId)`	`client.models3D.retrieve(modelId)`
`sdk.ThreeD.retrieveRevision(modelId, revisionId)`	`client.models3D.retrieve(modelId, revisionId)`
`sdk.ThreeD.updateModels({id, name})`	`client.models3D.update([{id, update: {name}])`
`sdk.ThreeD.updateRevisions(modelId, {id, ...changes})`	`client.revisions3D.update(modelId, [{id, update: changes])`
`sdk.ThreeD.updateRevisionThumbnail(...)`	`client.revisions3D.updateThumbnail(modelId, revisionId, fileId)`
`sdk.ThreeD.deleteModels([id])`	`client.models3D.delete([{id}])`
`sdk.ThreeD.deleteRevisions(modelId, [id])`	`client.revisions3D.delete(modelId, [{id}])`
`sdk.ThreeD.deleteAssetMappings(modelId, revisionId, mappings)`	`client.assetMappings3D.delete(modelId, revisionId, mappings)`
`sdk.ThreeD.listAssetMappings(modelId, revisionId, params)`	`client.assetMappings3D.list(modelId, revisionId, params).autoPagingToArray()`
`sdk.ThreeD.listModels(params)`	`client.models3D.list(params).autoPagingToArray()`
`sdk.ThreeD.listNodes(modelId, revisionId, params)`	`client.revisions3D.list3DNodes(modelId, revisionId, params).autoPagingToArray()`
`sdk.ThreeD.listNodeAncestors(modelId, revisionId, params)`	`client.revisions3D.list3DNodeAncestors(modelId, revisionId, nodeId, params).autoPagingToArray()`
`sdk.ThreeD.listRevisions(modelId, params)`	`client.revisions3D.list(modelId, params).autoPagingToArray()`
`sdk.ThreeD.listSectors(modelId, revisionId, params)`	`client.viewer3D.listRevealSectors3D(modelId, revisionId, params).autoPagingToArray()`

Last modified on April 23, 2026

Get started with JavaScript SDK

⌘I