> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognite.com/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate Simulator Models > Calculate aggregates for simulator models, considering the optional filter specification. ## OpenAPI ````yaml https://storage.googleapis.com/cognitedata-api-docs/dist/20230101-alpha.json post /simulators/models/aggregate openapi: 3.1.0 info: title: Cognite API description: >- # Introduction This is the reference documentation for the Cognite API with an overview of all the available methods. # Postman 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](https://hub.cognite.com/open-industrial-data-211) to understand how to get the credentials for use in Postman. For more information, see [Getting Started with Postman](https://developer.cognite.com/dev/guides/postman/). # 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 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. # Requests throttling 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](https://docs.cognite.com/dev/concepts/resource_throttling). # API versions ## Version headers 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. ## Beta versions 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 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`. version: v1 contact: name: Cognite Support url: https://support.cognite.com email: support@cognite.com servers: - url: https://{cluster}.cognitedata.com/api/v1/projects/{project} description: The URL for the CDF cluster to connect to variables: cluster: enum: - api - az-tyo-gp-001 - az-eastus-1 - az-power-no-northeurope - westeurope-1 - asia-northeast1-1 - gc-dsm-gp-001 default: api description: The CDF cluster to connect to project: default: publicdata description: The CDF project name. security: - oidc-token: - https://{cluster}.cognitedata.com/.default - oauth2-client-credentials: - https://{cluster}.cognitedata.com/.default - oauth2-open-industrial-data: - https://api.cognitedata.com/.default - oauth2-auth-code: - https://{cluster}.cognitedata.com/.default tags: - name: Changelog description: > This article documents all notable changes to the Cognite Data Fusion (CDF) API v1. ## 2026-06-23 ### Atlas AI (beta) #### Added - New `GET /ai/project-config` endpoint to retrieve the Atlas project configuration for the authenticated CDF project. - New `POST /ai/project-config` endpoint to create or update the Atlas project configuration, including setting a default orchestrator agent for the project (`defaultAgent` field). #### Changed - Increased the maximum number of custom client actions (`actions`) per agent session request from 15 to 20. #### Removed - Removed `aws/claude-4-sonnet` as an available language model option. ## 2026-06-19 ### Data Products #### Added - `POST /dataproducts/byids` retrieves multiple data products by externalId (up to 100 per request). ## 2026-06-17 ### Groups API #### Added - Added `integrationConfigsAcl` support to `CogniteCapability`, including `integrationconfigs_aclAcl`, `integrationconfigs_aclAction`, and `integrationconfigs_aclScope` schema definitions. - Added `integrationsAcl` support to `CogniteCapability`, including `integrations_aclAcl`, `integrations_aclAction`, and `integrations_aclScope` schema definitions. ### Token API #### Added - Added "Integration Configs Capability" to the token inspection response, including required `integrationConfigsAcl` and `projectScope` properties. - Added "Integrations Capability" to the token inspection response, including required `integrationsAcl` and `projectScope` properties. ## 2026-06-15 ### Data Workflows #### Added - Added `initializeCursor` to `RecordStreamTrigger` to control where record stream syncing starts when no cursor exists yet. Defaults to `"0d-ago"` for backward compatibility. #### Changed - `RecordStreamTrigger` is now generally available (GA). ## 2026-06-12 ### Postgres gateway #### Changed - `POST /postgresgateway/byids`: renamed `operationId` from `retreive_users` to `retrieve_users`. This might impact generated SDKs and API documentation deep links that reference the old operation name. ## 2026-05-28 ### Data Products #### Added A new API for managing data products. Data products act as a governance layer around data modeling, establishing trust and reliability for business decisions through clear ownership, comprehensive metadata, and standardized access patterns. - `POST /dataproducts` creates a data product. - `GET /dataproducts` lists all data products. - `GET /dataproducts/{externalId}` gets a data product. - `POST /dataproducts/update` updates a data product. - `POST /dataproducts/delete` deletes a data product. - `POST /dataproducts/{externalId}/versions` creates a data product version. - `GET /dataproducts/{externalId}/versions` lists all versions of a data product. - `GET /dataproducts/{externalId}/versions/{version}` gets a data product version. - `POST /dataproducts/{externalId}/versions/update` updates a data product version. - `POST /dataproducts/{externalId}/versions/delete` deletes data product versions. ### Entity matching #### Changed - `GET /context/entitymatching`: added cursor pagination (`cursor` query parameter, optional `nextCursor` in response). `limit` defaults to 100 with maximum 1000. ## 2026-05-27 ### Atlas AI #### Added - Agent list: optional query `skillExternalId` to filter agents by skill external ID. #### Changed - Skills upload: query `externalId` is required to set the CDF external ID for `SKILL.md` (trimmed before validation; was optional with frontmatter `name` as fallback). - Skills create: `externalId` is required on the create request body (was optional). - Agent list: `skillName` query filter constrained to skill-name rules (1–64 characters; lowercase letters, digits, and hyphens; must not start with `cdf-`). - Skill `externalId`: 1–128 characters, no null (U+0000), must not start with `cdf-` (replaces slug-style name rules, max 64). - Skills upload: single UTF-8 `.md` file only (`SKILL.md` shape); zip archives and additional skill files are no longer supported. - Skills create/upload: project may have at most **200** skills (`maxSkillLimit` default **200**, was 30); exceeding the limit returns **400**. - Download: `GET /ai/skills/{skill_external_id}/download` — path uses skill external ID (was `skill_name`); zip contains the skill's `SKILL.md` only; `skill_external_id` is trimmed before validation. #### Removed - `GET /ai/skills/{skill_name}/{file_external_id}` per-file download endpoint. - `additionalFiles` on skill create/update and related schemas (`AdditionalFileRequest`, `SkillAdditionalFileResponse`). - Zip-based skill upload and multi-file skill packages. ## 2026-05-26 ### Data Modeling API #### Added - Added `recordsOnlyContainers` and `recordsOnlyContainerProperties` to `ProjectStatistics` response definition. - Added `containerProperties`, `recordsOnlyContainers` and `recordsOnlyContainerProperties` to `SpaceStatistics` response definition. ## 2026-05-22 ### Chat Completions API (alpha) #### Added - Added new `ai/openai/chat/completions` endpoint to generate chat completions - Added new `ai/openai/models` endpoint to list available models ### Agents API (beta) #### Added - Added `subagents` field to the agents API ## 2026-05-21 ### Functions #### Changed - `POST /functions/{functionId}/call` now returns `429 Too Many Requests` (previously `400`) when a function has reached 100 concurrent running calls. The response schema is unchanged. This change was communicated on Cognite Hub in September 2025. ## 2026-05-18 ### Atlas AI #### Changed - Skills download and per-file read endpoints: `skill_name` and `file_external_id` path segments are trimmed of leading and trailing whitespace before validation. - Per-file read `file_external_id`: accepts any 1–128 character identifier without null (U+0000); updated parameter and response descriptions. ### Token API #### Added - Added "Cognite Units Capability" to the token inspection response, including required `cogUnitsAcl` and `projectScope` properties. ## 2026-05-12 ### Atlas AI #### Added - Added Skills API (`/ai/skills`, by-ids, delete, upload, download, per-file read) and related schemas. - Agent schemas: `labels`, `skills`; runtime metadata and session chunk/progress response types. - Agent session (beta): `retentionPolicy` when starting a conversation (`temporary` by default vs `persisted`). #### Changed - Agent contract defaults: model `azure/gpt-4.1`, runtime **1.2.0**; `ownerId` described as read-only (set on create). ### Functions #### Changed - `owner` on `POST /functions` is now server-stamped from the caller's token when absent or when it carries the reserved `user_identifier:` prefix; all other client-supplied values are preserved. ## 2026-05-08 ### Groups API #### Added - Added `cogUnitsAcl` support to `CogniteCapability`, including `cogunits_aclAcl`, `cogunits_aclAction`, and `cogunits_aclScope` schema definitions. ### Data Workflows (internal) #### Added - Added `docParser` task type to Data Workflows ## 2026-05-07 ### Data Modeling API #### Added - Added `isAutoRetryable` to `UpsertConflict` response definition. ### Agent APIs (beta) #### Added - Documented the `query` agent tool (beta) for exploring Cognite data models and instances with direct SDK-level control. #### Changed - Updated the documented default agent `runtimeVersion` to 1.2.0 (previously 1.1.1). ## 2026-05-06 ### Data Workflows (beta) #### Changed - Upgrade Json Mapping task type definition to beta version - Remove deprecated `inputs` arguments from Json Mapping task type ### Cognite Functions #### Added - Added `functionType` as a get-only field on Cognite Functions allowing to differentiate between `classic` functions and `functionApp`. ## 2026-05-05 ### Signals #### Changed - Signals API is now in beta (promoted from alpha) ### Seismic #### Removed - Seismic API is removed ## 2026-05-04 ### Simulator integration API #### Changed - Made `simulatorIntegrationExternalId` optional when creating routines, routine revisions, and simulation runs. - Added `queued` status to `SimulationRunStatus` enum to represent runs which are not assigned to any connector. ## 2026-04-30 ### Streams and Records API #### Added - `targetUnits` parameter has been added to records `/sync`, `/filter` and `/aggregate` endpoint requests, which allows unit conversion from source units to specified target units or unit system. - `includeTyping` parameter has been added to records `/sync`, `/filter` and `/aggregate` endpoint requests. If set to true, typing information of properties present in the request and the response will be included in the response. ## 2026-04-23 ### Cognite Functions #### Changed - Cognite functions now use Python 3.13 (py313) as the default runtime, replacing Python 3.12 (py312). ### Agent APIs (beta) #### Added - Extended `ReasoningDTO` with a structured `data` field to expose machine-readable reasoning payloads in agent chat responses. - Added reasoning payload schemas `AgentReasoningDataDTO` and `ToolCallDetailDTO` to represent tool-call details in reasoning output. ## 2026-04-21 ### Documents AI API #### Added - Added an optional `text` field (array of strings, defaults to empty) to `PageReferenceDTO` (beta). When the `DocumentAskTool` returns file attachments, each page reference now includes the raw passage text that was cited, in addition to the page number. ## 2026-04-15 ### Data Modeling API #### Added - New debug notice `intractableCursorWithNestedFilter` (grade D, warning): emitted when a query supplies both a cursor and a nested filter on the same result set expression. The additional join required by the nested filter can prevent efficient index-backed pagination. ## 2026-04-10 ### Cognite Functions #### Added - Added functionsAcl:RUN action, which grants permission to call functions without the ability to create or delete them. functionsAcl:WRITE continues to include call access in addition to create and delete permissions. ## 2026-03-25 ### Streams and Records API #### Changed Stricter validation in aggregate records request: - Aggregate identifiers can no longer contain `.` character. - Values `_count` and `_bucket_count` can no longer be used as aggregate identifiers. - Duplicate aggregate identifiers within the aggregate tree are no longer allowed. ## 2026-03-24 ### Data Modeling API #### Changed - Added `EnumProperty` to `RecordContainerPropertyTypeDefinition`, enabling enum properties in containers with `usedFor` set to `record`. - Updated the supported storage types description for record container properties to include `enum`. ## 2026-03-23 ### Streams and Records API #### Changed - Fixed maximum number of active streams created from `BasicLiveData` template to match what we actually allow. ## 2026-03-20 ### Data Workflows (beta) #### Added - Added new `functionApp` task type, enabling workflows to invoke HTTP endpoints on Cognite Function Apps. Supports built-in system paths (e.g. `/__health__`, `/__routes__`) and user-defined routes. ## 2026-03-17 ### Transformations #### Added - Added `autoCreate` field to `ViewDataSource` and `DataModelSource` destination configurations for transformations. The `autoCreate` field accepts an `AutoCreateOptions` object with three boolean properties: - `startNodes`: Controls automatic creation of missing start nodes when creating edges (default: true) - `endNodes`: Controls automatic creation of missing end nodes when creating edges (default: true) - `directRelations`: Controls automatic creation of missing direct relation targets (default: true) When set to false, the transformation will validate node/relation references and return a 400 error if referenced instances do not exist. ## 2026-03-12 ### 3D API (beta) #### Deprecated - Deprecated `ContextualizeImage360AnnotationBody` and `DeleteContextualizedImage360AnnotationsBody` request bodies for the 360 image contextualization endpoints. These will be removed before the endpoints are released. Use the RC (Release Candidate) variants (`ContextualizeImage360AnnotationRCBody` and `DeleteContextualizedImage360AnnotationsRCBody`) instead. ## 2026-03-09 ### Agent APIs (beta) #### Added - New OpenAI models: `azure/gpt-5.2`, `azure/gpt-5.4` Note: Availability of models may differ between the chosen cloud provider and region of the CDF cluster. ## 2026-03-06 ### Agent APIs (beta) #### Changed - Changed the default Query Knowledge Graph (QKG) Tool strategy from v1 to v2. ## 2026-03-04 ### Agent APIs (beta) #### Added - Added `stream` parameter to `AgentSessionRequest` to enable progress message streaming. ## 2026-01-20 ### Data Modeling API #### Added - Added 3 new endpoints to trigger revalidation of failed constraints or indexes. - `/models/containers/constraints/retry` for container-level constraints (`requires`, `uniqueness`) - `/models/containers/indexes/retry` for indexes - `/models/containers/properties/retry` for property-level constraints (`nullable`, `maxListSize`, `maxTextSize`) ## 2026-01-15 ### Data Workflows #### Added - Added `maxConcurrentExecutions` field to workflows to limit concurrent executions. ## 2026-01-13 ### Hosted Extractors #### Added - Added support for client credentials authentication to eventhub sources. ## 2026-01-06 ### 3D API (beta) #### Added - Added (beta) documentation for a new `/3d/contextualization/cad` endpoint, for contextualization of CAD nodes and asset instanceIds in DataModelOnly projects. This endpoint is preferred over the legacy `/3d/models//revisions//mappings` endpoint. ## 2025-12-06 ### Data Workflows #### Added - Added `parentTaskExternalId` field to `TaskExecution` schema to identify the parent task for tasks within dynamic tasks or subworkflows. The field is null for top-level tasks. ## 2025-12-05 ### 3D API (beta) #### Added - Added (beta) documentation for the optional `pipelineConfiguration` property for the 3D API create revision endpoint, for point cloud processing in Hybrid CDF projects. The settings within that property controls opt-in point cloud processing steps such as 360-images extraction, point cloud classification and point cloud volume suggestions. ## 2025-11-25 ### Data Workflows #### Added - Added `/workflows/triggers/{triggerExternalId}/pause` endpoint to pause triggers. A paused trigger will not create new workflow executions until resumed. - Added `/workflows/triggers/{triggerExternalId}/resume` endpoint to resume a previously paused trigger. ## 2025-11-28 ### Data Modeling API #### Added - Added `record` value that can be specified for the container's ```usedFor``` property ## 2025-11-26 ### Agent APIs (beta) #### Added - Within Agent CRUD requests, under the agent objects `tools` section, a description of each tool is now rendered above the selected `type` that explains what the tool is about. ### 3D API (beta) #### Added - Added more detailed documentation for the OptimizerJob type in the 3d/jobs endpoint, especially configuration for Point cloud processing. This will be available as Beta documentation. ## 2025-11-21 ### Hosted extractors API #### Added - Added `authCertificate` to REST sources. #### Deprecated - Deprecated eventhub `keyName` and `keyValue` in favor of `authentication`. `username` and `password` with basic authentication replaces the old fields. This is to make room for other forms of authentication. ## 2025-11-20 ### Agent APIs (beta) #### Added - Added `runtimeVersion` field to agent creation, update, and response schemas. The runtime version defines the complete execution environment including system prompt, available tools, and core features. Defaults to version 1.0.2. - Added `examineDataSemantically` (alpha) to the list of available tools for agents. - Added new AWS model: `aws/claude-4.5-sonnet`. ## 2025-11-18 ### Simulator integration API #### Added - Added `kind` field to simulator routines and routine revisions (beta) to classify routines by size and complexity; use `long` for routines that require more inputs, outputs, and script steps than usual. - Added `kind` filter to the simulator routines list endpoint (`POST /simulators/routines/list`) and routine revisions list endpoint (`POST /simulators/routines/revisions/list`), allowing filtering of routines by kind. In the revisions listing (`POST /simulators/routines/revisions/list`), `includeAllFields=true` returns all fields but omits 'long' routines and cannot be combined with the `kind` filter. ## 2025-11-13 ### 3D API #### Added - Added 3D API endpoints to create and delete image 360 contextualization connections to CogniteAsset instances. These endpoints are only available in DataModelOnly projects. Currently available in beta - `POST /3d/contextualization/image360` define image360 contextualizations towards assets - `POST /3d/contextualization/image360/delete` remove image360 contextualizations towards assets ## 2025-11-11 ### Streams and Records API #### Changed - Changed format of partial success response for record ingest, upsert and delete operations. ## 2025-11-06 ### Simulator integration API - Added `simulatorExternalIds` filter to the simulator model revisions list endpoint (`POST /simulators/models/revisions/list`), allowing filtering of model revisions by simulator external IDs. ## 2025-11-04 ### Streams and Records API #### Added - The Streams and Records API is now in General Availability (GA). - The following endpoints are now available: - `POST /streams` to create a stream. - `DELETE /streams/{streamId}` to delete a stream. - `GET /streams` to list all streams. - `GET /streams/{streamId}` to retrieve a specific stream. - `POST /streams/{streamId}/records` to create new records into a stream. - `POST /streams/{streamId}/records/upsert` to create new or update existing records in a mutable stream. - `POST /streams/{streamId}/records/delete` to delete records in a mutable stream. - `POST /streams/{streamId}/records/filter` to retrieve records from a stream. - `POST /streams/{streamId}/records/sync` to sync records from a stream. - `POST /streams/{streamId}/records/aggregate` to aggregate record data from a stream. ## 2025-10-29 ### Simulator integration API #### Added - Added `simulatorExternalIds` filter to the simulator routines list endpoint (`POST /simulators/routines/list`), allowing filtering of routines by simulator external IDs. - Added support for simulator routines aggregation (`POST /simulators/routines/aggregate`) ## 2025-10-07 ### 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. ## 2025-10-03 ### Cognite Functions #### Removed - Python 3.9 (py39) is no longer supported as a runtime argument for Cognite functions. ## 2025-10-02 ### Agent APIs (beta) - Gemini 2.0 Flash and Claude 3 Haiku have been retired as model options. ## 2025-10-01 ### 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. ## 2025-09-29 ### 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. ## 2025-09-26 ### Time Series API #### Changed - Increased the maximum length of string data points from 255 characters to 1023 bytes (UTF-8 encoded). ## 2025-09-09 ### 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. ## 2025-09-08 ### 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). ## 2025-09-02 ### 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. ## 2025-08-26 ### Data sets API #### Fixed - Add length constraints on `name` and `description` fields for the `/update` endpoint to disallow empty strings. ## 2025-09-02 ### 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` ## 2025-08-28 ### 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. ## 2025-08-29 ### 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) ## 2025-09-02 ### 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. ## 2025-08-20 ### 3D API #### Added - Added support in the create 3D asset mappings endpoint for creating asset mappings for 3D CAD `nodeId` and CogniteAsset`assetInstanceId` 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. ## 2025-07-21 ### 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`. ## 2025-07-18 ### Data Modeling API #### Added - Add `timezone` property to the `/trigger` endpoint. ## 2025-07-04 ### 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. ## 2025-06-30 ### Data Modeling API #### Added - Add `allowExpiredCursorsAndAcceptMissedDeletes` flag to the `/sync` endpoint. ## 2025-05-21 ### 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. ## 2025-05-26 ### 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](https://api-docs.cognite.com/20230101-beta/tag/Simulators) for more details. ## 2025-05-21 ### 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. ## 2025-05-15 ### 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. ## 2025-05-15 ### Transformations #### Changed - Enforcement of 90 days retention rule for job history ## 2025-05-09 ### 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 ## 2025-04-30 ### 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 ## 2025-04-23 ### 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. ## 2025-03-25 ### 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`). ## 2025-03-13 ### Documents API #### Added - Added ability to filter on the `space` and `externalId` properties of an `instanceId` object. ## 2025-03-12 ### Time Series API #### Added - New aggregates `maxDatapoint` and `minDatapoint`, that gives back both the value and the timestamp of the maximum/minimum data point. ## 2025-02-17 ### 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. ## 2025-02-15 ### 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. ## 2025-01-20 ### Hosted Extractors API #### Added - Added support for `clientCredentials` auth to kafka sources. ## 2024-12-03 ### 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. ## 2024-11-19 ### 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). ## 2024-11-14 ### 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. ## 2024-11-12 ### Organizations and Projects #### Updated - `GET /api/v1/orgs/{org}/projects?includeAdminProperties=true` now includes `state` and `deletionTime` ## 2024-10-22 ### 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. ## 2024-10-14 ### 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. ## 2024-10-11 ### 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. ## 2024-09-31 ### 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. ## 2024-09-19 ### Contextualization / Vision #### Added - Support for Vision endpoints referencing files by data modeling instance IDs, as an alternative to ID and external ID. ## 2024-09-14 ### 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)](https://api-docs.cognite.com/20230101-beta/tag/Simulators/) 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 ## 2024-09-13 ### Contextualization / Engineering diagrams #### Added - Support for detecting tags in diagrams referencing files by data modelling instance ids as an alternative to id and externalId. ## 2024-09-12 ### Files API #### Added - Add support for `ignoreUnknownIds` to the `files/delete` endpoint. ### SAP Writeback #### Added - SAP Writeback API (Beta) ## 2024-09-10 ### 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. ## 2024-09-02 ### 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 ## 2024-08-23 ### Data Workflows #### Added - subworkflow task: add support for referencing other workflow versions to run as part of a workflow ## 2024-08-20 ### 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. ## 2024-07-18 ### 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. ## 2024-06-24 ### Data Modeling #### Added - Support marking properties as immutable ## 2024-06-17 ### 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. ## 2024-06-13 ### 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. ## 2024-05-24 ### 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. ## 2024-05-23 ### 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. ## 2024-05-02 ### Postgres gateway #### Added - Endpoints for managing PostgreSQL gateway ## 2024-05-01 ### Time series #### Added - Added support for [status codes](https://developer.cognite.com/dev/concepts/resource_types/timeseries#data-point-quality-status-codes) for data points. ## 2024-04-02 ### 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. ## 2024-03-19 ### 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. ## 2024-03-11 ### 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. ## 2024-03-06 ### 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 ## 2024-02-29 ### 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 ## 2024-02-20 ### 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 ## 2024-02-19 ### Time series #### Added - Data point subscriptions reaches General Availability (GA). - Use the new [Data point subscriptions](https://developer.cognite.com/dev/concepts/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. ## 2024-02-08 ### Hosted Extractors #### Changed - `host` in kafka sources has been replaced with `bootstrapBrokers`, which is an array of objects with `host` and `port`. ## 2024-02-01 ### Synthetic time series #### Added - Support for unit conversion by setting `targetUnit` or `targetUnitSystem` on time series or aggregates with a compatible `unitExternalId` field. ## 2024-01-16 ### 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. ## 2024-01-02 ### Data Modeling #### Added - Support for a `bySpace` flag on btree indexes and uniqueness constraints. ## 2023-12-12 ### Data Modeling #### Added - **Units catalog support for container properties**: You can now specify a unit from [CDF units catalog](https://developer.cognite.com/dev/concepts/resource_types/units) on `float32` and `float64` properties in containers. ## 2023-12-11 ### Time series #### Changed - Data point subscriptions [list data (beta)](https://api-docs.cognite.com/20230101-beta/tag/Data-point-subscriptions/operation/listSubscriptionData/) 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. ## 2023-12-06 ### Time series #### Added - [Units catalog](https://developer.cognite.com/dev/concepts/resource_types/units) support to time series. This comes in addition to the existing free-text unit field. - [Create timeseries](https://docs.cognite.com/api#tag/Time-series/operation/postTimeSeries) with a unitExternalId. - [Update timeseries](https://docs.cognite.com/api#tag/Time-series/operation/alterTimeSeries) 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](https://docs.cognite.com/api#tag/Time-series/operation/listTimeSeries). - [Aggregate time series](https://docs.cognite.com/api#tag/Time-series/operation/aggregateTimeSeries). - [Search time series](https://docs.cognite.com/api#tag/Time-series/operation/searchTimeSeries). - Added unit conversion support to [retrieve data points/aggregates](https://docs.cognite.com/api#tag/Time-series/operation/getMultiTimeSeriesDatapoints) and [retrieve latest](https://docs.cognite.com/api#tag/Time-series/operation/getLatest). 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. ## 2023-11-30 ### 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. ## 2023-11-21 ### Units Catalog #### Added - Added the [Units Catalog](https://docs.cognite.com/api#tag/Units) 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. ## 2023-11-17 ### 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. ## 2023-11-08 ### Engineering diagrams #### Changed - Optional token mechanism for accessing detected results of engineering diagrams without read all access to assets. See [diagram/detect](https://api-docs.cognite.com/20230101/tag/Engineering-diagrams/operation/diagramDetect) for details. ## 2023-10-23 ### 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](https://docs.cognite.com/api/20230101/#tag/Files/operation/initMultiPartUpload) and - [Complete multipart upload](https://docs.cognite.com/api/20230101/#tag/Files/operation/completeMultiPartUpload) endpoints. ## 2023-10-17 ### 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 ## 2023-10-10 ### 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. ## 2023-10-05 ### Hosted extractors #### Added - Hosted extractors API (Beta) - Use the new [Hosted extractors](https://docs.cognite.com/cdf/integration/guides/extraction/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. ## 2023-09-27 ### 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". ## 2023-08-25 ### Transformations #### Changed - Fixed wrong description for fields in "transformations/update" and "/transformations/schedules/update" ## 2023-08-22 ### Functions #### Changed - Remove Functions runtime "py37". ## 2023-08-22 ### Time series #### Added - Data point subscriptions (Beta) - Use the new [Data point subscriptions](https://developer.cognite.com/dev/concepts/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) ## 2023-08-10 ### Time series #### Added - Advanced query language support reaches General Availability (GA). - Advanced search, filtering, and sorting capabilities in the [Filter time series](https://docs.cognite.com/api/20230101/#tag/Time-series/operation/listTimeSeries) endpoint. - Advanced aggregation capabilities in the [Aggregate time series](https://docs.cognite.com/api/20230101/#tag/Time-series/operation/aggregateTimeSeries) endpoint. ### Sequences #### Added - Advanced query language support reaches General Availability (GA). - Advanced search, filtering, and sorting capabilities in the [Filter sequences](https://docs.cognite.com/api/20230101/#tag/Sequences/operation/advancedListSequences) endpoint. - Advanced aggregation capabilities in the [Aggregate sequences](https://docs.cognite.com/api/20230101/#tag/Sequences/operation/aggregateSequences) endpoint. ## 2023-08-08 ### Assets #### Added - Advanced query language support reaches General Availability (GA). - Advanced search, filtering, and sorting capabilities in the [Filter assets](https://docs.cognite.com/api/20230101/#tag/Assets/operation/listAssets) endpoint. - Advanced aggregation capabilities in the [Aggregate assets](https://docs.cognite.com/api/20230101/#tag/Assets/operation/aggregateAssets) endpoint. ### Events #### Added - Advanced query language support reaches General Availability (GA). - Advanced search, filtering, and sorting capabilities in the [Filter events](https://docs.cognite.com/api/20230101/#tag/Events/operation/advancedListEvents) endpoint. - Advanced aggregation capabilities in the [Aggregate events](https://docs.cognite.com/api/20230101/#tag/Events/operation/aggregateEvents) endpoint. ### Documents #### Added - Advanced query language support reaches General Availability (GA). - Advanced aggregation capabilities in the [Aggregate documents](https://docs.cognite.com/api/20230101/#tag/Documents/operation/documentsAggregate) endpoint. ## 2023-06-27 ### IAM (Identity and access management) #### Changed - Identity providers (IdP) are required to be compatible with the [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) standard, and compliance will now be enforced by the [Projects](tag/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`. ## 2023-06-05 ### 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](tag/Time-series/operation/listTimeSeries) endpoint. - Advanced aggregation capabilities in the [Aggregate time series](tag/Time-series/operation/aggregateTimeSeries) endpoint. ### Sequences #### Added - Added advanced query language support (Beta). - Advanced search, filtering, and sorting capabilities in the [Filter sequences](tag/Sequences/operation/advancedListSequences) endpoint. - Advanced aggregation capabilities in the [Aggregate sequences](tag/Sequences/operation/aggregateSequences) endpoint. ## 2023-05-19 ### Transformations #### Added - Adding support for data model centric and view centric schema. ## 2023-04-24 ### Transformations #### Removed - Removing support for authentication via API keys when creating or updating transformations. ## 2023-05-04 ### 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. ## 2023-04-18 ### All resources #### Added - Added information about [Requests throttling](section/Requests-throttling). #### Changed - Updated the [Parallel retrieval](section/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](https://docs.cognite.com/api/20230101-beta/#tag/Assets/operation/listAssets) endpoint. - Advanced aggregation capabilities in the [Aggregate assets](https://docs.cognite.com/api/20230101-beta/#tag/Assets/operation/aggregateAssets) endpoint. ### Events #### Added - Added advanced query language support (Beta). - Advanced search, filtering, and sorting capabilities in the [Filter events](https://docs.cognite.com/api/20230101-beta/#tag/Events/operation/advancedListEvents) endpoint. - Advanced aggregation capabilities in the [Aggregate events](https://docs.cognite.com/api/20230101-beta/#tag/Events/operation/aggregateEvents) endpoint. ### Documents #### Added - Added advanced query language support (Beta). - Advanced aggregation capabilities in the [Aggregate documents](https://docs.cognite.com/api/20230101-beta/#tag/Documents/operation/documentsAggregate) endpoint. ## 2023-04-12 ### Sessions #### Fixed - Fixed the API documentation for the request body of the [POST /projects/{project}/sessions/byids](tag/Sessions/operation/getSessionsByIds) 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](tag/Sessions/operation/getSessionsByIds) 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. ## 2023-04-04 ### Transformations #### Change - Transformations support new target types for view-centric data model instances. #### Added - Added target types `nodes` and `edges`. ## 2023-03-06 ### 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. ## 2023-02-03 ### 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. ## 2023-02-07 ### Documents #### Added - Added `highlight` field in the `search` endpoint to indicate whether matches in search results should be highlighted. ## 2023-01-18 ### 3D #### Added - Added support for using names filter in list nodes endpoint. ## 2023-01-17 ### 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. ## 2023-01-12 ### Documents #### Added - Added support for approximateCardinality aggregate. ## 2023-01-10 ### Documents #### Added - Added the search leaf filter, to allow filtering by searching through specified properties. ## 2023-01-09 ### Documents #### Added - Added the uniqueProperties aggregation, which can be used to find all the metadata keys in use. ## 2023-01-06 ### Documents #### Added - Added inAssetSubtree filter to filter documents that have a related asset in a subtree rooted at any of the specified IDs. ## 2023-01-02 ### Documents #### Added - Added advanced filters for metadata (prefix, in, equals) ## 2022-12-06 ### 3D #### Added - Added get3DNodesById endpoint to be able to fetch 3D nodes mapped to an asset. ## 2022-12-16 ### 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. ## 2022-11-29 ### Events #### Added - Added `nulls` field to the sort property specification ## 2022-11-17 ### Time series #### Added - Added `nextCursor` field to [Retrieve data points](tag/Time-series/operation/getMultiTimeSeriesDatapoints), to support cursor pagination ## 2022-10-14 ### Geospatial #### Added - Added the [POST /projects/{project}/geospatial/compute](tag/Geospatial/operation/compute) endpoint. ## 2022-10-11 ### Transformations #### Added - Added capability to run a transformation with Nonce credentials provided through the Run endpoint. ## 2022-10-06 ### IAM (Identity and access management) #### Added - Added the [POST /projects/{project}/sessions/byids](tag/Sessions/operation/getSessionsByIds) endpoint. ## 2022-09-09 ### Vision (Contextualization) #### Added - Move Vision extract service from playground to V1. ## 2022-08-12 ### Time series #### Changed - Updated datapoints timestamp range from 1971 - 2050 to 1900 - 2050. Affected endpoints: - [Insert data points](tag//Time-series/operation/postMultiTimeSeriesDatapoints) - [Retrieve data points](tag//Time-series/operation/getMultiTimeSeriesDatapoints) - [Delete data points](tag//Time-series/operation/deleteDatapoints) - [Retrieve latest data point](tag//Time-series/operation/getLatest) - [Synthetic query](tag//Synthetic-Time-Series/operation/querySyntheticTimeseries) ## 2022-07-21 ### Transformations #### Added - Added authentication using nonce for transformation's exisiting endpoints. ## 2022-06-21 ### Annotations (Data organization) #### Added - Moved the annotation service from playground to v1. ## 2022-07-07 ### Events #### Removed - End-of-life for [filter.rootAssetIds](tag/Events/operation/advancedListEvents) filtering attribute. ## 2022-06-13 ### IAM (Identity and access management) #### Added - Added the [POST /projects/{project}/sessions/revoke](tag/Sessions/operation/revokeSessions) endpoint. ## 2022-05-20 ### 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. ## 2022-05-12 ### 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. ## 2022-04-11 ### Documents #### Added - Added the [GET /documents/{documentId}/preview/image/pages/{pageNumber}](tag/Document-preview/operation/documentsPreviewImagePage) endpoint. - Added the [GET /documents/{documentId}/preview/pdf](tag/Document-preview/operation/documentsPreviewPdf) endpoint. - Added the [GET /documents/{documentId}/preview/pdf/temporarylink](tag/Document-preview/operation/documentsPreviewPdfTemporaryLink) endpoint. ## 2022-03-15 ### 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. ## 2022-03-02 ### Sequences #### Added - Added the [POST /sequences/data/latest](tag/Sequences/operation/getLatestSequenceRow) endpoint. ## 2022-02-08 ### Time series #### Changed - Marked `isStep` parameter to be editable (i.e. removed description stating it is not updatable) in [POST /timeseries/create](tag/Time-series/operation/postTimeSeries). #### Added - Added `isStep` parameter to the `TimeSeriesPatch` object used in [POST /timeseries/update](tag/Time-series/operation/alterTimeSeries) ## 2022-02-07 ### Documents #### Added - The [POST /documents/search](tag/Documents/operation/documentsSearch) endpoint now supports pagination. ## 2022-01-25 ### Documents #### Added - Added the [POST /documents/search](tag/Documents/operation/documentsSearch) endpoint. ## 2022-01-24 ### Time series #### Added - Added optional `ignoreUnknownIds` parameter to [POST /sequences/delete](tag/Sequences/operation/deleteSequences). 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. ## 2021-12-07 ### Transformations #### Added - New [Transformations](tag//Transformations) APIs to v1 to create,retrieve,list and delete transformations - New [Transformation Jobs](tag//Transformation-Jobs) APIs to v1 to retrieve and list transformation jobs or job metrics - New [Transformation Schedule](tag//Transformation-Schedules) APIs to v1 to manage schedules of transformations - New [Transformation Notifications](tag//Transformation-Notifications) APIs to v1 to manage notifications from transformation job ## 2021-11-22 ### Contextualization #### Added - Added [diagram detect](tag/Engineering-diagrams/operation/diagramDetect) endpoint to v1 to detect annotations in engineering diagrams - Added [diagram detect results](tag/Engineering-diagrams/operation/diagramDetectResults) endpoint to v1 to get the results from an engineering diagram detect job - Added [diagram convert](tag/Engineering-diagrams/operation/diagramConvert) endpoint to v1 to create interactive engineering diagrams in SVG format with highlighted annotations - Added [diagram convert results](tag/Engineering-diagrams/operation/diagramConvertResults) endpoint to v1 to get the results for a job converting engineering diagrams to SVGs ## 2021-11-17 ### 3D #### Added - Added `dataSetId` support to 3D models enabling data access scoping of 3D data ## 2021-10-13 ### Raw #### Changed - To align with Microsoft Azure clusters, table and database names are now sensitive to trailing spaces also in Google Cloud Platform clusters. ## 2021-10-05 ### Extraction Pipelines #### Added - New [Extraction Pipelines](tag//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. ## 2021-09-28 ### Sequences #### Added - Added `partition` parameter to the [GET /sequences](tag/Sequences/operation/listSequences) endpoint to support [parallel retrieval](section/Parallel-retrieval). - [POST /sequences/list](tag/Sequences/operation/advancedListSequences) now supports [parallel retrieval](section/Parallel-retrieval). ### Time series #### Added - Added `partition` parameter to the [GET /timeseries](tag/Time-series/operation/getTimeSeries) endpoint to support [parallel retrieval](section/Parallel-retrieval). ## 2021-08-18 ### IAM (Identity and access management) #### Added Added sessions to [v1](tag//Sessions). Sessions let you securely delegate access to CDF resources for CDF services (such as Functions) by an external principal and for an extended time. ## 2021-08-12 ### Relationships #### Added - Relationships now support [Parallel Retrieval](section/Parallel-retrieval) ## 2021-07-01 ### 3D #### Added - Added filter3dNodes endpoint to allow for more advanced filtering on node metadata ## 2021-06-29 ### Labels #### Added - [Dataset scoping](tag/Labels/operation/listLabels) based on `dataSetIds`. ## 2021-06-08 ### Sequences #### Added - Added [syntax for updating columns](tag/Sequences/operation/updateSequences) of existing sequences. Can `remove` columns, `modify` existing columns, and `add` new columns as well. ## 2021-06-01 ### Assets #### Added - Added labels replace (set) method for [assets update](tag/Assets/operation/updateAssets). ## 2021-04-28 ### Time series #### Changed granularity limits on hour aggreagates You can now ask for a [granularity](https://docs.cognite.com/dev/concepts/aggregation/#granularity) of up to 100000 hours (previously 48 hours), both in normal aggregates and in synthetic time series. ## 2021-04-12 ### IAM (Identity and access management) #### Added - Added a [projects list](tag/Projects/operation/listProjects) endpoint to v1 - Added a [token inspection](tag/Token/operation/inspectToken) endpoint to v1 ## 2021-04-06 ### 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](https://docs.cognite.com/cdf/access/) 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](https://docs.cognite.com/cdf/access/) 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. ## 2021-03-22 CDF API 0.5, 0.6 reached their end-of-life after its initial deprecation announcement in Summer 2019. ## 2021-03-10 ### 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`. ## 2021-02-26 ### Entity matching #### Fixed - Fixed a bug in the documentation for Entity matching. The (job) `status` shall be capitalized string. ## 2020-12-22 ### 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. ## 2020-10-20 ### 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](https://developer.cognite.com/dev/concepts/resource_types/files.html). ## 2020-08-29 ### 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. ## 2020-08-05 ### 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. ## 2020-07-08 ### 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](https://developer.cognite.com/dev/guides/iam/#application-domains). ## 2020-07-01 ### Events #### Added - New aggregation [`uniqueValues`](tag/Events/operation/aggregateEvents) allows you to find different types, subtypes of events in your project. ## 2020-06-29 ### Labels #### Added - New data organization resource: [labels](tag//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](https://developer.cognite.com/dev/concepts/resource_types/synthetic_timeseries.html). ## 2020-04-28 ### Events #### Added - New filtering capabilities to find open events [`endTime=null`](tag/Events/operation/advancedListEvents). - New filtering capabilities to find all events intersecting a timespan using [activeAtTime](tag/Events/operation/advancedListEvents). ## 2020-03-12 ### General #### Added - New data organization resource: [data sets](tag//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](tag/Files/operation/aggregateFiles). 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. ## 2020-03-10 ### 3D #### Fixed - We fixed a bug in the documentation of [3D model revisions](tag/3D-Model-Revisions/operation/get3DNodesById). Applications should anticipate that 3D nodes may not have a bounding box. ## 2020-02-25 ### Assets #### Added - We have added a new [aggregation endpoint](tag/Assets/operation/aggregateAssets) 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](tag/Events/operation/aggregateEvents) 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`. ## 2020-02-12 ### Assets #### Added - We have added new aggregation properties: `depth` and `path`. You can use the properties in the filter and retrieve endpoints. ## 2020-02-10 ### Assets #### Added - Added the property `parentExternalId` which is returned for all assets which have a parent with a defined `externalId`. ## 2019-12-09 ### 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. ## 2019-12-04 ### Assets #### Added - Added the ability to [filter](tag/Assets/operation/searchAssets) assets by parent external IDs. ## 2019-11-18 ### Events #### Added - [Added the ability to filter events by the external ID of linked assets](tag/Events/operation/advancedListEvents) ## 2019-11-12 ### Access control #### Removed - Groups can no longer be created with a permissions field in v0.5. ## 2019-10-31 ### Assets #### Added - [Asset search](/api/v1/#operation/searchAssets) 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](/api/v1/#operation/searchTimeSeries) now uses an improved search algorithm that tries a wider range of variations of the input terms, and gives much better relevancy ranking. ## 2019-10-23 ### Files #### Added - Added support for updating the `mimeType` for existing files in files/update requests. ## 2019-10-18 ### 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](/api/v1/#operation/listTimeSeries). ## 2019-10-16 ### Events #### Added - [Added the ability to sort events on startTime, endTime, createdTime, and lastUpdatedTime](tag/Events/operation/advancedListEvents) ## 2019-10-02 ### 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](https://developer.cognite.com/dev/concepts/resource_types/sequences.html). ## 2019-09-30 ### 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. ## 2019-09-23 ### Files #### Added - Added support for filter on `rootAssetIds` in files GET /files (using query parameter) and POST /files/list (in request body). ## 2019-09-16 ### Assets and Events #### Added - Added support for `partition` in `/assets` and `/events` to support parallel retrieval. See guide for usage [here](./concepts/pagination) ## 2019-08-22 ### 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. ## 2019-08-21 ### 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. ## 2019-08-15 ### 3D #### Added - Properties field for 3D nodes, extracted from uploaded 3D files. - Ability to filter nodes with a specific set of properties. ## 2019-07-24 ### 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). ## 2019-07-15 ### 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. ## 2019-07-11 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](https://developer.cognite.com/dev/concepts/external_id.html) - `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. - name: Token description: > Access tokens issued by an IdP (Azure AD, Google, etc.) are used to access CDF resources. - name: Advanced joins description: > **Note** This functionality is in alpha. Callers need to provide the `cdf-version: alpha` header to their requests. ## Concepts ### Advanced joins An **advanced join** is an abstraction for matching data entities, and enable subject-matter experts to input their knowledge into the matching process. They work natively on top of Cognite Data Fusion [data modeling](#tag/Data-modeling) capabilities. In a first iteration (Alpha version), advanced joins support finding candidates, getting input on, and populating _direct relations_ in views. ### Matches After creating the main advanced join object, the caller can input truth values by creating **matches**, which are attached to the main advanced join object. A match indicates that two data model instances should be linked, by materializing the start and end of the direct relation between the two linked instances. ### Matchers The main feature of advanced joins is to run several matching processes, and pick the best results to write back to the original data model. The matching processes are described by **matcher** objects in the API. For now, we support only [Raw](#tag/Raw) matchers: the caller can write outputs from the matching process of their choice, like [Entity Matching](#tag/Entity-matching) with different parameters. ### Jobs The API provides several capabilities once advanced joins and matches are created, like - **measuring the proportion of mapped instances** in the advanced join's view, - **estimating the quality of a matcher** using the matches (truth values) as reference, - **suggesting data quality improvements** by predicting which unmatched instances are most likely to increase data quality if matched, - **running an advanced join**, which means to populate the original instances' direct relation property with the best combination of matcher results and matches. - name: Assets description: >- 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 a part of a subsystem asset on an oil platform asset. ## Rate and concurrency limits Both the rate of requests (denoted as request per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits, it will be throttled with a `429: Too Many Requests` response. More on limit types and how to avoid being throttled is described [here](https://docs.cognite.com/dev/concepts/resource_throttling). Limits are defined at both the overall API service level, and on the API endpoints belonging to the service.\ Some types of requests consume more resources (compute, storage IO) than others, and where a service handles multiple concurrent requests with varying resource consumption. For example, ‘CRUD’ type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete) are far less resource intensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource intensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\ The version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\ These limits are subject to change, pending review of changing consumption patterns and resource availability over time: ### Translating RPS into data speed A single request may retrieve up to 1000 items. In the context of Assets, 1 item = 1 asset record\ Therefore, the maximum theoretical data speed at the top API service level is 200,000 items per second for all consumers, and 150,000 for a single identity or client in a project. ### Use of Partitions / Parallel Retrieval As a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a single request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the capacity limits defined for a given API service. For example (using the Assets API request budget): * A single request may retrieve up to 1000 items * Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints * This provides a theoretical maximum of 23,000 items read per second per identity * The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request * Therefore, it is appropriate to specify the query to retrieve a lower number of items per request, and retrieve more items in parallel, up to the theoretical maximum performance of 23,000 items per second. **Important Note:** Parallel retrieval should be only used in situations where, due to query complexity, a single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\ Parallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number of concurrent requests issued, the overall requests per second limit still applies.\ So for example, a single request returning data at approximately 18,000 items per second will only benefit from adding a second parallel request, the capacity of which goes somewhat wasted as only an additional 5,000 items per second will return before the request rate budget limit is reached. - name: Data Modeling description: > Use the Data Modeling Service to build industrial knowledge graphs. For more information, see [Data modeling](https://docs.cognite.com/cdf/dm). This page contains the specifications for the 5 core data modeling resources: - Spaces - Instances (Nodes & Edges) - Containers - Views - Data Models ### URI formats used for lineage - Space: `cdf://{cluster}/{project}/domain/{domain}/models/{space}` - Data Model: `cdf://{cluster}/{project}/domain/{domain}/models/{space}/datamodel/{externalId}/{version}` - View: `cdf://{cluster}/{project}/domain/{domain}/models/{space}/view/{externalId}/{version}` - Container: `cdf://{cluster}/{project}/domain/{domain}/models/{space}/container/{externalId}` - Node: `cdf://{cluster}/{project}/domain/{domain}/models/{space}/node/{externalId}` - Edge: `cdf://{cluster}/{project}/domain/{domain}/models/{space}/edge/{externalId}` x-uri-format-fragments: - resource: Space uri-fragment: models/{space} - resource: Data Model uri-fragment: models/{space}/datamodel/{externalId}/{version} - resource: View uri-fragment: models/{space}/view/{externalId}/{version} - resource: Container uri-fragment: models/{space}/container/{externalId} - resource: Node uri-fragment: models/{space}/node/{externalId} - resource: Edge uri-fragment: models/{space}/edge/{externalId} - name: Streams description: > Use the streams and records API to build high-volume extensions to industrial knowledge graphs that are built with [Data Modeling](https://docs.cognite.com/cdf/dm). The streams API lets you manage the streams that are used for storing records. With the API you can create, list, retrieve, and delete streams, and view stream settings and statistics. A stream defines the data lifecycle, and not schema, type or source. Multiple different sets of data which have nothing in common can be put into the same stream, provided that settings of this stream fit lifecycle and usage patterns (volume, rate, etc) of the data involved. Streams can be either mutable or immutable, which affects how records can be modified, storage capacity limits, and query performance characteristics. Mutable streams allow records to be updated and deleted by the user. They provide consistent low-latency access and optimal query performance. However, the total number of records that can be stored is limited. Mutable streams are well-suited for use cases requiring frequent data access and updates. Immutable streams do not allow records to be updated or deleted by the user, but support ingestion of very large amounts of data. Query performance may vary depending on the age of the data being accessed, as the system optimizes storage over time. To delete all data in a stream, the stream itself should be deleted. To protect against irretrievable erroneous deletion, streams are 'soft deleted' allowing them to be recovered for up to 6 weeks after the time of deletion. The template used to create the stream determines the actual recovery time. A single project has a limited number of soft deleted streams at any given time. To avoid hitting this limit, please avoid using any pattern of create and delete streams in a high frequency. Please note that we expect streams to be long lived. The exception are streams created with one of the `test` templates. Deleting a stream can take a long time. How long depends on the stream settings and the volume of data stored. While a stream is soft deleted, it is not possible to recreate a stream with the same identifier as the deleted stream. Once a stream is deleted, it does not count as one of the active streams, and more streams can be created to serve as active streams. If a stream is accidentally deleted, it is possible to recover the data by contacting [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new). You must contact Cognite no less than 1 week prior to the expiration of the stream retention period to ensure we can recover the data. ## Available stream templates **Note: Stream Templates are in Beta** The current Stream Templates are in beta. This means: - New templates may be added based on customer needs - Existing templates may be modified or removed if necessary - Such modifications will **not affect existing streams** created from these templates Choose your template carefully for production use, as templates cannot be changed after stream creation. This section lists all currently available templates that can be used for creating streams. ### Immutable streams #### ImmutableTestStream This template should be used exclusively for experimentation. It is configured for high throughput and total data volume, but has a short data retention period. Low retention in a soft-deleted state means that such streams can be quickly discarded when no longer needed or recreated to remove the experimental data. **Note:** This template should never be used for production purposes. As this template allows significant load on the system, if we detect improper usage patterns, we can change setting of streams created from this template as a last resort. - Maximum total number of records - 50 M (50,000,000) - Maximum total data volume - 50 GB - Data retention - 7 days - Maximum ingestion throughput (per 10 minutes) - 1.5 GB - Maximum reading throughput (per 10 minutes) - 1.5 GB - Maximum records ingested (per 10 minutes) - 800,000 items - Maximum unique properties with data across all records - 1000 - Maximum range filter interval for the `lastUpdatedTime` property - 7 days - Stream soft-delete retention (before hard delete) - 1 day - Maximum active streams per project - 3 #### BasicArchive This template is intended for perpetual storage of data. However, overall data volume is limited, which needs to be taken into account when planning usage. - Maximum total number of records - 50 M (50,000,000) - Maximum total data volume - 50 GB - Data retention - Unlimited (data never gets deleted) - Maximum ingestion throughput (per 10 minutes) - 170 MB - Maximum reading throughput (per 10 minutes) - 1.7 GB - Maximum records ingested (per 10 minutes) - 170,000 items - Maximum unique properties with data (across all records) - 1000 - Maximum range filter interval for the `lastUpdatedTime` property - 365 days - Stream soft-delete retention (before hard delete) - 6 weeks - Maximum active streams per project - 2 ### Mutable streams #### BasicLiveData This template is intended for production usage and offers significant data volume and throughput. - Maximum total number of records - 5 M (5,000,000) - Maximum total data volume - 15 GB - Maximum ingestion throughput (per 10 minutes) - 170 MB - Maximum reading throughput (per 10 minutes) - 500 MB - Maximum records ingested (per 10 minutes) - 170,000 items - Maximum records updated or deleted (per 10 minutes) - 85,000 items - Maximum unique properties with data (across all records) - 1000 - Stream soft-delete retention (before hard delete) - 6 weeks - Maximum active streams per project - 1 ## Rate and concurrency limits Both the rate of requests (denoted as request per second (‘**rps**’)) and the number of concurrent (parallel) requests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits, it will be throttled with a `429: Too Many Requests` response. See [Resource throttling](https://docs.cognite.com/dev/concepts/resource_throttling) for limit types and how to avoid throttling. As streams are intended to be long-lived, users are not expected to interact with these endpoints frequently. The version limits for the streams endpoints are illustrated in the tables below. These limits are subject to change, pending review of changing consumption patterns and resource availability over time:
Create and Delete request budget
Overall Per ID
Requests per second 2 1
Concurrent requests 1 1
Retrieve and List request budget
Overall Per ID
Requests per second 5 3
Concurrent requests 3 2
- name: Records description: >- Records are mutable or immutable data objects (depending on the stream template) stored in a stream. Records are created by ingesting data into a stream. Records are shaped similarly to instances in the Data Modeling service, and their schema is defined by the containers referenced as sources. Each record is associated with a space. Space-based access control applies to records. This section specifies the `records` resource and uses the following Data Modeling concepts: - [Spaces](https://docs.cognite.com/cdf/dm/dm_concepts/dm_spaces_instances#space) - [Containers](https://docs.cognite.com/cdf/dm/dm_concepts/dm_containers_views_datamodels#containers) **Note:** Every `record` has a required top-level `externalId` property, which can be used in some queries to retrieve or aggregate records (for filtering or sorting). For mutable records, `externalId` (together with `space`) uniquely identifies a record for write operations (create, upsert, delete). For immutable records, the records API does not enforce uniqueness of the `space` + `externalId` pair, so multiple records may share the same identifier. ## Rate and concurrency limits Both the rate of requests (denoted as requests per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits for all CDF API endpoints. If a request exceeds a limit, it will be throttled with a `429: Too Many Requests` response. See [Resource throttling](https://docs.cognite.com/dev/concepts/resource_throttling) for limit types and how to avoid throttling. Limits apply to the API endpoints for this service. Some request types consume more resources (compute, storage I/O) than others. For example, ingest requests are less resource-intensive than analytical requests (Aggregate, Retrieve). Limits for query endpoints (Sync, Retrieve, Aggregate) are hierarchical: - All query endpoints share a common **Query request budget** (shown in the tables below) - The Retrieve endpoint has an **additional** dedicated budget that is checked first - The Aggregate endpoint has an **additional** dedicated budget that is checked first The Sync endpoint only checks the Query request budget. The Retrieve and Aggregate endpoints must pass both their dedicated budget check AND the Query request budget check. For example, with mutable streams you can make up to 40 rps total across all query endpoints (Query budget limit), but only up to 20 of those can be Retrieve requests (Retrieve budget limit) and only up to 15 can be Aggregate requests (Aggregate budget limit). That means you could send 20 Retrieve + 15 Aggregate + 5 Sync = 40 total RPS. Query performance and rate limits vary between mutable and immutable streams because of their different storage characteristics. Mutable streams provide consistent high-performance queries and higher rate limits (see "mutable streams" limits in the tables below). Immutable streams are optimized for ingesting very large amounts of data, which results in lower query performance and stricter rate limits than mutable streams (see "immutable streams" limits in the tables below). When designing data access patterns, use mutable streams for high-performance queries and higher rate limits, or immutable streams when the priority is high-volume ingestion and long-term storage. The amount of data returned in responses from query endpoints (Sync, Retrieve, Aggregate) is also limited. Prefer reading only the data you need: use an appropriate `filter` and limit which `sources` are retrieved, rather than retrieving large result sets that you will not use. The version limits for the records endpoints are shown in the tables below. These limits are subject to change, pending review of consumption patterns and resource availability over time:
Ingest request budget
Overall Per ID
Requests per second 40 30
Concurrent requests 20 15
Query request budget
Overall Per ID
Requests per second: mutable streams 40 30
Concurrent requests: mutable streams 30 22
Requests per second: immutable streams 10 7
Concurrent requests: immutable streams 10 7
Response MB per second 4 3

Additional dedicated budgets for Retrieve and Aggregate endpoints:

The Retrieve and Aggregate endpoints have dedicated budgets that are checked in addition to the Query request budget shown above. A request to these endpoints must pass both budget checks.

Retrieve request budget
Overall Per ID
Requests per second: mutable streams 20 15
Concurrent requests: mutable streams 20 15
Requests per second: immutable streams 10 7
Concurrent requests: immutable streams 10 7

Note: Retrieve endpoint requests are checked against both this budget and the Query request budget above.

Aggregate request budget
Overall Per ID
Requests per second: mutable streams 15 12
Concurrent requests: mutable streams 10 7
Requests per second: immutable streams 5 4
Concurrent requests: immutable streams 5 4

Note: Aggregate endpoint requests are checked against both this budget and the Query request budget above.

Summary:

- name: Events description: >- Events objects store complex information about multiple assets over a time period. Typical types of events that would be stored in this service might include Alarms, Process Data, and Logs.\ For the storage of low volume, manually generated, schedulable activities (such as maintenance schedules, work orders or other ‘appointment’ type activities, the Data Modeling service is now recommended. #### Important Note: Events and Time Series are somewhat closely related in that both are high volume types of data, capable of recording data in microsecond resolutions. However, Events is not recommended as a Time Series store, such as where the data flow is from a single instance of sensors (i.e. temperature, pressure, voltage), simulators or state machines (on, off, disconnected, etc).\ Time Series offers very low latency read and write performance, as well as specialised filters and aggregations that are tailored to the analysis of time series data. 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.\ When storing event information in metadata, it should be considered that all data is stored as string format. #### Note: In Events API, timestamps are treated as strings when added to metadata fields and aren’t converted to the user’s local time zone. **Caveats:**\ Due to the eventually consistent nature of Asset IDs stored in Events, it should be noted that Asset ID references obtained from the Events API may occasionally be invalid (such as if an Asset ID is deleted, but the reference to that ID remains in the Event record for a time). 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. ## Rate and concurrency limits Both the rate of requests (denoted as request per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits, it will be throttled with a `429: Too Many Requests` response. More on limit types and how to avoid being throttled is described [here](https://docs.cognite.com/dev/concepts/resource_throttling). Limits are defined at both the overall API service level, and on the API endpoints belonging to the service.\ Some types of requests consume more resources (compute, storage IO) than others, and where a service handles multiple concurrent requests with varying resource consumption. For example, ‘CRUD’ type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete) are far less resource intensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource intensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\ The version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\ These limits are subject to change, pending review of changing consumption patterns and resource availability over time: ### Translating RPS into data speed A single request may retrieve up to 1000 items. In the context of Events, 1 item = 1 event record\ Therefore, the maximum theoretical data speed at the top API service level is 200,000 items per second for all consumers, and 150,000 for a single identity or client in a project. ### Use of Partitions / Parallel Retrieval As a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a single request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the capacity limits defined for a given API service. For example (using the Events API request budget): * A single request may retrieve up to 1000 items * Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints * This provides a theoretical maximum of 23,000 items read per second per identity * The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request * Therefore, it is appropriate to specify the query to retrieve a lower number of items per request, and retrieve more items in parallel, up to the theoretical maximum performance of 23,000 items per second. **Important Note:** Parallel retrieval should be only used in situations where, due to query complexity, a single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\ Parallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number of concurrent requests issued, the overall requests per second limit still applies.\ So for example, a single request returning data at approximately 18,000 items per second will only benefit from adding a second parallel request, the capacity of which goes somewhat wasted as only an additional 5,000 items per second will return before the request rate budget limit is reached. - name: Files description: >- 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. ## Rate and concurrency limits Both the rate of requests (denoted as request per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits, it will be throttled with a `429: Too Many Requests` response. More on limit types and how to avoid being throttled is described [here](https://docs.cognite.com/dev/concepts/resource_throttling). Limits are defined at both the overall API service level, and on the API endpoints belonging to the service. Some types of requests consume more resources (compute, storage IO) than others, and where a service handles multiple concurrent requests with varying resource consumption. For example, ‘CRUD’ type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete and similar) are far less resource intensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource intensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget. The version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below. These limits are subject to change, pending review of changing consumption patterns and resource availability over time: ### Translating RPS into data speed A single request may retrieve up to 1000 items. In the context of Files, 1 item = 1 file record Therefore, the maximum theoretical data speed at the top API service level is 160,000 items per second for all consumers, and 120,000 for a single identity or client in a project. ### Use of Partitions / Parallel Retrieval As a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a single request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the capacity limits defined for a given API service. For example (using the Files API request budget): * A single request may retrieve up to 1000 items * Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints * This provides a theoretical maximum of 23,000 items read per second per identity * The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request * Therefore, it is appropriate to specify the query to retrieve a lower number of items per request, and retrieve more items in parallel, up to the theoretical maximum performance of 23,000 items per second. **Important Note:** Parallel retrieval should be only used in situations where, due to query complexity, a single request flow provides data retrieval speeds that are significantly less than the theoretical maximum. Parallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number of concurrent requests issued, the overall requests per second limit still applies. So for example, a single request returning data at approximately 18,000 items per second will only benefit from adding a second parallel request, the capacity of which goes somewhat wasted as only an additional 5,000 items per second will return before the request rate budget limit is reached. - name: Functions description: >- Functions enables Python code to be hosted and executed in the cloud, on demand or by using a schedule. Execution, status and logs are available through the API. A function is uploaded to the Files API as a zip file with at least a Python file called `handler.py` (unless specified otherwise through the `functionPath`-argument) that must contain a function named `handle` with any of the following arguments: `data`, `client`, `secrets`, or 'function_call_info', which are passed into the function. The latest version of Cognite SDK's are available, and additional python packages and version specifications can be defined in a `requirements.txt` in the root of the zip. - name: Function calls description: >- Function calls let you execute functions asynchronously with a timeout of 15 minutes. - name: Function schedules description: >- Function schedules allow you to run functions with a specific input at intervals defined by a cron expression. These function calls will be asynchronous and show up in the function call list. Visit http://www.cronmaker.com to generate a cron expression with a UI. - name: Function Apps description: | > **Private Beta:** This API is currently in private beta and available to > select customers. To request access, please reach out to your Cognite > contact or [Cognite Support](https://support.cognite.com/). Core operations for listing and retrieving Function Apps. - name: Function App Calls description: > > **Private Beta:** This API is currently in private beta and available to > select customers. To request access, please reach out to your Cognite > contact or [Cognite Support](https://support.cognite.com/). Invoke Function App endpoints and view call history, responses, and logs. All function invocations go through `POST /calls` with a `FunctionAppCallRequest` envelope containing the target path, HTTP method, body, and session nonce. - name: Function App MCP description: > > **Private Beta:** This API is currently in private beta and available to > select customers. To request access, please reach out to your Cognite > contact or [Cognite Support](https://support.cognite.com/). [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoints for AI agent integration. Implements the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) with [JSON-RPC 2.0](https://www.jsonrpc.org/specification) messaging and SSE streaming. Nonce is passed per-call inside `params._meta["com.cognite/nonce"]` for methods that invoke the function (tools/list, tools/call, ping). - name: 3D description: >- The CDF 3D API organizes 3D data into models and revisions. A model is just a container for a set of revisions. Revisions contains the actual 3D data. For example you can have a model named `Compressor` and you can upload a revision under that model. When you create a revision you need to attach a file, which may be in 3D CAD or Point cloud format. For every new version of the 3D model you upload a new revision under the model. You can then easily track the history of a model by browsing the different revisions. When you upload a new revision the 3D API needs to process the 3D data to optimize it for rendering. This can take some time. The Get3D api get revision endpoint provides a status string in the revision object. You can then follow the process while you wait. A 3D CAD model is typically built up by a hierarchical structure. This is related to the layout of the asset hierarchy in the Cognite Asset API. The 3D API provides endpoints to extract the nodes from the 3D node hierarchy, and endpoints to make mappings from the 3D nodeIds to assetIds in the asset hierarchy. The nodes are assigned an ID, nodeId, based on the node name and hierarchy. Each node in the 3D hierarchy gets a unique ID. This is the ID representing the object in the viewer. When a user click on a object in the 3D viewer it can returns the ID for the object that was clicked. You can then use that ID to look up which node in the hierarchy the user clicked on. Cognite also provides a [web based 3D viewer](https://www.npmjs.com/package/@cognite/reveal) to embed the processed 3D model in your own web page app. - name: Time series description: >- 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 numbers 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, can't 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 linearly changes between the two measurements. The `isStep` flag controls this 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 (`isStep`) or close to the mean of the two (not `isStep`). 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:00.000, January 1st, 1970. The time series service accepts timestamps in the range from 00:00:00.000, January 1st, 1900 through 23:59:59.999, December 31st, 2099 (in other words, every millisecond in the two centuries from 1900 to but not including 2100). Negative timestamps are used to define dates before 1970. Milliseconds is the finest time resolution supported by CDF, i.e., fractional milliseconds are not supported. Leap seconds are not counted. Numerical data points can be aggregated before they are retrieved from CDF. This allows for faster queries by reducing the amount of data transferred. You can aggregate data points by specifying one or more aggregates (e.g., average, minimum, maximum) as well as the time granularity over which the aggregates should be applied (e.g., “1h” for one hour). Aggregates are aligned to the start time modulo the granularity unit. For example, if you ask for daily average temperatures since Monday afternoon last week, the first aggregated data point will contain averages for Monday, the second for Tuesday, etc. Determining aggregate alignment without considering data point timestamps allows CDF to pre-calculate aggregates (e.g., to quickly return daily average temperatures for a year). Consequently, aggregating over 60 minutes can return a different result than 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 eventually consistent manner. - name: Data point subscriptions description: >- A data point subscription is a way to listen to changes to time series data points, in ingestion order. A single subscription can listen to many time series, and a time series can be part of many subscriptions. You listen to subscriptions by calling the “list subscription data“ endpoint. It will return a list of data point upserts and deleted ranges, together with a cursor to retrieve the next batch of updates. Updates written since the creation of the subscription, up to 7 days ago, can be retrieved through the subscription. Subscriptions can be defined explicitly through a list of time series external ids and instance ids, or implicitly through a filter. The filter is a subset of the advanced filter query in the regular “time series search“ endpoint. Partitions: Subscriptions can be further divided into a number of partitions, for the purpose of fetching subscription data in parallel. Each partition will return data in ingestion order, but the order between partitions is not guaranteed. Limitations: - Each subscription can have at most 10000 time series. - A time series can be part of at most 10 subscriptions. - A project can have at most 1000 subscriptions, of which 100 are filter subscriptions. - Time series with security categories can not be shown in filter subscriptions. - Time series with neither external id nor instance id cannot be added to non-filter subscriptions. - The number of partitions cannot be changed after creation. Access control: You need READ access to subscriptions ACL to read/list subscriptions or list data, and you need WRITE access to create/update/delete subscriptions. Furthermore, you need READ access to the time series you want to get updates from. For filter subscriptions, you either need READ access to all time series, or the filter must be restricted according to your access rights (e.g. by filtering on specific data set IDs). Subscriptions can have data sets that allow for more granular access control. The data set on a subscription does not influence the data stream, but allows you to restrict who can read/update the subscription. Name of ACL: `timeSeriesSubscriptionsAcl` Supported actions: - `READ` - `WRITE` Example capabilities: ``` [ {"timeSeriesAcl":{"actions":["READ"], "scope":{"all":{}}}}, {"timeSeriesSubscriptionsAcl":{"actions":["WRITE", "READ"], "scope":{"all":{}}}} ] ``` - name: Synthetic Time Series description: >- 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'} / TS{space='data modeling space', externalId='dm id'}`. * Functions of time series `sin(pow(TS{id=123}, 2))`. * Aggregations of time series `TS{id=123, aggregate='average', granularity='1h'}+TS{id=456}` * Convert time series with `unitExternalId` to another unit `TS{externalId='temp_c', targetUnit='temperature:deg_f'}`. To learn more about synthetic time series please follow [our guide](https://docs.cognite.com/dev/concepts/resource_types/synthetic_timeseries). - name: Raw description: > 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.\ ### Request and concurrency limits Both the rate of requests and the number of concurrent (parallel) requests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits, it will be throttled with a `429: Too Many Requests` response. More on limit types and how to avoid being throttled is described [here](https://docs.cognite.com/dev/concepts/resource_throttling). The limits for the Raw service are described in the table below. Note that under high load, some deviation from the limits might occur for short periods of time as the service is scaling up. The `/rows` endpoints for inserting and retrieving data are governed by specific data rate limits. | Limit | Per project | Per user (identity) | |-----------------------|-----------------------|---------------------| | Concurrency | 64 parallel requests | 48 parallel requests| | Data rate (retrieve) | 8.3 GB / 10 minutes | 6.6 GB / 10 minutes | | Data rate (insert) | 1.6 GB / 10 minutes | 1.3 GB / 10 minutes | ### URI formats used for lineage - Database: `cdf://{cluster}/{project}/domain/{domain}/raw/{dbName}` - Table: `cdf://{cluster}/{project}/domain/{domain}/raw/{dbName}/{tableName}` x-uri-format-fragments: - resource: Database uri-fragment: raw/{dbName} - resource: Table uri-fragment: raw/{dbName}/{tableName} - name: Groups description: > Groups are used to give principals 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. Groups can either be managed through the external identity provider for the project or managed by CDF. - **Group Membership Managed Externally**: Groups membership is managed by the external identity provider. It is not possible edit or see the members of these groups in CDF. - **Group Membership Managed within CDF**: Lets you see and edit group membership in CDF instead of relying on the external identity provider. - name: Projects description: > 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. - name: Security categories description: > 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](https://docs.cognite.com/api-reference/concepts/20230101/security-categories). - name: Data sets description: >- 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](https://docs.cognite.com/cdf/data_governance/concepts/datasets/) - name: Limits description: Limits Service Endpoints to provide limit values for a project. - name: Metering description: Metering Service Endpoints to provide consumption data for a project. - name: Sequences description: > A sequence stores a table with up to 400 columns indexed by row number. There can be at most 400 numeric columns and 200 string columns. Each of the columns has a pre-defined type: 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) pairs in the rows directly. Other potential applications include data logs in which the index isn't time-based. To learn more about sequences, see the [concept guide](https://docs.cognite.com/dev/concepts/resource_types/sequences). - name: Labels - name: Relationships description: >- 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. - name: Entity matching description: >- 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. - name: Entity matching pipelines description: >- **Note** This functionality is in beta. Callers need to provide the `cdf-version: beta` header to their requests. Using Entity matching pipelines, you can configure re-runnable executions of entity matching. Pipelines support expert knowledge (confirmed and/or rejected matches), regex rules (match rules), and entity matching models. - name: Diagram parsing description: A collection of Diagram Parsing API services in Cognite Data Fusion (CDF). - name: Vision description: >- Vision API is deprecated. See [Deprecated and retired features](https://docs.cognite.com/cdf/deprecated) for details and timelines. The Vision contextualization endpoints enable extraction of information from imagery data based on their visual content. For example, you can detect external ID or name of assets, detect and read value of gauges or identify common industrial objects in images. This service has support for batch processing which enables processing of multiple image files via an asynchronous prediction request. A new contextualization job is triggered by sending a POST request to the service. The response of the POST request contains a job ID, which can then be used to make subsequent calls to check the status and retrieve the results of the job once it is completed. - description: >- Atlas AI agents use language models to solve specific industrial business needs, such as providing insights into historical and planned maintenance and analyzing time series data for root cause analysis. An agent includes prompts with instructions, industry-relevant tools, and access to industrial data stored in the Cognite Data Fusion (CDF) knowledge graph. A project can have a maximum of 30 agents. Each agent can have a maximum of 10 tools. For more information about Atlas AI agents, see the [Atlas AI documentation](https://docs.cognite.com/cdf/atlas_ai/concepts/). name: Agents - description: >- Skills are reusable instruction sets that can be shared across Atlas AI agents. Agents only load skills as needed to reduce initial context window bloat. name: Skills - description: >- Project-scoped Atlas settings, including the default orchestrator agent for incoming operator queries. name: Project Configuration - description: >- List language models available in your CDF project. Compatible with the OpenAI Models API specifications. Connect any OpenAI compatible client or SDK by pointing it to the Cognite API endpoint. name: Models - description: >- Generates chat completions using language models available in your CDF project. Compatible with the OpenAI Chat Completions API specifications. Connect any OpenAI compatible client or SDK by pointing it to the Cognite API endpoint. Feature support and model availability vary by model and project. **Rate limiting**: Requests are subject to rate limits. When a limit is exceeded, the API returns an HTTP `429 Too Many Requests` error. Retry requests using an exponential backoff strategy with jitter. name: Chat Completions - description: A collection of AI API services in CDF. name: Cognite AI - name: Documents description: >- A document is a file that has been indexed by the document search engine. Every time a file is uploaded, updated or deleted in the Files API, it will also be scheduled for processing by the document search engine. After some processing, it will be possible to search for the file in the document search API. The document search engine is able to extract content from a variety of document types, and perform classification, contextualization and other operations on the file. This extracted and derived information is made available in the form of a `Document` object. The document structure consists of a selection of derived fields, such as the `title`, `author` and `language` of the document, plus some of the original fields from the raw file. The fields from the raw file can be found in the `sourceFile` structure. The derived fields are described in more detail below. ### Derived fields #### title Some document types (such as PDFs) contain additional metadata fields. If the document contains its title as part of this metadata, this field will be populated with that title. Note that we do not currently extract the title from the document content itself. If there is a need for this, we may consider adding such functionality in the future. #### author Similar to the `title` field, the author field is another field that can often be extracted from the document's metadata. #### producer The `producer` field also exists in the document metadata. It contains information about the software or the system that was used to create the document. #### createdTime The `createdTime` we assign to the document is not exactly the same as the one found in the Files API. We first try to extract the created time from the document metadata. If the document does not contain such a timestamp, we fall back to the time set in the Files API. #### mimeType If there is a mime type set in on the file in the Files API, this field will be set to the same mime type. If there is no mime type set on the file, we will try to auto-detect it. #### extension This field contains the extension of the file, derived from the file name. For instance, if the file name is `My Document.docx`, the `extension` field will contain `docx`. #### pageCount Contains the number of pages in the document, if possible to determine. #### type The `type` field contains a high level file type, derived from the mime type. Mime types are not that pleasant to look at, and not always easy to understand. That is why we map the mime types into more user-friendly types. Below is the list of types currently returned, but be aware that this list may be extended in the future. - `Document`: Document files from Microsoft Word or similar word processing software. - `PDF`: PDF files. - `Spreadsheet`: Files from Microsoft Excel or similar spreadsheet software. - `Presentation`: Slides from Microsoft Powerpoint or similar. - `Image`: Any kind of image such as PNG or JPG files. - `Video`: Any kind of video such as MOV or MP4 files. - `Tabular data`: Csv, tsv and other kinds of tabular data files. - `Plain text`: Plain text files. - `Compressed`: ZIP files and other kinds of compressed archive files. - `Script`: Program code such as python or matlab. - `Other`: Anything that doesn't fit in any of the above types. #### geoLocation If there is a geolocation set on the file in the Files API, then this field will contain the same geolocation. If there is no explicitly assigned geolocation, the document processing system will try to detect a location using two different techniques; 1. We will extract locations from files that contain embedded GPS locations. Photos and videos often have this kind of metadata. 2. We will look at related assets that have locations, and assign the same location(s) to the document. ### File type support We create a document for each uploaded file, but only derive data from certain files. The following file types are eligible for further data extraction & enrichment: - PDF files - Spreadsheets, documents, and presentations from the Microsoft, Libre Office and macOS office suites - Plain text files - Images - name: Document preview x-displayName: Preview description: >- The document preview service is a utility API that can render most document types as an image or PDF. This can be very helpful if you want to display a preview of a file in a frontend, or for other tasks that require one of these formats. For both rendered formats there is a concept of a page. The actual meaning of a page depends on the source document. E.g. an image will always have exactly one page, while a spreadsheet will typically have one page representing each individual sheet. The document preview service can only generate preview for document sizes that do not exceed 150 MiB. Trying to preview a larger document will give an error. ### File type support Previews can be created for the following types of files: - PDF files - Spreadsheets, documents and presentations from the Microsoft and Libre Office office suites - Images - name: Geospatial description: >- The Geospatial API allows to model a problem domain when data has a geometric or geographic nature. The geospatial data is organized in feature types that are homogeneous collections of features (geospatial items), each having the same spatial representation, such as points, lines, or polygons, and a common set of typed properties. The Geospatial API is aware of Coordinate Reference Systems, and allows transformations. To learn more about geospatial concepts, see the [concept guide](https://developer.cognite.com/dev/concepts/resource_types/geospatial.html). - name: SessionsInternal - name: Sessions description: > Sessions are used to maintain access to CDF resources for an extended period of time. The methods available to extend a sessions lifetime are client credentials and token exchange. Sessions depend on the project OIDC configuration and may become invalid in the following cases - Project OIDC configuration has been updated through the [update project](#operation/updateProject) endpoint. This action invalidates all of the project's sessions. - The session was invalidated through the identity provider. - name: Extraction Pipelines description: >- Extraction Pipeline objects represent the applications and software that are deployed to ingest operational data into CDF. An extraction pipeline can consist of a number of different software components between the source system and CDF. The extraction pipeline object represents the software component that actually sends the data to CDF. Two examples are Cognite extractors and third party ETL tools such as Microsoft Azure or Informatica PowerCenter - name: Extraction Pipelines Runs description: >- Extraction Pipelines Runs are CDF objects to store statuses related to an extraction pipeline. The supported statuses are: success, failure and seen. The statuses are related to two different types of operation of the extraction pipeline. Success and failure indicate the status for a particular EP run where the EP attempts to send data to CDF. If the data is successfully posted to CDF the status of the run is ‘success’; if the run has been unsuccessful and the data is not posted to CDF, the status of the run is ‘failure’. Message can be stored to explain run status. Seen is a heartbeat status that indicates that the extraction pipeline is alive. This message is sent periodically on a schedule and indicates that the extraction pipeline is working even though data may not have been sent to CDF by the extraction pipeline. - name: Extraction Pipelines Config description: >- Extraction Pipelines Configs are configuration file revisions tied to an extraction pipeline. Users can create new configuration revisions, and extractors can fetch the latest, making it easy to deploy configuration files from source control, automated scripts, etc. - name: Extractors description: >- Extractors are tools used to move data from various source systems to CDF. The extractors API is used to manage extractor releases, give access to downloads, and contextualize which source systems each extractor is used to access. Each extractor has a list of releases, and each release may have a list of artifacts which are things like documentation PDFs, executables, and installers. Extractors may also be tied to source systems through solutions, representing concrete sources each extractor may connect to. The extractors API is currently read-only. In the future it may be possible to define per-project extractors. Because of this, cognite-maintained extractors and source systems currently have their external ID prefixed by `cognite-`. - name: Transformations description: >- Transformations enable users to use Spark SQL queries to transform data from the CDF staging area, RAW, into the CDF data model. ### Concurrency limits The number of concurrent (parallel) jobs are governed by limits. If a request exceeds one of the limits, the job fails to run. This limitation also applies to scheduled transformations. The limits for the transformation service are described in the table below. Note that under high load, some deviation from the limits might occur for short periods as the service scales up. | Limit | Per project | |-----------------------|-----------------------| | Concurrency | 10 parallel jobs | - name: Transformation Jobs description: >- Transformation jobs let you list jobs and their metrics. A maximum of 1000 jobs per transformation are retained, provided they are not older than 90 days. - name: Transformation Schedules description: >- Transformation schedules allow you to run transformations with a specific input at intervals defined by a cron expression. These transformation jobs will be asynchronous and show up in the transformation job list. Visit http://www.cronmaker.com to generate a cron expression with a UI. - name: Transformation Notifications description: >- Transformation notifications let users know when a job fails if subscribed. - name: Query description: Query lets the users preview the result of their queries. - name: Schema description: Schema provides the expected schema for CDF resources. - name: Annotations description: >- Annotations reflect contextual information in base CDF resource types, such as Files and Time series, that are not present on the object itself. The benefits of the annotations concept are threefold: - The annotations concept is a good fit for enriching the base resources themselves, so that the overall data quality is higher in a given project. - It is also a good fit for building reference datasets for data problems uniformly across customer projects. Product teams can then use those reference datasets to train machine learning models or validate the performance of their algorithms on actual customer data. - Given a uniform way of labelling similar concepts across projects, it becomes easy for apps to agree on a consistent visual representation of those concepts. - name: User profiles description: > User profiles is an authoritative source of core user profile information (email, name, job title, etc.) for principals based on data from the identity provider configured for the CDF project. User profiles are first created (usually within a few seconds) when a principal issues a request against a CDF API. We currently don't support automatic exchange of user identity information between the identity provider and CDF, but the profile data is updated regularly with the latest data from the identity provider for the principals issuing requests against a CDF API. Note: - Do not use other fields than `userIdentifier` (e.g. email) to uniquely identify a principal. User profile data is mutable and is not guaranteed to be stable or unique (except `userIdentifier`). - Do not use user profile data for authentication or authorization purposes. It is not guaranteed to be under the strict governance necessary for that. For example, one should not use email address as proof of identity or job title to give access to resources. - We strongly recommend _against_ storing any user profile data. It is intended for display purposes only and may update at any time. Clients should fetch user profile data at demand, and optionally cache for performance reasons. - name: Workflows description: >- Define and orchestrate data workflows consisting of CDF Transformations, Cognite Functions, and other processes. This service enables you to build data pipelines and business solutions leveraging the capabilities of CDF and external tools.

All API and service limitations are listed here. - name: Workflow versions - name: Workflow executions - name: Tasks - name: Workflow triggers description: >- Triggers allow you to automate the execution of your data workflows based on specific conditions, such as scheduled times (defined by cron expressions). - name: Data aware description: Endpoints for data aware workflow features. - name: Sources description: >- A hosted extractor **source** represents an external source system on the internet. The **source** resource in CDF contains all the information the extractor needs to connect to the external source system. A source can have many jobs, each streaming different data from the source system. - name: Jobs description: >- A hosted extractor **job** represents the running extractor. Jobs produce logs and metrics that give the state of the job. For details on available states and metrics see documentation [here](https://docs.cognite.com/cdf/integration/guides/extraction/hosted_extractors). - name: Destinations description: >- A hosted extractor writes to a **destination**. The destination contains credentials for CDF, and additional information about where the data should land, such as data set ID. Multiple jobs can share a single destination, in which case requests will be combined, reducing the number of requests made to CDF APIs. Metrics are still reported for each individual job. - name: Mappings description: >- A **mapping** is a custom transformation, translating the source format to a format that can be ingested into CDF. Mappings are written in the Cognite transformation language. For more details see documentation [here](https://docs.cognite.com/cdf/integration/guides/extraction/hosted_extractors/hosted_extractors_custom_mappings). - name: Previews description: >- A **preview** is a temporary job that runs until it times out, fails, or receives a single message, then stores the result. This is useful for development, as it allows you to easily inspect the output of a source. Previews require a source, but not a mapping or a destination. This API is in alpha. The endpoints listed here are available only when the `cdf-version` header with the value `alpha` is provided. - name: Postgres Gateway Users description: > A postgres gateway **user** (also a typical postgres user) owns the foreign tables (built in or custom). The created postgres user only has access to use foreign tables and cannot directly create tables users. To create foreign tables use the Postgres Gateway Tables APIs - name: Postgres Gateway Tables description: View and create foreign **tables** for a given **user** - name: SAP Instances description: >- An SAP **instance** represents a configuration to an external SAP S/4HANA destination system. The **instance** resource contains all the information this API service needs to connect to an SAP S/4HANA destination. Supported SAP S/4HANA versions: * SAP S/4HANA OnPremise 2021 FPS01, and later * SAP S/4HANA Cloud - name: SAP Endpoints description: >- An SAP **endpoint** represents a configuration to an SAP S/4HANA OData endpoint (and its related OData entity) the API will send the writeback requests. It defines which SAP Instance destination and which schema mapping should be used when processing a writeback request. Supported SAP entities: * [Maintenance Notifications](https://api.sap.com/api/OP_API_MAINTNOTIFICATION/overview) * [Attachments](https://api.sap.com/api/OP_API_CV_ATTACHMENT_SRV_0001/overview) - name: Schema Mappings description: >- A **mapping** uses field and value mapping(s) to perform an in-flight transformation from source CDF entities to SAP S/4HANA entities. Mappings are written in the Cognite transformation language. For more details see the [documentation](https://docs.cognite.com/cdf/integration/guides/extraction/hosted_extractors/hosted_extractors_custom_mappings). - name: Writeback Requests description: >- A writeback **request** to the SAP S/4HANA destination. The request body contains the target SAP endpoint destination, and the payload to send. - name: Simulators description: > The simulator resource contains the definitions necessary for Cognite Data Fusion (CDF) to interact with a given simulator. It serves as a central contract that allows APIs, UIs, and integrations (connectors) to utilize the same definitions when dealing with a specific simulator. Each simulator is uniquely identified and can be associated with various file extension types, model types, step fields, and unit quantities. Simulators are essential for managing data flows between CDF and external simulation tools, ensuring consistency and reliability in data handling. #### Limitations: - A project can have a maximum of 100 simulators - name: Simulator Integrations description: > The simulator integration resource represents a simulator connector in Cognite Data Fusion (CDF). It provides information about the configured connectors for a given simulator, including their status and additional details such as dataset, name, license status, connector version, simulator version, and more. This resource is essential for monitoring and managing the interactions between CDF and external simulators, ensuring proper data flow and integration. #### Limitations: - A project can have a maximum of 20 simulator integrations - name: Simulator Routines description: > The simulator routine resource defines instructions on interacting with a simulator model. A simulator routine includes: - Inputs (values set into the simulator model) - Commands (actions to be performed by the simulator) - Outputs (values read from the simulator model) Simulator routines can have multiple revisions, enabling users to track changes and evolve the routine over time. Each model can have multiple routines, each performing different objectives such as calculating optimal operation setpoints, forecasting production, benchmarking asset performance, and more. #### Limitations: - A project can have a maximum of 10000 simulator routines. - Each simulator model can have a maximum of 10 simulator routines. - Each simulator routine can have a maximum of 10 revisions. - The total size of each routine revision can be a maximum of 50.00 KB. - name: Simulator Models description: > The simulator model resource represents an asset modeled in a simulator. This asset could range from a pump or well to a complete processing facility or refinery. The simulator model is the root of its associated revisions, routines, runs, and results. The dataset assigned to a model is inherited by its children. Deleting a model also deletes all its children, thereby maintaining the integrity and hierarchy of the simulation data. Simulator model revisions track changes and updates to a simulator model over time. Each revision ensures that modifications to models are traceable and allows users to understand the evolution of a given model. #### Limitations: - A project can have a maximum of 1000 simulator models. - Each simulator model can have a maximum of 200 revisions. - name: Simulation Runs description: > Every time a simulation routine executes, a simulation run object is created. This object ensures that each execution of a routine is documented and traceable. Each run has an associated simulation data resource, which stores the inputs and outputs of a simulation run, capturing the values set into and read from the simulator model to ensure the traceability and integrity of the simulation data. Simulation runs provide a historical record of the simulations performed, allowing users to analyze and compare different runs, track changes over time, and make informed decisions based on the simulation results. When simulation run load balancing is enabled and the routine is not assigned to any particular simulator integration, the run initiates with status `queued` and any active simulator integration can claim it automatically. Without load balancing, the run initiates with status `ready` and is tied to the simulator integration specified on the routine. #### Limitations: - A retention policy is in place for simulation runs, allowing up to 100000 entries. When this limit is reached, the oldest runs are deleted to make room for new ones. - The total size of all inputs for a simulation run can be a maximum of 50.00 KB. - The total size of simulation run data sent by the connector can be a maximum of 100.00 KB. - name: Simulator Logs description: > Simulator logs track what happens during simulation runs, model parsing, and generic connector logic. They provide valuable information for monitoring, debugging, and auditing. Simulator logs capture important events, messages, and exceptions that occur during the execution of simulations, model parsing, and connector operations. They help users identify issues, diagnose problems, and gain insights into the behavior of the simulator integrations. #### Limitations: - A retention policy allows up to 10000 log entries per logId. When this limit is reached, the oldest logs are deleted to make room for new ones. - name: Units description: >- Units Catalog API provides a standardized list of units that can be used in Cognite Data Fusion. The content this API serves is based on the [CDF Units Catalog](https://github.com/cognitedata/units-catalog) - name: Unit Systems description: >- Unit system is a collection of default units for different quantities. This API provides a list of supported unit systems and their associated quantities and respective unit. - name: Application Data Storage description: '' - name: Location Filters description: '' - name: User Preferences description: '' - name: User History description: '' - name: Search Config description: '' - name: Organizations description: > 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. - name: Integrations description: Each integration represents an application running on-premises. - name: Principals description: > **Principal** is an umbrella term for **user accounts** and **service accounts**. Both entities can be uniquely identified, authenticated, and authorized in CDF. Principals are unique within an organization, and therefore also within a project in the organization. Principals can access data and create and run processes (transformations, Functions) in a CDF project. * A **user account** is associated with a **person** who wants to interact with CDF. Each user account has a user profile containing a unique user ID. * A **service account** is associated with an **application** or **process** that wants to interact with CDF, such as an extractor or Cognite Functions, rather than a person. ## Authentication for this API Requests to the Principals API are directed to `auth.cognite.com`, like for organizations. Only OAuth tokens issued by `https://auth.cognite.com` (such as the ones issued when logging into Fusion) are accepted by the Principals 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. ## User Accounts The Principals API lets you query user accounts in an organization, and retrieve profiles. - name: Signals description: >- A signal is a notification that something has occurred in a CDF process. Users and systems may listen to signals by creating a sink and attaching subscriptions with a filter that matches the signals they are interested in. Subscriptions tie sinks to topics. Each topic represents some CDF resource like integrations or workflows. When a signal is emitted for a resource, all subscriptions for that resource's topic are evaluated. If the signal matches the subscription filter, it is pushed to the the sink. - name: Data products description: > Data products are governed, ready-for-consumption data assets derived from data domains, following data mesh principles. **Key characteristics:** - **Clear ownership**: Defined data product owners with explicit access roles and accountability - **Rich metadata**: Comprehensive data modeling views, usage terms, access permissions, and descriptive documentation - **Self-service consumption**: Discoverable and well-documented for autonomous data consumer access - **Version management**: Immutable data modeling view versions with governed schemas and updatable metadata Data products act as a governance layer around data modeling, establishing trust and reliability for business decisions through clear ownership, comprehensive metadata, and standardized access patterns. **Space ownership**: A data product owns a schema space. The data modeling views that the data product governs live in that schema space. The schema space is exclusively owned by the data product. paths: /simulators/models/aggregate: post: tags: - Simulator Models summary: Aggregate Simulator Models description: >- Calculate aggregates for simulator models, considering the optional filter specification. operationId: aggregate_simulator_models requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AggregateSimulatorModelsQuery' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListAggregateCount' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorBase' description: Bad Request '403': content: application/json: schema: $ref: '#/components/schemas/ErrorBase' description: Forbidden '500': content: application/json: schema: $ref: '#/components/schemas/ErrorBase' description: Internal Server Error components: schemas: AggregateSimulatorModelsQuery: properties: filter: $ref: '#/components/schemas/ListSimulatorModelsFilters' aggregate: type: string const: count title: Aggregate description: Aggregate type enum: - count additionalProperties: false type: object required: - aggregate title: AggregateSimulatorModelsQuery ListAggregateCount: properties: items: items: $ref: '#/components/schemas/AggregateCount' type: array title: Items additionalProperties: false type: object required: - items title: ListAggregateCount ErrorBase: properties: error: $ref: '#/components/schemas/APIError' type: object required: - error title: ErrorBase ListSimulatorModelsFilters: properties: simulatorExternalIds: title: SimulatorExternalIds description: Filter by simulator external ids examples: - - PROSPER items: type: string type: array maxItems: 100 minItems: 1 externalIdPrefix: title: ExternalIdPrefix description: Filter by prefix on simulator model external ids type: string maxLength: 255 minLength: 1 dataSetIds: title: DataSetIds description: Filter by data set IDs items: type: integer type: array maxItems: 100 minItems: 1 additionalProperties: false type: object title: ListSimulatorModelsFilters AggregateCount: properties: count: type: integer title: Count description: Number of items additionalProperties: false type: object required: - count title: AggregateCount APIError: properties: message: type: string title: Message code: type: integer title: Code type: object required: - message - code title: APIError securitySchemes: oidc-token: type: http scheme: bearer bearerFormat: OpenID Connect or OAuth2 token description: >- 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'. The token can be obtained through any flow supported by the identity provider. oauth2-client-credentials: type: oauth2 description: >- 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'. The token can be obtained through any flow supported by the identity provider. flows: clientCredentials: tokenUrl: https://your-idps.token.url/ scopes: default: https://{cluster}.cognitedata.com/.default oauth2-open-industrial-data: type: oauth2 description: >- Auth flow for Open Industrial Data. Get your client secret from https://hub.cognite.com/open-industrial-data-211. flows: clientCredentials: tokenUrl: >- https://login.microsoftonline.com/48d5043c-cf70-4c49-881c-c638f5796997/oauth2/v2.0/token scopes: default: https://api.cognitedata.com/.default oauth2-auth-code: type: oauth2 description: >- 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'. The token can be obtained through any flow supported by the identity provider. flows: authorizationCode: authorizationUrl: https://your-idps.authorization.url/ tokenUrl: https://your-idps.token.url/ scopes: default: https://{cluster}.cognitedata.com/.default ````