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

Select the Download button to download our OpenAPI specification to get started.

To import your data into Postman, select Import, and the Import modal opens. You can import items by dragging or dropping files or folders. You can choose how to import your API and manage the import settings in View Import Settings.

In the Import Settings, set the Folder organization to Tags, select Enable optional parameters to turn off the settings, and select Always inherit authentication to turn on the settings. Select Import.

Set the Authorization to Oauth2.0. By default, the settings are for Open Industrial Data. Navigate to Cognite Hub to understand how to get the credentials for use in Postman.

For more information, see Getting Started with Postman.

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.

As general guidance, Parallel Retrieval is a technique that should be used when due to query complexity, retrieval of data in a single request is significantly slower than it would otherwise be for a simple request. Parallel retrieval does not act as a speed multiplier on optimally running queries. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs.

CDF supports 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, 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.

Processing of parallel retrieval requests is subject to concurrency quota availability. The request returns the 429 response upon exceeding concurrency limits. See the Request throttling chapter below.

To prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. Some CDF resources will automatically enforce a maximum of 10 partitions. For more specific and detailed information, please read the partition attribute documentation for the CDF resource you're using.

Cognite Data Fusion (CDF) returns the HTTP 429 (too many requests) response status code when project capacity exceeds the limit.

The throttling can happen:

• If a user or a project sends too many (more than allocated) concurrent requests.
• If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.

Cognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.

Cognite recommends using a reasonable number (up to 10) of Parallel retrieval partitions.

Following these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.

See more here.

This API uses calendar versioning, and version names follow the YYYYMMDD format. You can find the versions currently available by using the version selector at the top of this page.

To use a specific API version, you can pass the cdf-version: $version header along with your requests to the API.

The beta versions provide a preview of what the stable version will look like in the future. Beta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.

Beta versions are indicated by a -beta suffix after the version name. For example, the beta version header for the 2023-01-01 version is then cdf-version: 20230101-beta.

Alpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API. This functionality presents no guarantee of service, so its use is subject to caution.

Alpha versions are indicated by an -alpha suffix after the version name. For example, the alpha version header for the 2023-01-01 version is then cdf-version: 20230101-alpha.

This article documents all notable changes to the Cognite Data Fusion (CDF) API v1.

Agents API

Added

• Added support for interactive message types in the Agent API, enabling bidirectional communication between agents and clients. Agents can now request clients to execute actions, and clients can respond with action messages containing the results.

Cognite Functions

Removed

• Python 3.9 (py39) is no longer supported as a runtime argument for Cognite functions.

Agent APIs (beta)

• Gemini 2.0 Flash and Claude 3 Haiku have been retired as model options.

Data Modeling API

Added

• Added state field to constraints returned from the service, describing whether the constraint is validated or failed.
• Added state field to indexes returned from the service, describing whether the index is successfully built, or if building failed.
• Added fields maxListSize and maxTextSize to the constraintState field in properties returned from the service, describing whether the associated property-level constraints are valdiated or failed.

Agent APIs (beta)

Deprecated

• agentId in the /ai/agents/chat endpoint has been deprecated in favor of agentExternalId. agentId will be retired from 2025-11-29.

Removed

• Gemini 1.5 Pro and Gemini 1.5 Flash have been retired as model options.

Time Series API

Changed

• Increased the maximum length of string data points from 255 characters to 1023 bytes (UTF-8 encoded).

Data Modeling API

Added

• Added field constraintState to properties returned from the service, describing the state of any property-level constraints. Currently includes the field nullability which tracks the state of any non-null constraint.

Default runtime in Cognite functions

Changed

• Default Python runtime in Cognite functions has been updated from Python 3.11 (py311) to Python 3.12 (py312).

Data Modeling API

Added

• Added a debug parameter to the /models/instances/query, /models/instances/sync, and /models/instances/list endpoints.
• The feature returns notices providing insights into query execution, which can be used for performance analysis and optimization.

Data sets API

Fixed

• Add length constraints on name and description fields for the /update endpoint to disallow empty strings.

3D API

Added

• Added 3D API endpoints to create and delete point cloud volume contextualization connections to CogniteAsset instances. These endpoints are only available in DataModelOnly projects. Currently available in beta.
  • POST /3d/contextualization/pointcloud
  • POST /3d/contextualization/pointcloud/delete

Agent APIs (beta)

Added

• New OpenAI models: azure/o3, azure/o4-mini, azure/gpt-4.1, azure/gpt-4.1-nano, azure/gpt-4.1-mini, azure/gpt-5, azure/gpt-5-mini, azure/gpt-5-nano
• New Gemini models: gcp/gemini-2.5-pro, gcp/gemini-2.5-flash
• New AWS models: aws/claude-4-sonnet, aws/claude-4-opus, aws/claude-4.1-opus

Note: Availability of models may differ between the chosen cloud provider and region of the CDF cluster.

Improved

• Various improvements to the Agent APIs after feedback from the initial alpha release. The Agent APIs (/ai/agents) to programmatically build and interact with Atlas agents are now in beta state.

Simulator integration API

Changed

• Introduced limits for number of simulator nodes and edges in a simulator model revision flowsheet, as well as number of properties per node. (Alpha feature)
• Support multiple flowsheets in a simulator model revision data. (Alpha feature)

IAM (Identity and access management)

Added

• The following endpoints (all under https://auth.cognite.com) are added:
  • /api/v1/orgs/{org}/principals/{principal}/sessions: List login sessions for a user principal in an organization.
  • /api/v1/orgs/{org}/principals/{principal}/sessions/revoke: Revoke one or more login sessions for a user principal in an organization.

3D API

Added

• Added support in the create 3D asset mappings endpoint for creating asset mappings for 3D CAD nodeId and CogniteAssetassetInstanceId pairs. This creates connections between instances in data modelling and 3D CAD nodes. Only available in Hybrid and DMSFirst CDF projects.
• Added support in the list 3D asset mappings endpoint for listing assetInstanceId based mappings, enabled with the getDmsInstances=true parameter.

Data Modeling API

Added

• Added mode to table expressions in the /sync endpoint, to select between sync modes:
  • onePhase (default, current behavior): All instances are returned while following the cursor
  • twoPhase: Existing instances are returned first, then new instances are returned by following the cursor
  • noBackfill: Existing instances are not returned, only new instances are yielded by following the cursor.
• Added backfillSort to table expressions in the /sync endpoint, to optionally specify how to sort existing instances with syncMode: twoPhase.

Data Modeling API

Added

• Add timezone property to the /trigger endpoint.

IAM (Identity and access management)

Added

• Added attributes to group creation in the POST /api/v1/projects/:project/groups endpoint to set attributes for groups.

Data Modeling API

Added

• Add allowExpiredCursorsAndAcceptMissedDeletes flag to the /sync endpoint.

Agent APIs

Fixed

• Removed the duplicate /api/v1/projects/{projectName} prefix from all agents endpoints.

Documents AI API

Fixed

• Removed the duplicate /api/v1/projects/{projectName} prefix from all documents AI endpoints.

Simulator integration API

Changed

• Introduced request body size limits for the simulator integration API endpoints.
  • POST /simulators/routines/revisions to create simulator routines revisions: 50KB
  • POST /simulators/run to run a simulation: 50KB
  • In addition, the simulator connector won't be able to send more than 100KB of data in a single run. See the Simulator integration API documentation for more details.

Simulator integration API

Changed

• The API now accepts empty strings for simulation values (inputs and outputs). Previous restriction on "STRING" values to have a minimum length of 1 character has been removed.

3D API

Added

• The 3D API now supports filtering nodes within a boundingbox in dm-only projects.
  • The following endpoint is now available:
    • POST /3d/nodes/list to filter nodes within an area definition.

3D Api

Added

• The 3D Jobs API is extended to include the job result and job result rejections endpoints.
  • The following endpoints are now available:
    • POST /3d/job/results/list to list the results of a job
    • POST /3d/job/result/rejections to add or remove job result rejections
    • POST /3d/job/result/rejections/list to list job result rejections

3D Api

Added

• The 3D Jobs API is now available in DM-Only Projects
  • The following endpoints are now available:
    • POST /3d/jobs to create a 3d job
    • POST /3d/jobs/list to list jobs
    • POST /3d/jobs/delete to delete jobs

Entity Matching

Changed

• Enforcement of request limits.
  • POST /context/entitymatching/byids can retrieve max 1000 models per request.
  • POST /context/entitymatching/update can update max 1000 models per request.
  • POST /context/entitymatching/delete can delete max 1000 models per request.

Agent APIs

Added

• The Agent APIs is now available in Alpha.
  • The following endpoints are now available:
    • POST /ai/agents to create or update one or more agents
    • GET /ai/agents to list all agents
    • POST /ai/agents/ids to retrieve one or more agents by externalId
    • POST /ai/agents/delete to delete one or more agents by externalId
    • POST /ai/agents/chat to send messages new messages and receive an answer to a specific agent

2025-03-25

Documents AI

Added

• A new field for specifying the language that the answer should be in, added to Documents Summarize endpoint (/ai/tools/documents/summarize).

Documents API

Added

• Added ability to filter on the space and externalId properties of an instanceId object.

Time Series API

Added

• New aggregates maxDatapoint and minDatapoint, that gives back both the value and the timestamp of the maximum/minimum data point.

PostgreSQL Gateway API

Added

• The PostgreSQL Gateway API is now in General Availability (GA).
  • The following endpoints are now available:
    • POST /postgresgateway to create postgres users.
    • POST /postgresgateway/delete to delete postgres users.
    • POST /postgresgateway/list to filter postgres users.
    • GET /postgresgateway to list postgres users.
    • POST /postgresgateway/byids to retrieve postgres users by their username.
    • POST /postgresgateway/update to update postgres users.
    • POST /postgresgateway/tables/{username} to create postgres foreign tables.
    • POST /postgresgateway/tables/{username}/delete to delete postgres foreign tables.
    • GET /postgresgateway/tables/{username} to list postgres foreign tables.
    • POST /postgresgateway/tables/{username}/byids to retrieve postgres foreign tables by name.

Principals API

Added

• The Principals API is now generally available.

Deprecated

• The User profiles API is deprecated in favor of the Principals API, which offers a superset of the functionality. The User profiles API will be removed in a future release.

Hosted Extractors API

Added

• Added support for clientCredentials auth to kafka sources.

SAP Writeback API

Added

• SAP writeback API reaches General Availability (GA).
  • The following endpoints are now available:
    • GET /writeback/sap/instances to list SAP instance destinations
    • POST /writeback/sap/instances to create SAP instance destinations
    • POST /writeback/sap/instances/delete to delete SAP instance destinations
    • POST /writeback/sap/instances/byids to retrieve SAP instance destinations by externalId
    • GET /writeback/sap/endpoints to list SAP endpoint destinations
    • POST /writeback/sap/endpoints to create SAP endpoint destinations
    • POST /writeback/sap/endpoints/delete to delete SAP endpoint destinations
    • POST /writeback/sap/endpoints/byids to retrieve SAP instance destinations by externalId
    • POST /writeback/sap/endpoints/verify to verify connectivity between CDF and the SAP endpoint destination
    • GET /writeback/sap/mappings to list schema mappings
    • POST /writeback/sap/mappings to create schema mappings
    • POST /writeback/sap/mappings/delete to delete schema mappings
    • POST /writeback/sap/mappings/byids to retrieve schema mappings destinations by externalId
    • GET /writeback/sap/requests to list writeback requests
    • POST /writeback/sap/requests to create writeback requests. Maximum concurrent limit of 50 requests per CDF project.
    • POST /writeback/sap/requests/byids to retrieve writeback requests by externalId

Hosted Extractors API

Added

• REST and EventHub sources and jobs are now in GA.

Simulator integration API

Added

• Simulator integration API reaches General Availability (GA).
  • The following endpoints are now available:
    • POST /simulators/* to access the simulators API and list simulators enabled for the project
    • POST /simulators/integrations/* to list simulator connectors and their state
    • POST /simulators/models/* to create/list/remove simulator models and their revisions
    • POST /simulators/routines/* to create/list/remove simulator routines and their revisions
    • POST /simulators/runs/* to create/schedule simulation runs
    • POST /simulators/logs/* to access simulator logs

Documents AI APIs

Added

• Documents AI APIs (/ai/tools/documents/ask and /ai/tools/documents/summarize) reaches General Availability (GA).

User profiles

Added

• Organization principals: get calling principal's profile

Deprecated

• GET /api/v1/{projectName}/profiles/me is deprecated in favor of the new endpoint.

Organizations and Projects

Updated

• GET /api/v1/orgs/{org}/projects?includeAdminProperties=true now includes state and deletionTime

Hosted Extractors API

Added

• Stabilized the API for Sources, Mappings, Destinations and Jobs, for MQTT and Kafka extractors.
• Promote Rest and EventHub extractors to public beta.
• Support data models in hosted extractors.

AWS Cognito support

Added

• Support creating organization with AWS Cognito as IdP.
  • POST /api/v1/orgs/{orgId}/orgs can be called to create organization with AWS Cognito as IdP.

Organizations and Projects

Added

• Allow non-admin users to list all projects in an organization.
  • GET /api/v1/orgs/{orgId}/projects can be called by all users of an organization.
• Include apiUrl when listing projects in an organization.
  • GET /api/v1/orgs/{orgId}/projects will include apiUrl for each project.

Time Series API

Added

• Introduced support for time series managed by Data modeling in data point subscriptions.
  • GET subscriptions/members can contain members with instanceId.
  • POST subscriptions can be used to create subscriptions with an defined set of instance ids.
  • POST subscriptions/update can be used to add/remove/set the instance id time series members.

Contextualization / Vision

Added

• Support for Vision endpoints referencing files by data modeling instance IDs, as an alternative to ID and external ID.

Simulator integration API

Added

• The simulator integration API endpoints have now been promoted to public beta. The following is just a brief list of endpoints. Go to the Cognite API reference documentation (beta) to view all endpoints and their functionalities.
  • POST /simulators/* to access the simulators API and list simulators enabled for the project
  • POST /simulators/integrations/* to list simulator connectors and their state
  • POST /simulators/models/* to create/list/remove simulator models and their revisions
  • POST /simulators/routines/* to create/list/remove simulator routines and their revisions
  • POST /simulators/runs/* to create/schedule simulation runs
  • POST /simulators/logs/* to access simulator logs

Contextualization / Engineering diagrams

Added

• Support for detecting tags in diagrams referencing files by data modelling instance ids as an alternative to id and externalId.

Files API

Added

• Add support for ignoreUnknownIds to the files/delete endpoint.

SAP Writeback

Added

• SAP Writeback API (Beta)

Time Series API

Added

• Introduces support for Time Series managed by Data modeling.
  • /timeseries/* endpoints will return data modeling instance Id in time series objects where applicable.
  • POST /timeseries/update can be used to update properties of data modeling time series, but only fields that are not managed by data modeling.
  • POST /timeseries/byids can be used to retrieve time series by instance Id.
  • POST /timeseries/list and POST /timeseries/aggregate support advanced filters with instanceId.space and instanceId.externalId fields. (No changes to regular filters)
  • POST /timeseries/data/* can be used with instance Id to ingest/delete/query data points.
  • POST /timeseries/synthetic/query can lookup by instance Id.

Subscriptions API

Added

• Subscription filters support advanced filters with instanceId.space and instanceId.externalId fields.
• List subscription members will show time series instance Ids, if available.

Files API

Added

• Introduces support for Files managed by Data modeling, which means following endpoints will allow specifying instance Id
  • POST /files/uploadlink to get upload links for files
  • POST /files/multiuploadlink to get multipart upload link for files
  • POST /files/completemultipartupload to complete a multipart file upload
  • POST /files/downloadlink to get download links for files
  • GET /files/icon to get an image representation of a file
  • POST /files/byids to retrieve metadata information about multiple specific files
  • POST /files/update to updates the information for the files

Data Workflows

Added

• subworkflow task: add support for referencing other workflow versions to run as part of a workflow

Data Workflows

Added

• Introduces the trigger resource for Data Workflows, which adds support for scheduling the execution of workflows and the management thereof.
  • POST /workflows/triggers to create a UNIX cron trigger for a workflow
  • GET /workflows/triggers to list all triggers
  • POST /workflows/triggers/delete to delete a trigger
  • GET /workflows/triggers/{triggerExternalId}/history which keeps a ledger of when the trigger fired and if it successfully started a workflow or not.

Organizations and Projects

Added

• Selected endpoints are promoted from beta to v1 (all under https://auth.cognite.com; note that the routes are different from the beta routes, and that some request and response signatures have changed):
  • GET /api/v1/orgs/{orgId} to get organization info
  • POST /api/v1/orgs/{orgId}/orgs to create an organization
  • POST /api/v1/orgs/{orgId}/delete to delete an organization
  • GET /api/v1/orgs/{orgId}/orgs to list the child organizations of an organization
  • POST /api/v1/orgs/{orgId}/projects to create a project in an organization
  • GET /api/v1/orgs/{orgId}/projects to list the projects in an organization

Deprecated

• The six beta endpoints that have been published as new V1 endpoints (just above) are deprecated and will be removed in a future release.

Data Modeling

Added

• Support marking properties as immutable

Data Modeling

Added

• Support for creating properties of type direct_relation[], allowing direct relations to point to multiple nodes.
• /containers/inspect endpoint to retrieve information about which views map a container.
• /instances/inspect endpoint to retrieve information about which containers an instance has data in.

Organizations and Projects

Added

• Projects API (Beta): Allow for parametrization of the initial admin group when creating a project.

Time Series

Added

• Time zone aware aggregate queries. Align aggregates with a given time zone. Also works with half-hour offsets like Asia/Kolkata (UTC+5:30). Takes DST transitions into account.
• New month (mo) granularity.
• Also applies to synthetic time series.

Organizations and Projects

Added

• Organizations API (Beta): create, list, and delete CDF organizations
• Organizations API (Alpha): update CDF organizations
• Projects API (Beta): create and list projects in CDF organizations

User profiles

Added

• Organization user profiles (Beta): list users in CDF organizations

Projects

Removed

• Removed the previous Projects API from public documentation, as those endpoints are available to Cognite and resellers only.

Time series

Added

• Beta support for time zone aware aggregate queries. Align aggregates with a given time zone. Also works with half-hour offsets like Asia/Kolkata (UTC+5:30). Takes DST transitions into account.
• Beta support for new month (mo) granularity.
• Also applies to synthetic time series.

Postgres gateway

Added

• Endpoints for managing PostgreSQL gateway

Time series

Added

• Added support for status codes for data points.

Groups

Added

• Introduce the option to manage members of a group through CDF instead of through external groups in the identity provider. This is done through the new members field on the group object. Members can either be explicitly enumerated or one declare a group to include all users accounts. The latter is useful if one wants all existing users and new users who joins a project to automatically receive certain capabilities.

Engineering diagrams (beta)

Added

• Beta endpoint for retrieving ocr data for a file per page. Currently, only files that have been run through diagram/detect will give any results. This may be up for change in the future. The endpoint replaces a previous playground endpoint which is no longer documented.

Default runtime in Cognite functions

Changed

• Default Python runtime in Cognite functions has been updated from Python 3.8 (py38) to Python 3.11 (py311) in response to the upcoming end of community support for Python 3.8 in October 14, 2024.

Files

Updated

• Files API rate and concurrency limits have been documented. -- Service layer request rate and concurrency limits added -- CRUD endpoints request rate, concurrency and items rate limits added -- Analytic endpoints request rate, concurrency rate limits added

Assets

Updated

• Assets API rate and concurrency limits have been documented. -- Service layer request rate and concurrency limits added -- CRUD endpoints request rate, concurrency and items rate limits added -- Analytic endpoints request rate, concurrency and items rate limits added

Data Modeling

Added

Conversion between unit types for returned values during filter and query operations.

• Trigger conversion by setting the targetUnit by externalId or unitSystemName parameters for the data source in a query.
• When using filters with unit conversion, the unit for filter value is determined by the corresponding property in the source object. When querying data in centimeters by setting targetUnit on a property in the source, the filter value for that property will also be considered to be in centimeters.
• typing - type.unit on a property in a typing object is now always the same as the unit for the returned data.
• Added typing to following endpoints:
  • query
  • sync
  • aggregate
  • search

Time series

Added

• Data point subscriptions reaches General Availability (GA).
  • Use the new Data point subscriptions feature to configure a subscription to listen to changes in one or more time series (in ingestion order). The feature is intended to be used where data points consumers need to keep up to date with changes to one or more time series without the need to read the entire time series again.

Hosted Extractors

Changed

• host in kafka sources has been replaced with bootstrapBrokers, which is an array of objects with host and port.

Synthetic time series

Added

• Support for unit conversion by setting targetUnit or targetUnitSystem on time series or aggregates with a compatible unitExternalId field.

Sessions

Added

• Support for creating one-shot sessions by setting the oneshotTokenExchange flag. One-shot sessions are short-lived sessions that are not refreshed and do not require support for token exchange from the identity provider.

Data Modeling

Added

• Support for a bySpace flag on btree indexes and uniqueness constraints.

Data Modeling

Added

• Units catalog support for container properties: You can now specify a unit from CDF units catalog on float32 and float64 properties in containers.

Time series

Changed

• Data point subscriptions list data (beta) now supports long polling through the pollTimeoutSeconds parameter. The request will be kept active for the specified number of seconds, or until new data is available, whichever comes first.

Time series

Added

• Units catalog support to time series. This comes in addition to the existing free-text unit field.
  • Create timeseries with a unitExternalId.
  • Update timeseries to add/remove unitExternalId.
• Filter and aggregate time series by unitExternalId or unitQuantity (eg. "volume" or "temperature"). Both using regular filters and advanced filters.
  • Filter time series.
  • Aggregate time series.
  • Search time series.
• Added unit conversion support to retrieve data points/aggregates and retrieve latest. Specify a targetUnit or targetUnitSystem to convert the data points or aggregates to a different unit, or to the default unit of a given unit system.

Hosted extractors

Changed

• Hosted extractors API (Beta)
  • Updates hosted extractor schema with tls certificate details hence users can now provide CA and authentication certificates for connection to MQTT brokers.
  • Now includes schema requirements for connection to Kafka brokers i.e. connection to and extraction from Kafka brokers to Cognie Data fusion is not possible.

Units Catalog

Added

• Added the Units Catalog API. The Units Catalog is a collection of units of measurement and their conversion factors. The Units Catalog is used within Cognite Data Fusion to easily convert between different units and unit systems when retrieving Time Series and Data Models.

Documents

Added

• Added support for sorting in the /documents/list endpoint. It works exactly the same as the sorting in /documents/search except that you can not sort on search relevance.

Engineering diagrams

Changed

• Optional token mechanism for accessing detected results of engineering diagrams without read all access to assets. See diagram/detect for details.

Files

Added

• Added multipart upload endpoints for the files API. This enables upload of files larger than 5 GiB, in a uniform way for all CDF cloud environments. Optionally use parallel part upload, for greater upload speed. See the documentation for the new endpoints at:
  • Upload multipart file and
  • Complete multipart upload endpoints.

Events

Added

• New and old but previously undocumented API rate and concurrency limits have been documented. Overrides have been specified for existing customers, so that the new limits would not affect them.
  • Service layer request rate and concurrency limits added.
  • CRUD endpoints request rate and concurrency and items rate limits added

Entity matching

Added

• Entity matching pipelines are now in v1. We resuscitated the old playground API and made some changes. We will keep the new v1 API in beta for the foreseeable future.

Vision (Contextualization)

Added

• New computer vision models (beta) are available in Vision extract service, including digital, dial and level gauge readers, valve state detection (open/closed) and model to segment objects in images.

Hosted extractors

Added

• Hosted extractors API (Beta)
  • Use the new Hosted extractors feature to create simple streaming extractors running inside CDF, streaming data from sources available on the internet directly into CDF. Currently supports Azure Event Hub and MQTT. Support is planned for Kafka and REST APIs.

3D

Changed

• If the 3d model processing is ongoing or has failed, the 3d api nodes endpoints will now return error code 400 with the response body "Revision processing is not yet complete" or "Revision processing failed" respectively. The previous behavior was to return an empty or partial items list in these cases. Before calling any 3d api nodes endpoints, clients should check that the model revision has "status":"Done".

Transformations

Changed

• Fixed wrong description for fields in "transformations/update" and "/transformations/schedules/update"

Functions

Changed

• Remove Functions runtime "py37".

2023-08-22

Time series

Added

• Data point subscriptions (Beta)
  • Use the new Data point subscriptions feature to configure a subscription to listen to changes in one or more time series (in ingestion order). The feature is intended to be used where data points consumers need to keep up to date with changes to one or more time series without the need to read the entire time series again. (Beta)

Time series

Added

• Advanced query language support reaches General Availability (GA).
  • Advanced search, filtering, and sorting capabilities in the Filter time series endpoint.
  • Advanced aggregation capabilities in the Aggregate time series endpoint.

Sequences

Added

• Advanced query language support reaches General Availability (GA).
  • Advanced search, filtering, and sorting capabilities in the Filter sequences endpoint.
  • Advanced aggregation capabilities in the Aggregate sequences endpoint.

Assets

Added

• Advanced query language support reaches General Availability (GA).
  • Advanced search, filtering, and sorting capabilities in the Filter assets endpoint.
  • Advanced aggregation capabilities in the Aggregate assets endpoint.

Events

Added

• Advanced query language support reaches General Availability (GA).
  • Advanced search, filtering, and sorting capabilities in the Filter events endpoint.
  • Advanced aggregation capabilities in the Aggregate events endpoint.

Documents

Added

• Advanced query language support reaches General Availability (GA).
  • Advanced aggregation capabilities in the Aggregate documents endpoint.

IAM (Identity and access management)

Changed

• Identity providers (IdP) are required to be compatible with the OpenID Connect Discovery 1.0 standard, and compliance will now be enforced by the Projects API.

  • The oidcConfiguration.jwksUrl and oidcConfiguration.tokenUrl can be entirely omitted when updating the OIDC configuration for a project.
  • The oidcConfiguration.jwksUrl and oidcConfiguration.tokenUrl are preserved for backwards compatibility of the API. However, if these are specified as part of the request body, the value must match excatly the values that are specified in the OpenID provider configuration document for the configured issuer (can be found at https://{issuer-url}/.well-known/openid-configuration). If the values does not match, the API will return an error message.

• The oidcConfiguration.skewMs has been deprecated but remains part of the API for backwards compatibility. It can be omitted from the request. If included, it must always be set to 0.

• The oidcConfiguration.isGroupCallbackEnabled has been deprecated but remains part of the API for backwards compatibility. It can be omitted from the request.

  • For projects configured to use Azure Active Directory as the identity provider, if this value is specified in the request, it must always be set to true.

Data Modeling

Added

• Added support for an autoCreateDirectRelations option on the endpoint for ingesting instances. This option lets the user specify whether to create missing target nodes of direct relations.

Removed

• Removed support for the deprecated per-item sources field on the /instances/byids endpoint.

Time series

Added

• Added advanced query language support (Beta).
  • Advanced search, filtering, and sorting capabilities in the Filter time series endpoint.
  • Advanced aggregation capabilities in the Aggregate time series endpoint.

Sequences

Added

• Added advanced query language support (Beta).
  • Advanced search, filtering, and sorting capabilities in the Filter sequences endpoint.
  • Advanced aggregation capabilities in the Aggregate sequences endpoint.

Transformations

Added

• Adding support for data model centric and view centric schema.

Transformations

Removed

• Removing support for authentication via API keys when creating or updating transformations.

Annotations

Added

• Added image.InstanceLink and diagrams.InstanceLink annotation types to allow you to link from objects discovered in images and engineering diagrams to data model instances.

All resources

Added

• Added information about Requests throttling.

Changed

• Updated the Parallel retrieval documentation.
• Aligned endpoint naming within Assets, Data sets, Events, and Files.

Assets

Added

• Added advanced query language support (Beta).
  • Advanced search, filtering, and sorting capabilities in the Filter assets endpoint.
  • Advanced aggregation capabilities in the Aggregate assets endpoint.

Events

Added

• Added advanced query language support (Beta).
  • Advanced search, filtering, and sorting capabilities in the Filter events endpoint.
  • Advanced aggregation capabilities in the Aggregate events endpoint.

Documents

Added

• Added advanced query language support (Beta).
  • Advanced aggregation capabilities in the Aggregate documents endpoint.

Sessions

Fixed

• Fixed the API documentation for the request body of the POST /projects/{project}/sessions/byids endpoint. The documentation incorrectly stated the request body schema as specifying the list of session IDs to retrieve, in the form {"items": [42]} - it should in fact be {"items": [{"id": 42}]}. The documentation has been updated to reflect this.

• Fixed the API documentation for the response body of the POST /projects/{project}/sessions/byids endpoint. The documentation incorrectly stated nextCursor and previousCursor fields as being returned from the response, which was not the case, and these fields have now been removed from the API documentation.

Transformations

Change

• Transformations support new target types for view-centric data model instances.

Added

• Added target types nodes and edges.

Documents

Change

• Renamed "approximateCardinality" aggregate to "cardinalityValues" to unify the search spec in Cognite.
• "uniqueProperties" aggregate no longer supports pagination. It returns unique properties (up to 10000) in the specified path. The results are sorted by frequency.

Added

• Added "allUniqueProperties" aggregate that returns all unique properties. The response contains a cursor that can be used to fetch all pages of data.

Seismic

Added

• Batch downloading of seismics as a ZIP archive is now an experimental v1 endpoint. A user requires the experimental ACL to use this endpoint, and any other ACLs and scopes to read the downloadable seismics.

Fixed

• The documentation for downloading seismics as SEG-Y files is part of v1. The API documentation didn't reflect that the endpoint had been promoted to version 1.

Documents

Added

• Added highlight field in the search endpoint to indicate whether matches in search results should be highlighted.

3D

Added

• Added support for using names filter in list nodes endpoint.

Authentication

Removed

We've removed authentication via CDF service accounts and API keys, and user sign-in via /login.

3D

Added

• Added support for storing translation and scale for model revision.

Documents

Added

• Added support for approximateCardinality aggregate.

Documents

Added

• Added the search leaf filter, to allow filtering by searching through specified properties.

Documents

Added

• Added the uniqueProperties aggregation, which can be used to find all the metadata keys in use.

Documents

Added

• Added inAssetSubtree filter to filter documents that have a related asset in a subtree rooted at any of the specified IDs.

Documents

Added

• Added advanced filters for metadata (prefix, in, equals)

3D

Added

• Added get3DNodesById endpoint to be able to fetch 3D nodes mapped to an asset.

Time series

Changed

• Timestamps of data points may now be as large as 4102444799999 (23:59:59.999, December 31, 2099). The previous limit was the year 2050.

Events

Added

• Added nulls field to the sort property specification

Time series

Added

• Added nextCursor field to Retrieve data points, to support cursor pagination

Geospatial

Added

• Added the POST /projects/{project}/geospatial/compute endpoint.

Transformations

Added

• Added capability to run a transformation with Nonce credentials provided through the Run endpoint.

IAM (Identity and access management)

Added

• Added the POST /projects/{project}/sessions/byids endpoint.

Vision (Contextualization)

Added

• Move Vision extract service from playground to V1.

Time series

Changed

• Updated datapoints timestamp range from 1971 - 2050 to 1900 - 2050. Affected endpoints:
  • Insert data points
  • Retrieve data points
  • Delete data points
  • Retrieve latest data point
  • Synthetic query

Transformations

Added

• Added authentication using nonce for transformation's exisiting endpoints.

Annotations (Data organization)

Added

• Moved the annotation service from playground to v1.

Events

Removed

• End-of-life for filter.rootAssetIds filtering attribute.

IAM (Identity and access management)

Added

• Added the POST /projects/{project}/sessions/revoke endpoint.

Documents

Added

• Added the POST /documents/aggregate endpoint. The endpoint allows you to count documents optionally grouped by a property and also to retrieve all unique values of a property.

Documents

Added

• Added the POST /documents/list endpoint. The endpoint allows you to iterate through all the documents in a project.
• Added the POST /documents/{documentId}/content endpoint. The endpoint lets you download the entire extracted plain text of a document.

Documents

Added

• Added the GET /documents/{documentId}/preview/image/pages/{pageNumber} endpoint.
• Added the GET /documents/{documentId}/preview/pdf endpoint.
• Added the GET /documents/{documentId}/preview/pdf/temporarylink endpoint.

Sequences

Changed

• Changed sequences column limits. Old limit of maximum total 200 columns limits is updated to maximum 400 total columns, maximum 400 numeric columns and maximum 200 string columns.

Sequences

Added

• Added the POST /sequences/data/latest endpoint.

Time series

Changed

• Marked isStep parameter to be editable (i.e. removed description stating it is not updatable) in POST /timeseries/create.

Added

• Added isStep parameter to the TimeSeriesPatch object used in POST /timeseries/update

Documents

Added

• The POST /documents/search endpoint now supports pagination.

Documents

Added

• Added the POST /documents/search endpoint.

Time series

Added

• Added optional ignoreUnknownIds parameter to POST /sequences/delete. Setting this to true will prevent the operation from failing if one or more of the given sequences do not exist; instead, those given sequences that do exist will be deleted.

Transformations

Added

• New Transformations APIs to v1 to create,retrieve,list and delete transformations
• New Transformation Jobs APIs to v1 to retrieve and list transformation jobs or job metrics
• New Transformation Schedule APIs to v1 to manage schedules of transformations
• New Transformation Notifications APIs to v1 to manage notifications from transformation job

Contextualization

Added

• Added diagram detect endpoint to v1 to detect annotations in engineering diagrams
• Added diagram detect results endpoint to v1 to get the results from an engineering diagram detect job
• Added diagram convert endpoint to v1 to create interactive engineering diagrams in SVG format with highlighted annotations
• Added diagram convert results endpoint to v1 to get the results for a job converting engineering diagrams to SVGs

3D

Added

• Added dataSetId support to 3D models enabling data access scoping of 3D data

Raw

Changed

• To align with Microsoft Azure clusters, table and database names are now sensitive to trailing spaces also in Google Cloud Platform clusters.

Extraction Pipelines

Added

• New Extraction Pipelines resource to document extractors and monitor the status of data ingestion to make sure reliable and trustworthy data are flowing into the CDF data sets.
• API endpoints for creating, managing, and deleting extraction pipelines. Capture common attributes around extractors such as owners, contacts, schedule, destination RAW databases, and data set. Document structured metadata in the form of key-value attributes as well unstructured documentation attribute that supports Markdown (rendered as Markdown in Fusion).
• Extraction Pipelines Runs are CDF objects to store statuses related to an extraction pipeline. The supported statuses are: success, failure and seen. They enable extractor developers to report status and error message after ingesting data. As well enables for reporting heartbeat through seen status by the extractor to easily identify issues related to crushed applications and scheduling issues.

Sequences

Added

• Added partition parameter to the GET /sequences endpoint to support parallel retrieval.
• POST /sequences/list now supports parallel retrieval.

Time series

Added

• Added partition parameter to the GET /timeseries endpoint to support parallel retrieval.

IAM (Identity and access management)

Added

Added sessions to v1. Sessions let you securely delegate access to CDF resources for CDF services (such as Functions) by an external principal and for an extended time.

Relationships

Added

• Relationships now support Parallel Retrieval

3D

Added

• Added filter3dNodes endpoint to allow for more advanced filtering on node metadata

Labels

Added

• Dataset scoping based on dataSetIds.

Sequences

Added

• Added syntax for updating columns of existing sequences. Can remove columns, modify existing columns, and add new columns as well.

Assets

Added

• Added labels replace (set) method for assets update.

Time series

Changed granularity limits on hour aggreagates

You can now ask for a granularity of up to 100000 hours (previously 48 hours), both in normal aggregates and in synthetic time series.

IAM (Identity and access management)

Added

• Added a projects list endpoint to v1
• Added a token inspection endpoint to v1

Authentication

Deprecated

We are deprecating authentication via CDF service accounts and API keys, and user sign-in via /login, in favor of registering applications and services with your IdP (identity provider) and using OpenID Connect and the IdP framework to manage CDF access securely.

The legacy authentication flow is available for customers using Cognite Data Fusion (CDF) on GCP until further notice. We strongly encourage customers to adopt the new authentication flows as soon as possible.

The following API endpoints are deprecated:

• /api/v1/projects/*/apikeys
• /api/v1/projects/*/serviceaccounts
• /login
• /logout
• /api/v1/projects/*/groups/serviceaccounts ^*

^*only the sub-resources for listing, adding, and removing members of groups.

CDF API 0.5, 0.6 reached their end-of-life after its initial deprecation announcement in Summer 2019.

3D

Added

• Added partition parameter to the List 3D Nodes endpoint for supporting parallel requests.
• Added sortByNodeId parameter to the List 3D Nodes endpoint, improving request latency in most cases if set to true.

Entity matching

Fixed

• Fixed a bug in the documentation for Entity matching. The (job) status shall be capitalized string.

Files

Added

• New field fileType inside derivedFields to refer to a pre-defined subset of MIME types.
• New filter fileType inside derivedFields to find files with a pre-defined subset of MIME types.

Files

Added

• New field geoLocation to refer to the geographic location of the file.
• New filter geoLocation to find files matching a certain geographic location.

To learn how to leverage new geoLocation features, follow our guide.

Files

Added

• New field directory referring to the directory in the source containing the file.
• New filter directoryPrefix allows you to find Files matching a certain directory prefix.

Files

Added

• New field labels allows you to attach labels to Files upon creation or updating.
• New filter labels allows you to find Files that have been annotated with specific labels.

IAM (Identity and access management)

Added

• New project field applicationDomains. If this field is set, users only sign in to the project through applications hosted on a whitelisted domain. Read more.

Events

Added

• New aggregation uniqueValues allows you to find different types, subtypes of events in your project.

Labels

Added

• New data organization resource: labels. Manage terms that you can use to annotate and group assets.

Assets

Added

• New filter labels allows you to find resources that have been annotated with specific labels.

Time series

Added

• Combine various input time series, constants and operators with on-the-fly synthetic time series.

Events

Added

• New filtering capabilities to find open events endTime=null.
• New filtering capabilities to find all events intersecting a timespan using activeAtTime.

General

Added

• New data organization resource: data sets. Document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to your Cognite Data Fusion (CDF) project.
• New attribute datasetId introduced in assets, files, events, time series and sequences.
• New filter dataSetIds allows you to narrow down results to resources containing datasetId by a list of ids or externalIds of a data set. Supported by assets, files, events, time series and sequences.
• We have added a new aggregation endpoint for time series. With this endpoint, you can find out how many results in a tenant meet the criteria of a filter. We will expand this feature to add more aggregates than count.

Groups

Added

• Introduced a new capability: datasetsAcl for managing access to data set resources.
• New scope datasetScope for assets, files, events, time series and sequences ACLs. Allows you to scope down access to resources contained within a specified set of data sets.

3D

Fixed

• We fixed a bug in the documentation of 3D model revisions. Applications should anticipate that 3D nodes may not have a bounding box.

Assets

Added

• We have added a new aggregation endpoint for assets. With this endpoint, you can find out how many assets in a tenant meet the criteria of a filter. We will expand this feature to add more aggregates than count.

Events

Added

• We have added a new aggregation endpoint for events. With this endpoint, you can find out how many events in a tenant meet the criteria of a filter. We will expand this feature to add more aggregates than count.

Assets

Added

• We have added new aggregation properties: depth and path. You can use the properties in the filter and retrieve endpoints.

Assets

Added

• Added the property parentExternalId which is returned for all assets which have a parent with a defined externalId.

General

Added

• Added assetSubtreeIds as a parameter to filter, search, and list endpoints for all core resources. assetSubtreeIds allows you to specify assets that are subtree roots, and then only retrieve resources that are related to assets within those subtrees.

Assets

Added

• Added the ability to filter assets by parent external IDs.

Events

Added

• Added the ability to filter events by the external ID of linked assets

Access control

Removed

• Groups can no longer be created with a permissions field in v0.5.

Assets

Added

• Asset search now has a search.query parameter. This uses an improved search algorithm that tries a wider range of variations of the input terms and gives much better relevancy ranking than the existing search.name and search.description fields.

Time Series

Changed

• The search.query parameter for time series search now uses an improved search algorithm that tries a wider range of variations of the input terms, and gives much better relevancy ranking.

Files

Added

• Added support for updating the mimeType for existing files in files/update requests.

Time Series

Added

• Time series expanded their filtering capabilities with new Filter time series endpoint, allowing for additional filtering by:

  • Name
  • Unit
  • Type of time series: string or step series
  • Metadata objects
  • ExternalId prefix filtering
  • Create and last updated time ranges

  Endpoint in addition support pagination and partitioning. Check out detailed API documentation here.

Events

Added

• Added the ability to sort events on startTime, endTime, createdTime, and lastUpdatedTime

Sequences

Added

• Introducing the new sequences core resource type that lets you store numerically indexed multi-column rows of data. Connect your sequences to physical assets and to their source systems through externalId and metadata support. Read more here.

3D

Added

• Added endpoint to get multiple nodes for a 3D model by their IDs.
• Added endpoint to get asset mappings for multiple node IDs or asset IDs.

Files

Added

• Added support for filter on rootAssetIds in files GET /files (using query parameter) and POST /files/list (in request body).

Assets and Events

Added

• Added support for partition in /assets and /events to support parallel retrieval. See guide for usage here

3D

Added

• Added the query parameter intersectsBoundingBox to the list asset mappings endpoint. The parameter filters asset mappings to the assets where the bounding box intersects (or is contained within) the specified bounding box.

Files

Added

• Added support for sourceCreatedTime and sourceModifiedTime fields in files v1 endpoints.

Assets

Added

• Allow the parent asset ID to be updated. The root asset ID must be preserved, and you can not convert a non-root asset to a root asset or vice versa.
• Support for ignoreUnknownIds when deleting assets.

3D

Added

• Properties field for 3D nodes, extracted from uploaded 3D files.
• Ability to filter nodes with a specific set of properties.

Files

Changed

• Allow lookup of names with length up to 256 characters (was 50) for GET /files and POST /files/search operations.
• Allow creating and retrieving files with mimeType length up to 256 characters (was 64).

Time series

Added

• Added query parameter rootAssetIds to list time series endpoint. Returns time series that are linked to an asset that has one of the root assets as an ancestor.

List of changes for initial API v1 release in comparison to previous version - API 0.5

General

Added

• Support for externalId added across resource types. externalId lets you define a unique ID for a data object. Learn more: External IDs
• externalIdPrefix added as a parameter to the list events, assets and files operations.
• Richer filtering on the list assets, files and events operations.
• Search, list and filter operations for assets, events and files now support filtering on source and metadata field values.

Changed

• Core resources standardize on HTTP methods and URI naming for common operations such as search, partial updates, delete, list and filter
• API responses are no longer wrapped in a top level data object.
• Standardized pagination across resources through limit, cursor and nextCursor parameters.
• The limit parameter no longer implicitly rounds down requested page size to maximum page size.
• Standardized error responses and codes across all resources. Errors across CDF can be parsed into a single model.
• Overall improvements to reference documentation. Including documented input constraints, required fields, individual attribute descriptions.

Removed

• The sourceId field has been removed from resources. Use externalId instead of sourceId+source to define unique IDs for data objects.
• Sorting is removed from the search operations for files, assets, events and time series. Results are sorted by relevance.
• offset and previousCursor parameters are no longer supported for pagination across resources.
• Fetching an asset subtree is no longer supported by files, assets, events and time series.

Assets

Added

• Ability to select only root assets though new root filter.
• Added the rootId field to specify the top element in an asset hierarchy.
• Added the ability to filter by the root asset ID. This allows you to scope queries for one or many asset hierarchies.
• List Assets allows for filtering assets belonging to set of root assets, specified by list of asset internal ids. New query parameter: rootIds.
• Filter and Search Assets allows or filtering assets belonging to a set of root assets, specified by combination of internal and external asset identifiers. New body attribute: rootIds.

Changed

• Updating a single asset is no longer supported through a separate endpoint. Use the update multiple endpoint instead.
• Delete assets by default removes only leaf assets (assets without children). New parameter 'recursive' allows for enabling recursive removal of the entire subtree of the asset pointed by ID (API 0.5 behaviour).

Removed

• Overwriting assets is no longer supported.
• Filtering assets by their complete description is no longer supported.
• Locating assets fuzzily by name has been removed. Instead, search for assets on the name property.
• When searching assets, querying over both name and description in the same query is no longer supported.
• The experimental query parameter boostName has been removed from the search for assets operation.
• Removed the path and depth fields.

Events

Added

• Events can now be filtered on asset ID in combination with other filters.
• New filter rootAssetIds allows for narrowing down events belonging only to list or specified root assets. Supported by Filter and Search API

Removed

• Events can no longer be filtered by empty description.
• The 'dir' parameter has been removed from the search events operation.

Files

Added

• Filtering files by assetIds in list files operations now support multiple assets in the same request.

Changed

• Download file content has changed from HTTP GET to HTTP POST method.
• We have renamed the fileType field to mimeType. The field now requires a MIME formatted string (e.g. text/plain).
• We have renamed the uploadedAt field to uploadedTime.
• Resumable is now the default behavior for file uploads.
• Update metadata for single files is no longer supported by a separate operation. Instead, use the update multiple operation.

Removed

• Replace files metadata endpoint has been removed.
• Directory has been removed as a property of files.
• Updating the name or mimeType of a file through the update multiple files operation is no longer supported.
• Query parameter for specifying the sort direction has been removed from list all files operations.

Raw

Changed

• Raw has changed structure to become resource-oriented. The URL structure has changed.
• Recursively delete of tables and rows when deleting a database is now the default behavior without a control parameter.

Time series

Added

• Support for adding datapoints by id and externalId of time series. Adding datapoints to time series by name has been removed.
• Add ability to update the new externalId attribute for time series.
• Allow to set externalId during creation of time series. ExternalId requires uniqueness across time series.
• Consolidate multiple APIs to allow adding datapoints into a single endpoint. Allows datapoints to be added to multiple time series at the same time.
• Retrieve data points by using id and externalId of the time series.
• Time series created through API v1 are not discoverable by API 0.3, 0.4, 0.5 and 0.6 by default. Introduce the option to enable this compatibility by setting new attribute - legacyName on time series creation. Value is required to be unique.

Changed

• Get latest datapoints has been reworked. Introduces support for id and externalId lookup as well retrieval for multiple time series within the same request.
• Time series name is no longer limited by uniqueness. Note that time series (meta objects) created by API v1 will not be discoverable by older API versions.
• Delete time series endpoint has been redesigned to allow deletion of multiple time series by id and externalId.
• Delete single and multiple datapoints endpoint has been redesigned and consolidated into a single endpoint. New delete allows selection of multiple time series and time ranges by id and externalId. Selecting by name is no longer available.
• Update multiple time series restructured to support lookup by externalId.
• Retrieve time series by ID endpoint restructured adding the ability to get time series by externalId.
• Set limit for data point value to min -1E100, max 1E100.

Removed

• Experimental feature for performing calculations across multiple time series (synthetic time series), function and alias attributes are no longer available.
• The experimental query parameter boostName has been removed from search operation.
• Short names for aggregate functions are no longer supported.
• Ability to remove time series by name have been removed as names are no longer unique identifiers.
• Select multiple time series and time ranges by name is no longer available.
• The ability to update isString and isStep attributes is removed. The attributes are not intended to be modified after creation of time series.
• The endpoint for updating single time series is removed. Use the update multiple time series endpoint instead.
• Remove ability to overwrite time series object by id. Use the update multiple time series endpoint instead.
• The ability to retrieve time series matching by name has been removed. Use externalId instead.
• The ability to retrieve by id from a single time series has been removed. Use retrieve multiple datapoints for multiple time series instead.
• The ability to retrieve time-aligned datapoints through "dataframe" API has been removed. Similar functionality is available through our supported SDKs.
• The ability to add datapoints to time series by name has been removed.
• The ability to look up by time series name has been removed.

IAM (Identity and access management)

Added

• The login status endpoint includes the ID of the API key making the request (new attribute: apiKeyId), if the request used an API key.

Changed

• The user resource type has been replaced with service accounts. Users from previous API versions are equivalent to service accounts.
• Adding, listing and removing users from a group has been replaced by equivalent operations for service accounts.
• Retrieve project returns a single object instead of a list.
• API keys endpoints for list/create rename userId attribute to serviceAccountId.

Removed

• List and create groups no longer use the permissions and source attributes.

3D

Added

• New 3D API lets you upload and process 3D models. Supported format: FBX.
• Ability to create and maintain multiple revisions for the 3D models.
• API for mapping relationships between 3D model nodes and asset hierarchy.

An organization is used to group CDF projects and facilitate their management.

An organization holds users, projects, and perhaps other organizations. The organization ID is what the users enter when logging into Cognite apps, such as Cognite Data Fusion. The organization has one IdP configuration, which is used for both interactive login and service account authentication against all projects in the organization.

External identity providers (IdP)

CDF supports interfacing with external IdPs to manage users and groups. The following vendors are supported:

• Microsoft Entra ID (formerly known as Azure AD or Azure Active Directory)
• Auth0
• Keycloak

Users

If a user can log into the external IdP configured for the organization, then they have access to the CDF organization. Which of the organization's projects they have access to, and what they may do inside those projects, is determined by the access settings within each project.

After a user has logged into the organization for the first time, they will be visible in the organization's user list. Users can see each other, which enables them to collaborate on projects.

Organization hierarchy

An organization can have child organizations. The ownership relationship is materialized through the parentId field of the organization resource.

Projects

An organization holds CDF projects. The users that are logged into the organization can see all the projects in the organization, but what they can actually do within each project is controlled by the project's access control lists (ACLs) and other access control settings.

Allowed clusters

An organization has a list of clusters on which it can hold projects. This is the allowedClusters field on the resource.

Organization admins

An organization can have admins, which are identified principals that can perform an extended set of modifications on the organization, such as creating projects, changing who the admins are, and so on.

Admins are identified by the adminGroupId field on the organization resource, which is the ID of a group that is managed in the external IdP.

The different organization API endpoints have different access rules, which are documented under each endpoint. The general rule is that admins of a given organization have control over most aspects of the organization itself and full control of any sub-organizations.

Authentication for this API

Organizations are global, which means that they are not tied to specific projects or clusters. API requests against organizations are directed to auth.cognite.com, instead of a specific cluster and projects as for other resources.

Only OAuth tokens issued by https://auth.cognite.com (such as the ones issued when logging into Fusion) are accepted by the organizations API.

It is also possible to obtain a token by initiating a login flow against the authorization server directly. See the "Authorizations" sections for more information.