{ "openapi": "3.1.0", "info": { "title": "Cognite API", "description": "# Introduction\nThis is the reference documentation for the Cognite API with\nan overview of all the available methods.\n\n# Postman\nSelect the **Download** button to download our OpenAPI specification to get started.\n\nTo import your data into Postman, select **Import**, and the Import modal opens.\nYou 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**.\n\nIn the Import Settings, set the **Folder organization** to **Tags**, select\n**Enable optional parameters** to turn off the settings, and select **Always inherit authentication** to turn on the settings. Select **Import**.\n\nSet 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.\n\nFor more information, see [Getting Started with Postman](https://developer.cognite.com/dev/guides/postman/).\n\n# Pagination\nMost resource types can be paginated, indicated by the field `nextCursor` in the response.\nBy passing the value of `nextCursor` as the cursor you will get the next page of `limit` results.\nNote that all parameters except `cursor` has to stay the same.\n\n# Parallel retrieval\nAs 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. \n\nCDF 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.\nIf 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:\n - Make a request to `/events` with `partition=m/10`.\n - Paginate through the response by following the cursor as explained above. Note that the `partition` parameter needs to be passed to all subqueries.\n\nProcessing 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.\n\nTo prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. \nSome CDF resources will automatically enforce a maximum of 10 partitions.\nFor more specific and detailed information, please read the ```partition``` attribute documentation for the CDF resource you're using. \n\n# Requests throttling\nCognite Data Fusion (CDF) returns the HTTP `429` (too many requests) response status code when project capacity exceeds the limit.\n\nThe throttling can happen:\n - If a user or a project sends too many (more than allocated) concurrent requests.\n - If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.\n\nCognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.\n\nCognite recommends using a reasonable number (up to 10) of `Parallel retrieval` partitions.\n\nFollowing these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.\n\nSee more [here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\n# API versions\n## Version headers\nThis API uses calendar versioning, and version names follow the `YYYYMMDD` format.\nYou can find the versions currently available by using the version selector at the top of this page.\n\nTo use a specific API version, you can pass the `cdf-version: $version` header along with your requests to the API.\n\n## Beta versions\nThe beta versions provide a preview of what the stable version will look like in the future.\nBeta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.\n\nBeta versions are indicated by a `-beta` suffix after the version name. For example, the beta version header for the\n2023-01-01 version is then `cdf-version: 20230101-beta`.\n\n## Alpha versions\nAlpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API.\nThis functionality presents no guarantee of service, so its use is subject to caution.\n\nAlpha versions are indicated by an `-alpha` suffix after the version name. For example, the alpha version header for\nthe 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.\n\n\n\n## 2026-06-15\n### Data Workflows\n#### Added\n- Added `initializeCursor` to `RecordStreamTrigger` to control where record stream syncing starts when no cursor exists yet. Defaults to `\"0d-ago\"` for backward compatibility.\n#### Changed\n- `RecordStreamTrigger` is now generally available (GA).\n\n## 2026-06-12\n### Postgres gateway\n#### Changed\n- `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.\n\n## 2026-05-28\n### Data Products\n#### Added\n\nA 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.\n- `POST /dataproducts` creates a data product.\n- `GET /dataproducts` lists all data products.\n- `GET /dataproducts/{externalId}` gets a data product.\n- `POST /dataproducts/update` updates a data product.\n- `POST /dataproducts/delete` deletes a data product.\n- `POST /dataproducts/{externalId}/versions` creates a data product version.\n- `GET /dataproducts/{externalId}/versions` lists all versions of a data product.\n- `GET /dataproducts/{externalId}/versions/{version}` gets a data product version.\n- `POST /dataproducts/{externalId}/versions/update` updates a data product version.\n- `POST /dataproducts/{externalId}/versions/delete` deletes data product versions.\n\n### Entity matching\n\n#### Changed\n\n- `GET /context/entitymatching`: added cursor pagination (`cursor` query parameter, optional `nextCursor` in response). `limit` defaults to 100 with maximum 1000.\n\n## 2026-05-27\n### Atlas AI\n#### Added\n- Agent list: optional query `skillExternalId` to filter agents by skill external ID.\n\n#### Changed\n- 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).\n- Skills create: `externalId` is required on the create request body (was optional).\n- Agent list: `skillName` query filter constrained to skill-name rules (1–64 characters; lowercase letters, digits, and hyphens; must not start with `cdf-`).\n- Skill `externalId`: 1–128 characters, no null (U+0000), must not start with `cdf-` (replaces slug-style name rules, max 64).\n- Skills upload: single UTF-8 `.md` file only (`SKILL.md` shape); zip archives and additional skill files are no longer supported.\n- Skills create/upload: project may have at most **200** skills (`maxSkillLimit` default **200**, was 30); exceeding the limit returns **400**.\n- 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.\n\n#### Removed\n- `GET /ai/skills/{skill_name}/{file_external_id}` per-file download endpoint.\n- `additionalFiles` on skill create/update and related schemas (`AdditionalFileRequest`, `SkillAdditionalFileResponse`).\n- Zip-based skill upload and multi-file skill packages.\n\n## 2026-05-26\n### Data Modeling API\n#### Added\n- Added `recordsOnlyContainers` and `recordsOnlyContainerProperties` to `ProjectStatistics` response definition.\n- Added `containerProperties`, `recordsOnlyContainers` and `recordsOnlyContainerProperties` to `SpaceStatistics` response definition.\n\n## 2026-05-22\n### Chat Completions API (alpha)\n#### Added\n- Added new `ai/openai/chat/completions` endpoint to generate chat completions\n- Added new `ai/openai/models` endpoint to list available models\n\n### Agents API (beta)\n#### Added\n- Added `subagents` field to the agents API\n\n## 2026-05-21\n### Functions\n#### Changed\n- `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.\n\n## 2026-05-18\n### Atlas AI\n#### Changed\n- Skills download and per-file read endpoints: `skill_name` and `file_external_id` path segments are trimmed of leading and trailing whitespace before validation.\n- Per-file read `file_external_id`: accepts any 1–128 character identifier without null (U+0000); updated parameter and response descriptions.\n\n### Token API\n#### Added\n- Added \"Cognite Units Capability\" to the token inspection response, including required `cogUnitsAcl` and `projectScope` properties.\n\n## 2026-05-12\n### Atlas AI\n#### Added\n- Added Skills API (`/ai/skills`, by-ids, delete, upload, download, per-file read) and related schemas.\n- Agent schemas: `labels`, `skills`; runtime metadata and session chunk/progress response types.\n- Agent session (beta): `retentionPolicy` when starting a conversation (`temporary` by default vs `persisted`).\n\n#### Changed\n- Agent contract defaults: model `azure/gpt-4.1`, runtime **1.2.0**; `ownerId` described as read-only (set on create).\n\n### Functions\n#### Changed\n- `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.\n\n## 2026-05-08\n### Groups API\n#### Added\n- Added `cogUnitsAcl` support to `CogniteCapability`, including `cogunits_aclAcl`, `cogunits_aclAction`, and `cogunits_aclScope` schema definitions.\n\n### Data Workflows (internal)\n#### Added\n- Added `docParser` task type to Data Workflows\n\n## 2026-05-07\n### Data Modeling API\n#### Added\n- Added `isAutoRetryable` to `UpsertConflict` response definition.\n\n### Agent APIs (beta)\n#### Added\n- Documented the `query` agent tool (beta) for exploring Cognite data models and instances with direct SDK-level control.\n\n#### Changed\n- Updated the documented default agent `runtimeVersion` to 1.2.0 (previously 1.1.1).\n\n## 2026-05-06\n### Data Workflows (beta)\n#### Changed\n- Upgrade Json Mapping task type definition to beta version\n- Remove deprecated `inputs` arguments from Json Mapping task type\n\n### Cognite Functions\n#### Added\n- Added `functionType` as a get-only field on Cognite Functions allowing to differentiate between `classic` functions and `functionApp`.\n\n## 2026-05-05\n### Signals\n#### Changed\n- Signals API is now in beta (promoted from alpha)\n\n### Seismic\n#### Removed\n- Seismic API is removed\n\n## 2026-05-04\n### Simulator integration API\n#### Changed\n- Made `simulatorIntegrationExternalId` optional when creating routines, routine revisions, and simulation runs.\n- Added `queued` status to `SimulationRunStatus` enum to represent runs which are not assigned to any connector.\n\n## 2026-04-30\n### Streams and Records API\n#### Added\n- `targetUnits` parameter has been added to records `/sync`, `/filter` and `/aggregate` endpoint\n requests, which allows unit conversion from source units to specified target units or unit system.\n- `includeTyping` parameter has been added to records `/sync`, `/filter` and `/aggregate` endpoint\n requests. If set to true, typing information of properties present in the request and\n the response will be included in the response.\n\n## 2026-04-23\n### Cognite Functions\n#### Changed\n- Cognite functions now use Python 3.13 (py313) as the default runtime, replacing Python 3.12 (py312).\n\n### Agent APIs (beta)\n#### Added\n- Extended `ReasoningDTO` with a structured `data` field to expose machine-readable reasoning payloads in agent chat responses.\n- Added reasoning payload schemas `AgentReasoningDataDTO` and `ToolCallDetailDTO` to represent tool-call details in reasoning output.\n\n## 2026-04-21\n### Documents AI API\n#### Added\n- 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.\n\n## 2026-04-15\n### Data Modeling API\n#### Added\n- New debug notice `intractableCursorWithNestedFilter` (grade D, warning): emitted when a query\n supplies both a cursor and a nested filter on the same result set expression. The additional\n join required by the nested filter can prevent efficient index-backed pagination.\n\n## 2026-04-10\n### Cognite Functions\n#### Added\n- 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.\n\n## 2026-03-25\n### Streams and Records API\n#### Changed\nStricter validation in aggregate records request:\n- Aggregate identifiers can no longer contain `.` character.\n- Values `_count` and `_bucket_count` can no longer be used as aggregate identifiers.\n- Duplicate aggregate identifiers within the aggregate tree are no longer allowed.\n\n## 2026-03-24\n### Data Modeling API\n#### Changed\n- Added `EnumProperty` to `RecordContainerPropertyTypeDefinition`, enabling enum properties in containers with `usedFor` set to `record`.\n- Updated the supported storage types description for record container properties to include `enum`.\n\n## 2026-03-23\n### Streams and Records API\n#### Changed\n- Fixed maximum number of active streams created from `BasicLiveData` template to match what we actually allow.\n\n## 2026-03-20\n### Data Workflows (beta)\n#### Added\n- 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.\n\n## 2026-03-17\n### Transformations\n#### Added\n- Added `autoCreate` field to `ViewDataSource` and `DataModelSource` destination configurations for transformations. The `autoCreate` field accepts an `AutoCreateOptions` object with three boolean properties:\n - `startNodes`: Controls automatic creation of missing start nodes when creating edges (default: true)\n - `endNodes`: Controls automatic creation of missing end nodes when creating edges (default: true)\n - `directRelations`: Controls automatic creation of missing direct relation targets (default: true)\n When set to false, the transformation will validate node/relation references and return a 400 error if referenced instances do not exist.\n\n## 2026-03-12\n### 3D API (beta)\n#### Deprecated\n- 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.\n\n## 2026-03-09\n### Agent APIs (beta)\n#### Added\n- New OpenAI models: `azure/gpt-5.2`, `azure/gpt-5.4`\n\nNote: Availability of models may differ between the chosen cloud provider and region of the CDF cluster.\n\n## 2026-03-06\n### Agent APIs (beta)\n#### Changed\n- Changed the default Query Knowledge Graph (QKG) Tool strategy from v1 to v2.\n\n\n## 2026-03-04\n### Agent APIs (beta)\n#### Added\n- Added `stream` parameter to `AgentSessionRequest` to enable progress message streaming.\n\n## 2026-01-20\n### Data Modeling API\n#### Added\n- Added 3 new endpoints to trigger revalidation of failed constraints or indexes.\n - `/models/containers/constraints/retry` for container-level constraints (`requires`, `uniqueness`)\n - `/models/containers/indexes/retry` for indexes\n - `/models/containers/properties/retry` for property-level constraints (`nullable`, `maxListSize`, `maxTextSize`)\n\n## 2026-01-15\n### Data Workflows\n#### Added\n- Added `maxConcurrentExecutions` field to workflows to limit concurrent executions.\n\n## 2026-01-13\n### Hosted Extractors\n#### Added\n- Added support for client credentials authentication to eventhub sources.\n\n## 2026-01-06\n### 3D API (beta)\n#### Added\n- 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.\n\n## 2025-12-06\n### Data Workflows\n#### Added\n- 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.\n\n## 2025-12-05\n### 3D API (beta)\n#### Added\n- 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.\n\n## 2025-11-25\n### Data Workflows\n#### Added\n- Added `/workflows/triggers/{triggerExternalId}/pause` endpoint to pause triggers. A paused trigger will not create new workflow executions until resumed.\n- Added `/workflows/triggers/{triggerExternalId}/resume` endpoint to resume a previously paused trigger.\n\n## 2025-11-28\n### Data Modeling API\n#### Added\n- Added `record` value that can be specified for the container's ```usedFor``` property\n\n## 2025-11-26\n### Agent APIs (beta)\n#### Added\n- 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.\n\n### 3D API (beta)\n#### Added\n- 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.\n\n## 2025-11-21\n### Hosted extractors API\n#### Added\n- Added `authCertificate` to REST sources.\n#### Deprecated\n- 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.\n\n## 2025-11-20\n### Agent APIs (beta)\n#### Added\n- 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.\n- Added `examineDataSemantically` (alpha) to the list of available tools for agents.\n- Added new AWS model: `aws/claude-4.5-sonnet`.\n\n## 2025-11-18\n### Simulator integration API\n#### Added\n- 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.\n- 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.\n\n## 2025-11-13\n### 3D API\n#### Added\n- 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\n - `POST /3d/contextualization/image360` define image360 contextualizations towards assets\n - `POST /3d/contextualization/image360/delete` remove image360 contextualizations towards assets\n\n## 2025-11-11\n### Streams and Records API\n#### Changed\n- Changed format of partial success response for record ingest, upsert and delete operations.\n\n## 2025-11-06\n### Simulator integration API\n- Added `simulatorExternalIds` filter to the simulator model revisions list endpoint (`POST /simulators/models/revisions/list`), allowing filtering of model revisions by simulator external IDs.\n\n## 2025-11-04\n### Streams and Records API\n#### Added\n- The Streams and Records API is now in General Availability (GA).\n - The following endpoints are now available:\n - `POST /streams` to create a stream.\n - `DELETE /streams/{streamId}` to delete a stream.\n - `GET /streams` to list all streams.\n - `GET /streams/{streamId}` to retrieve a specific stream.\n - `POST /streams/{streamId}/records` to create new records into a stream.\n - `POST /streams/{streamId}/records/upsert` to create new or update existing records in a mutable stream.\n - `POST /streams/{streamId}/records/delete` to delete records in a mutable stream.\n - `POST /streams/{streamId}/records/filter` to retrieve records from a stream.\n - `POST /streams/{streamId}/records/sync` to sync records from a stream.\n - `POST /streams/{streamId}/records/aggregate` to aggregate record data from a stream.\n\n## 2025-10-29\n### Simulator integration API\n#### Added\n- Added `simulatorExternalIds` filter to the simulator routines list endpoint (`POST /simulators/routines/list`), allowing filtering of routines by simulator external IDs.\n- Added support for simulator routines aggregation (`POST /simulators/routines/aggregate`)\n\n## 2025-10-07\n### Agents API\n#### Added\n- 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.\n\n## 2025-10-03\n### Cognite Functions\n#### Removed\n- Python 3.9 (py39) is no longer supported as a runtime argument for Cognite functions.\n\n## 2025-10-02\n### Agent APIs (beta)\n- Gemini 2.0 Flash and Claude 3 Haiku have been retired as model options.\n\n## 2025-10-01\n### Data Modeling API\n#### Added\n- Added `state` field to constraints returned from the service, describing whether the constraint is validated or failed.\n- Added `state` field to indexes returned from the service, describing whether the index is successfully built, or if building failed.\n- 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.\n\n## 2025-09-29\n### Agent APIs (beta)\n#### Deprecated\n- `agentId` in the `/ai/agents/chat` endpoint has been deprecated in favor of `agentExternalId`. `agentId` will be retired from 2025-11-29.\n#### Removed\n- Gemini 1.5 Pro and Gemini 1.5 Flash have been retired as model options.\n\n## 2025-09-26\n### Time Series API\n#### Changed\n- Increased the maximum length of string data points from 255 characters to 1023 bytes (UTF-8 encoded).\n\n## 2025-09-09\n### Data Modeling API\n#### Added\n- 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.\n\n## 2025-09-08\n\n### Default runtime in Cognite functions\n\n#### Changed\n- Default Python runtime in Cognite functions has been updated from Python 3.11 (py311) to Python 3.12 (py312).\n\n## 2025-09-02\n### Data Modeling API\n#### Added\n- Added a `debug` parameter to the `/models/instances/query`, `/models/instances/sync`, and `/models/instances/list` endpoints.\n- The feature returns `notices` providing insights into query execution, which can be used for performance analysis and optimization.\n\n## 2025-08-26\n### Data sets API\n#### Fixed\n- Add length constraints on `name` and `description` fields for the `/update` endpoint to disallow empty strings.\n\n## 2025-09-02\n### 3D API\n#### Added\n- 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.\n - `POST /3d/contextualization/pointcloud`\n - `POST /3d/contextualization/pointcloud/delete`\n\n## 2025-08-28\n### Agent APIs (beta)\n#### Added\n- 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`\n- New Gemini models: `gcp/gemini-2.5-pro`, `gcp/gemini-2.5-flash`\n- New AWS models: `aws/claude-4-sonnet`, `aws/claude-4-opus`, `aws/claude-4.1-opus`\n\nNote: Availability of models may differ between the chosen cloud provider and region of the CDF cluster.\n\n#### Improved\n- 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.\n\n## 2025-08-29\n### Simulator integration API\n#### Changed\n- 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)\n- Support multiple flowsheets in a simulator model revision data. (Alpha feature)\n\n## 2025-09-02\n### IAM (Identity and access management)\n#### Added\n- The following endpoints (all under https://auth.cognite.com) are added:\n - `/api/v1/orgs/{org}/principals/{principal}/sessions`: List login sessions for a user principal in an organization.\n - `/api/v1/orgs/{org}/principals/{principal}/sessions/revoke`: Revoke one or more login sessions for a user principal\n in an organization.\n\n## 2025-08-20\n### 3D API\n#### Added\n- 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.\n- Added support in the list 3D asset mappings endpoint for listing `assetInstanceId` based mappings, enabled with the `getDmsInstances=true` parameter.\n\n## 2025-07-21\n### Data Modeling API\n#### Added\n- Added `mode` to table expressions in the `/sync` endpoint, to select between sync modes:\n - `onePhase` (default, current behavior): All instances are returned while following the cursor\n - `twoPhase`: Existing instances are returned first, then new instances are returned by following the cursor\n - `noBackfill`: Existing instances are not returned, only new instances are yielded by following the cursor.\n- Added `backfillSort` to table expressions in the `/sync` endpoint, to optionally specify how to sort existing instances with `syncMode: twoPhase`.\n\n## 2025-07-18\n### Data Modeling API\n#### Added\n- Add `timezone` property to the `/trigger` endpoint.\n\n## 2025-07-04\n### IAM (Identity and access management)\n#### Added\n\n- Added `attributes` to group creation in the POST `/api/v1/projects/:project/groups` endpoint to set attributes for groups.\n\n## 2025-06-30\n### Data Modeling API\n#### Added\n- Add `allowExpiredCursorsAndAcceptMissedDeletes` flag to the `/sync` endpoint.\n\n## 2025-05-21\n### Agent APIs\n#### Fixed\n- Removed the duplicate `/api/v1/projects/{projectName}` prefix from all agents endpoints.\n\n### Documents AI API\n#### Fixed\n- Removed the duplicate `/api/v1/projects/{projectName}` prefix from all documents AI endpoints.\n\n\n## 2025-05-26\n### Simulator integration API\n#### Changed\n- Introduced request body size limits for the simulator integration API endpoints.\n - `POST /simulators/routines/revisions` to create simulator routines revisions: 50KB\n - `POST /simulators/run` to run a simulation: 50KB\n - 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.\n\n## 2025-05-21\n### Simulator integration API\n#### Changed\n- 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.\n\n## 2025-05-15\n### 3D API\n#### Added\n- The 3D API now supports filtering nodes within a boundingbox in dm-only projects.\n - The following endpoint is now available:\n - `POST /3d/nodes/list` to filter nodes within an area definition.\n\n## 2025-05-15\n### Transformations\n#### Changed\n- Enforcement of 90 days retention rule for job history\n\n## 2025-05-09\n### 3D Api\n#### Added\n- The 3D Jobs API is extended to include the job result and job result rejections endpoints.\n - The following endpoints are now available:\n - `POST /3d/job/results/list` to list the results of a job\n - `POST /3d/job/result/rejections` to add or remove job result rejections\n - `POST /3d/job/result/rejections/list` to list job result rejections\n\n## 2025-04-30\n### 3D Api\n#### Added\n- The 3D Jobs API is now available in DM-Only Projects\n - The following endpoints are now available:\n - `POST /3d/jobs` to create a 3d job\n - `POST /3d/jobs/list` to list jobs\n - `POST /3d/jobs/delete` to delete jobs\n\n## 2025-04-23\n### Entity Matching\n#### Changed\n- Enforcement of request limits.\n - `POST /context/entitymatching/byids` can retrieve max 1000 models per request.\n - `POST /context/entitymatching/update` can update max 1000 models per request.\n - `POST /context/entitymatching/delete` can delete max 1000 models per request.\n\n\n## 2025-03-25\n### Agent APIs\n#### Added\n- The Agent APIs is now available in Alpha.\n - The following endpoints are now available:\n - `POST /ai/agents` to create or update one or more agents\n - `GET /ai/agents` to list all agents\n - `POST /ai/agents/ids` to retrieve one or more agents by externalId\n - `POST /ai/agents/delete` to delete one or more agents by externalId\n - `POST /ai/agents/chat` to send messages new messages and receive an answer to a specific agent\n\n## 2025-03-25\n### Documents AI\n#### Added\n- A new field for specifying the language that the answer should be in, added to Documents Summarize endpoint (`/ai/tools/documents/summarize`).\n\n## 2025-03-13\n### Documents API\n#### Added\n- Added ability to filter on the `space` and `externalId` properties of an `instanceId` object.\n\n## 2025-03-12\n### Time Series API\n#### Added\n- New aggregates `maxDatapoint` and `minDatapoint`, that gives back both the value and the timestamp of the maximum/minimum data point.\n\n## 2025-02-17\n### PostgreSQL Gateway API\n#### Added\n- The PostgreSQL Gateway API is now in General Availability (GA).\n - The following endpoints are now available:\n - `POST /postgresgateway` to create postgres users.\n - `POST /postgresgateway/delete` to delete postgres users.\n - `POST /postgresgateway/list` to filter postgres users.\n - `GET /postgresgateway` to list postgres users.\n - `POST /postgresgateway/byids` to retrieve postgres users by their username.\n - `POST /postgresgateway/update` to update postgres users.\n - `POST /postgresgateway/tables/{username}` to create postgres foreign tables.\n - `POST /postgresgateway/tables/{username}/delete` to delete postgres foreign tables.\n - `GET /postgresgateway/tables/{username}` to list postgres foreign tables.\n - `POST /postgresgateway/tables/{username}/byids` to retrieve postgres foreign tables by name.\n\n## 2025-02-15\n### Principals API\n#### Added\n- The Principals API is now generally available.\n\n#### Deprecated\n- The User profiles API is deprecated in favor of the Principals API, which offers a superset of the functionality.\nThe User profiles API will be removed in a future release.\n\n## 2025-01-20\n### Hosted Extractors API\n#### Added\n- Added support for `clientCredentials` auth to kafka sources.\n\n## 2024-12-03\n### SAP Writeback API\n#### Added\n- SAP writeback API reaches General Availability (GA).\n - The following endpoints are now available:\n - `GET /writeback/sap/instances` to list SAP instance destinations\n - `POST /writeback/sap/instances` to create SAP instance destinations\n - `POST /writeback/sap/instances/delete` to delete SAP instance destinations\n - `POST /writeback/sap/instances/byids` to retrieve SAP instance destinations by externalId\n - `GET /writeback/sap/endpoints` to list SAP endpoint destinations\n - `POST /writeback/sap/endpoints` to create SAP endpoint destinations\n - `POST /writeback/sap/endpoints/delete` to delete SAP endpoint destinations\n - `POST /writeback/sap/endpoints/byids` to retrieve SAP instance destinations by externalId\n - `POST /writeback/sap/endpoints/verify` to verify connectivity between CDF and the SAP endpoint destination\n - `GET /writeback/sap/mappings` to list schema mappings\n - `POST /writeback/sap/mappings` to create schema mappings\n - `POST /writeback/sap/mappings/delete` to delete schema mappings\n - `POST /writeback/sap/mappings/byids` to retrieve schema mappings destinations by externalId\n - `GET /writeback/sap/requests` to list writeback requests\n - `POST /writeback/sap/requests` to create writeback requests. Maximum concurrent limit of 50 requests per CDF project.\n - `POST /writeback/sap/requests/byids` to retrieve writeback requests by externalId\n\n### Hosted Extractors API\n#### Added\n- `REST` and `EventHub` sources and jobs are now in GA.\n\n## 2024-11-19\n### Simulator integration API\n#### Added\n- Simulator integration API reaches General Availability (GA).\n - The following endpoints are now available:\n - `POST /simulators/*` to access the simulators API and list simulators enabled for the project\n - `POST /simulators/integrations/*` to list simulator connectors and their state\n - `POST /simulators/models/*` to create/list/remove simulator models and their revisions\n - `POST /simulators/routines/*` to create/list/remove simulator routines and their revisions\n - `POST /simulators/runs/*` to create/schedule simulation runs\n - `POST /simulators/logs/*` to access simulator logs\n\n### Documents AI APIs\n#### Added\n- Documents AI APIs (`/ai/tools/documents/ask` and `/ai/tools/documents/summarize`) reaches General Availability (GA).\n\n## 2024-11-14\n### User profiles\n#### Added\n- Organization principals: get calling principal's profile\n\n#### Deprecated\n- `GET /api/v1/{projectName}/profiles/me` is deprecated in favor of the new endpoint.\n\n## 2024-11-12\n### Organizations and Projects\n#### Updated\n- `GET /api/v1/orgs/{org}/projects?includeAdminProperties=true` now includes `state` and `deletionTime`\n\n## 2024-10-22\n### Hosted Extractors API\n#### Added\n- Stabilized the API for `Sources`, `Mappings`, `Destinations` and `Jobs`, for MQTT and Kafka extractors.\n- Promote Rest and EventHub extractors to public beta.\n- Support data models in hosted extractors.\n\n## 2024-10-14\n### AWS Cognito support\n#### Added\n- Support creating organization with AWS Cognito as IdP.\n - `POST /api/v1/orgs/{orgId}/orgs` can be called to create organization with AWS Cognito as IdP.\n\n## 2024-10-11\n### Organizations and Projects\n#### Added\n- Allow non-admin users to list all projects in an organization.\n - `GET /api/v1/orgs/{orgId}/projects` can be called by all users of an organization.\n- Include `apiUrl` when listing projects in an organization.\n - `GET /api/v1/orgs/{orgId}/projects` will include `apiUrl` for each project.\n\n## 2024-09-31\n### Time Series API\n#### Added\n- Introduced support for time series managed by Data modeling in data point subscriptions.\n - `GET subscriptions/members` can contain members with `instanceId`.\n - `POST subscriptions` can be used to create subscriptions with an defined set of instance ids.\n - `POST subscriptions/update` can be used to add/remove/set the instance id time series members.\n\n## 2024-09-19\n### Contextualization / Vision\n#### Added\n- Support for Vision endpoints referencing files by data modeling instance IDs, as an alternative to ID and external ID.\n\n## 2024-09-14\n### Simulator integration API\n#### Added\n- 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.\n - `POST /simulators/*` to access the simulators API and list simulators enabled for the project\n - `POST /simulators/integrations/*` to list simulator connectors and their state\n - `POST /simulators/models/*` to create/list/remove simulator models and their revisions\n - `POST /simulators/routines/*` to create/list/remove simulator routines and their revisions\n - `POST /simulators/runs/*` to create/schedule simulation runs\n - `POST /simulators/logs/*` to access simulator logs\n\n## 2024-09-13\n### Contextualization / Engineering diagrams\n#### Added\n- Support for detecting tags in diagrams referencing files by data modelling instance ids as an alternative to id and externalId.\n\n## 2024-09-12\n### Files API\n#### Added\n- Add support for `ignoreUnknownIds` to the `files/delete` endpoint.\n\n### SAP Writeback\n#### Added\n- SAP Writeback API (Beta)\n\n## 2024-09-10\n### Time Series API\n#### Added\n- Introduces support for Time Series managed by Data modeling.\n - `/timeseries/*` endpoints will return data modeling instance Id in time series objects where applicable.\n - `POST /timeseries/update` can be used to update properties of data modeling time series, but only fields that are not managed by data modeling.\n - `POST /timeseries/byids` can be used to retrieve time series by instance Id.\n - `POST /timeseries/list` and `POST /timeseries/aggregate` support advanced filters with `instanceId.space` and `instanceId.externalId` fields. (No changes to regular filters)\n - `POST /timeseries/data/*` can be used with instance Id to ingest/delete/query data points.\n - `POST /timeseries/synthetic/query` can lookup by instance Id.\n\n### Subscriptions API\n#### Added\n- Subscription filters support advanced filters with `instanceId.space` and `instanceId.externalId` fields.\n- List subscription members will show time series instance Ids, if available.\n\n## 2024-09-02\n### Files API\n#### Added\n- Introduces support for Files managed by Data modeling, which means following endpoints will allow specifying instance Id\n - `POST /files/uploadlink` to get upload links for files\n - `POST /files/multiuploadlink` to get multipart upload link for files\n - `POST /files/completemultipartupload` to complete a multipart file upload\n - `POST /files/downloadlink` to get download links for files\n - `GET /files/icon` to get an image representation of a file\n - `POST /files/byids` to retrieve metadata information about multiple specific files\n - `POST /files/update` to updates the information for the files\n\n## 2024-08-23\n### Data Workflows\n#### Added\n- subworkflow task: add support for referencing other workflow versions to run as part of a workflow\n\n## 2024-08-20\n### Data Workflows\n#### Added\n- Introduces the trigger resource for Data Workflows, which adds support for scheduling the execution of workflows and the management thereof.\n - `POST /workflows/triggers` to create a UNIX cron trigger for a workflow\n - `GET /workflows/triggers` to list all triggers\n - `POST /workflows/triggers/delete` to delete a trigger\n - `GET /workflows/triggers/{triggerExternalId}/history` which keeps a ledger of when the trigger fired and if it successfully started a workflow or not.\n\n## 2024-07-18\n### Organizations and Projects\n#### Added\n- Selected endpoints are promoted from beta to v1 (all under https://auth.cognite.com; note that the routes are\n different from the beta routes, and that some request and response signatures have changed):\n - `GET /api/v1/orgs/{orgId}` to get organization info\n - `POST /api/v1/orgs/{orgId}/orgs` to create an organization\n - `POST /api/v1/orgs/{orgId}/delete` to delete an organization\n - `GET /api/v1/orgs/{orgId}/orgs` to list the child organizations of an organization\n - `POST /api/v1/orgs/{orgId}/projects` to create a project in an organization\n - `GET /api/v1/orgs/{orgId}/projects` to list the projects in an organization\n\n#### Deprecated\n- The six beta endpoints that have been published as new V1 endpoints (just above) are deprecated and will be removed in\n a future release.\n\n## 2024-06-24\n### Data Modeling\n\n#### Added\n- Support marking properties as immutable\n\n## 2024-06-17\n### Data Modeling\n\n#### Added\n- Support for creating properties of type `direct_relation[]`, allowing direct relations to point to multiple nodes.\n- /containers/inspect endpoint to retrieve information about which views map a container.\n- /instances/inspect endpoint to retrieve information about which containers an instance has data in.\n\n## 2024-06-13\n### Organizations and Projects\n#### Added\n- Projects API (Beta): Allow for parametrization of the initial admin group when creating a project.\n\n### Time Series\n#### Added\n- 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.\n- New `month` (mo) granularity.\n- Also applies to synthetic time series.\n\n## 2024-05-24\n### Organizations and Projects\n#### Added\n- Organizations API (Beta): create, list, and delete CDF organizations\n- Organizations API (Alpha): update CDF organizations\n- Projects API (Beta): create and list projects in CDF organizations\n\n### User profiles\n#### Added\n- Organization user profiles (Beta): list users in CDF organizations\n\n### Projects\n#### Removed\n- Removed the previous Projects API from public documentation, as those endpoints are available to Cognite and resellers\n only.\n\n## 2024-05-23\n\n### Time series\n\n#### Added\n- 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.\n- Beta support for new `month` (mo) granularity.\n- Also applies to synthetic time series.\n\n## 2024-05-02\n\n### Postgres gateway\n\n#### Added\n- Endpoints for managing PostgreSQL gateway\n\n## 2024-05-01\n\n### Time series\n\n#### Added\n\n- Added support for [status codes](https://developer.cognite.com/dev/concepts/resource_types/timeseries#data-point-quality-status-codes) for data points.\n\n## 2024-04-02\n\n### Groups\n\n#### Added\n\n- 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.\n\n## 2024-03-19\n\n### Engineering diagrams (beta)\n\n#### Added\n- Beta endpoint for retrieving ocr data for a file per page.\n Currently, only files that have been run through diagram/detect will give any results.\n This may be up for change in the future.\n The endpoint replaces a previous playground endpoint which is no longer documented.\n\n## 2024-03-11\n\n### Default runtime in Cognite functions\n\n#### Changed\n- 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.\n\n## 2024-03-06\n\n### Files\n\n#### Updated\n- Files API rate and concurrency limits have been documented.\n -- Service layer request rate and concurrency limits added\n -- CRUD endpoints request rate, concurrency and items rate limits added\n -- Analytic endpoints request rate, concurrency rate limits added\n\n## 2024-02-29\n\n### Assets\n\n#### Updated\n- Assets API rate and concurrency limits have been documented.\n -- Service layer request rate and concurrency limits added\n -- CRUD endpoints request rate, concurrency and items rate limits added\n -- Analytic endpoints request rate, concurrency and items rate limits added\n\n## 2024-02-20\n\n### Data Modeling\n\n#### Added\n**Conversion between unit types for returned values during filter and query operations.**\n- Trigger conversion by setting the `targetUnit` by `externalId` or `unitSystemName` parameters for the data source in a query.\n- 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.\n- `typing` - `type.unit` on a property in a `typing` object is now always the same as the unit for the returned data.\n- Added `typing` to following endpoints:\n - query\n - sync\n - aggregate\n - search\n\n## 2024-02-19\n\n### Time series\n\n#### Added\n\n- Data point subscriptions reaches General Availability (GA).\n - Use the new [Data point subscriptions](https://developer.cognite.com/dev/concepts/data_point_subscriptions/)\n feature to configure a subscription to listen to changes in one or more\n time series (in ingestion order).\n The feature is intended to be used where data points consumers need to keep up to date with\n changes to one or more time series without the need to read the entire time series again.\n\n## 2024-02-08\n\n### Hosted Extractors\n\n#### Changed\n\n- `host` in kafka sources has been replaced with `bootstrapBrokers`, which is an array of objects with `host` and `port`.\n\n\n## 2024-02-01\n\n### Synthetic time series\n\n#### Added\n- Support for unit conversion by setting `targetUnit` or `targetUnitSystem` on time series or aggregates with a compatible `unitExternalId` field.\n\n\n## 2024-01-16\n\n### Sessions\n\n#### Added\n- 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.\n\n## 2024-01-02\n\n### Data Modeling\n\n#### Added\n- Support for a `bySpace` flag on btree indexes and uniqueness constraints.\n\n\n## 2023-12-12\n\n### Data Modeling\n\n#### Added\n- **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.\n\n\n## 2023-12-11\n\n### Time series\n\n#### Changed\n\n- 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.\n\n## 2023-12-06\n\n### Time series\n\n#### Added\n- [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.\n - [Create timeseries](https://docs.cognite.com/api#tag/Time-series/operation/postTimeSeries) with a unitExternalId.\n - [Update timeseries](https://docs.cognite.com/api#tag/Time-series/operation/alterTimeSeries) to add/remove unitExternalId.\n- Filter and aggregate time series by unitExternalId or unitQuantity (eg. \"volume\" or \"temperature\"). Both using regular filters and advanced filters.\n - [Filter time series](https://docs.cognite.com/api#tag/Time-series/operation/listTimeSeries).\n - [Aggregate time series](https://docs.cognite.com/api#tag/Time-series/operation/aggregateTimeSeries).\n - [Search time series](https://docs.cognite.com/api#tag/Time-series/operation/searchTimeSeries).\n- 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.\n\n## 2023-11-30\n\n### Hosted extractors\n\n#### Changed\n\n- Hosted extractors API (Beta)\n - Updates hosted extractor schema with tls certificate details hence users can now provide CA and authentication certificates for connection to MQTT brokers.\n - 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.\n\n## 2023-11-21\n\n### Units Catalog\n\n#### Added\n\n- 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.\n\n## 2023-11-17\n\n### Documents\n\n#### Added\n\n- Added support for sorting in the `/documents/list` endpoint. It works exactly the same as the sorting\n in `/documents/search` except that you can not sort on search relevance.\n\n## 2023-11-08\n\n### Engineering diagrams\n\n#### Changed\n\n- Optional token mechanism for accessing detected results of engineering diagrams without read all access to assets.\n See [diagram/detect](https://api-docs.cognite.com/20230101/tag/Engineering-diagrams/operation/diagramDetect) for details.\n\n## 2023-10-23\n\n### Files\n\n#### Added\n\n- 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.\n Optionally use parallel part upload, for greater upload speed.\n See the documentation for the new endpoints at:\n - [Upload multipart file](https://docs.cognite.com/api/20230101/#tag/Files/operation/initMultiPartUpload) and\n - [Complete multipart upload](https://docs.cognite.com/api/20230101/#tag/Files/operation/completeMultiPartUpload) endpoints.\n\n## 2023-10-17\n### Events\n#### Added\n- New and old but previously undocumented API rate and concurrency limits have been documented.\nOverrides have been specified for existing customers, so that the new limits would not affect them.\n - Service layer request rate and concurrency limits added.\n - CRUD endpoints request rate and concurrency and items rate limits added\n\n## 2023-10-10\n\n### Entity matching\n\n#### Added\n\n- Entity matching pipelines are now in v1. We resuscitated the old playground API and made some changes.\n We will keep the new v1 API in beta for the foreseeable future.\n\n### Vision (Contextualization)\n\n#### Added\n\n- 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.\n\n## 2023-10-05\n\n### Hosted extractors\n\n#### Added\n\n- Hosted extractors API (Beta)\n - Use the new [Hosted extractors](https://docs.cognite.com/cdf/integration/guides/extraction/hosted_extractors)\n feature to create simple streaming extractors running inside CDF, streaming data from sources available on the internet\n directly into CDF.\n Currently supports Azure Event Hub and MQTT. Support is planned for Kafka and REST APIs.\n\n## 2023-09-27\n\n### 3D\n\n#### Changed\n\n- 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.\n The previous behavior was to return an empty or partial items list in these cases.\n Before calling any 3d api nodes endpoints, clients should check that the model revision has \"status\":\"Done\".\n\n## 2023-08-25\n\n### Transformations\n\n#### Changed\n\n- Fixed wrong description for fields in \"transformations/update\" and \"/transformations/schedules/update\"\n\n## 2023-08-22\n\n### Functions\n\n#### Changed\n\n- Remove Functions runtime \"py37\".\n\n## 2023-08-22\n\n### Time series\n\n#### Added\n\n- Data point subscriptions (Beta)\n - Use the new [Data point subscriptions](https://developer.cognite.com/dev/concepts/data_point_subscriptions/)\n feature to configure a subscription to listen to changes in one or more\n time series (in ingestion order).\n The feature is intended to be used where data points consumers need to keep up to date with\n changes to one or more time series without the need to read the entire time series again. (Beta)\n\n## 2023-08-10\n\n### Time series\n\n#### Added\n\n- Advanced query language support reaches General Availability (GA).\n - Advanced search, filtering, and sorting capabilities in the [Filter time series](https://docs.cognite.com/api/20230101/#tag/Time-series/operation/listTimeSeries) endpoint.\n - Advanced aggregation capabilities in the [Aggregate time series](https://docs.cognite.com/api/20230101/#tag/Time-series/operation/aggregateTimeSeries) endpoint.\n\n### Sequences\n\n#### Added\n\n- Advanced query language support reaches General Availability (GA).\n - Advanced search, filtering, and sorting capabilities in the [Filter sequences](https://docs.cognite.com/api/20230101/#tag/Sequences/operation/advancedListSequences) endpoint.\n - Advanced aggregation capabilities in the [Aggregate sequences](https://docs.cognite.com/api/20230101/#tag/Sequences/operation/aggregateSequences) endpoint.\n\n## 2023-08-08\n\n### Assets\n\n#### Added\n\n- Advanced query language support reaches General Availability (GA).\n - Advanced search, filtering, and sorting capabilities in the [Filter assets](https://docs.cognite.com/api/20230101/#tag/Assets/operation/listAssets) endpoint.\n - Advanced aggregation capabilities in the [Aggregate assets](https://docs.cognite.com/api/20230101/#tag/Assets/operation/aggregateAssets) endpoint.\n\n### Events\n\n#### Added\n\n- Advanced query language support reaches General Availability (GA).\n - Advanced search, filtering, and sorting capabilities in the [Filter events](https://docs.cognite.com/api/20230101/#tag/Events/operation/advancedListEvents) endpoint.\n - Advanced aggregation capabilities in the [Aggregate events](https://docs.cognite.com/api/20230101/#tag/Events/operation/aggregateEvents) endpoint.\n\n### Documents\n\n#### Added\n\n- Advanced query language support reaches General Availability (GA).\n - Advanced aggregation capabilities in the [Aggregate documents](https://docs.cognite.com/api/20230101/#tag/Documents/operation/documentsAggregate) endpoint.\n\n## 2023-06-27\n\n### IAM (Identity and access management)\n\n#### Changed\n\n- 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.\n - The `oidcConfiguration.jwksUrl` and `oidcConfiguration.tokenUrl` can be entirely omitted when updating the OIDC configuration for a project.\n - 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.\n\n- 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`.\n\n- The `oidcConfiguration.isGroupCallbackEnabled` has been deprecated but remains part of the API for backwards compatibility. It can be omitted from the request.\n - 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`.\n\n## 2023-06-05\n\n### Data Modeling\n\n#### Added\n\n- Added support for an `autoCreateDirectRelations` option on the endpoint for ingesting instances.\nThis option lets the user specify whether to create missing target nodes of direct relations.\n\n#### Removed\n\n- Removed support for the deprecated per-item `sources` field on the `/instances/byids` endpoint.\n\n### Time series\n\n#### Added\n\n- Added advanced query language support (Beta).\n - Advanced search, filtering, and sorting capabilities in the [Filter time series](tag/Time-series/operation/listTimeSeries) endpoint.\n - Advanced aggregation capabilities in the [Aggregate time series](tag/Time-series/operation/aggregateTimeSeries) endpoint.\n\n### Sequences\n\n#### Added\n\n- Added advanced query language support (Beta).\n - Advanced search, filtering, and sorting capabilities in the [Filter sequences](tag/Sequences/operation/advancedListSequences) endpoint.\n - Advanced aggregation capabilities in the [Aggregate sequences](tag/Sequences/operation/aggregateSequences) endpoint.\n\n## 2023-05-19\n\n### Transformations\n\n#### Added\n\n- Adding support for data model centric and view centric schema.\n\n## 2023-04-24\n\n### Transformations\n\n#### Removed\n\n- Removing support for authentication via API keys when creating or updating transformations.\n\n## 2023-05-04\n\n### Annotations\n\n#### Added\n\n- 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.\n\n## 2023-04-18\n\n### All resources\n\n#### Added\n\n- Added information about [Requests throttling](section/Requests-throttling).\n\n#### Changed\n\n- Updated the [Parallel retrieval](section/Parallel-retrieval) documentation.\n- Aligned endpoint naming within Assets, Data sets, Events, and Files.\n\n### Assets\n\n#### Added\n\n- Added advanced query language support (Beta).\n - Advanced search, filtering, and sorting capabilities in the [Filter assets](https://docs.cognite.com/api/20230101-beta/#tag/Assets/operation/listAssets) endpoint.\n - Advanced aggregation capabilities in the [Aggregate assets](https://docs.cognite.com/api/20230101-beta/#tag/Assets/operation/aggregateAssets) endpoint.\n\n### Events\n\n#### Added\n\n- Added advanced query language support (Beta).\n - Advanced search, filtering, and sorting capabilities in the [Filter events](https://docs.cognite.com/api/20230101-beta/#tag/Events/operation/advancedListEvents) endpoint.\n - Advanced aggregation capabilities in the [Aggregate events](https://docs.cognite.com/api/20230101-beta/#tag/Events/operation/aggregateEvents) endpoint.\n\n### Documents\n\n#### Added\n\n- Added advanced query language support (Beta).\n - Advanced aggregation capabilities in the [Aggregate documents](https://docs.cognite.com/api/20230101-beta/#tag/Documents/operation/documentsAggregate) endpoint.\n\n## 2023-04-12\n\n### Sessions\n\n#### Fixed\n\n- Fixed the API documentation for the request body of the [POST /projects/{project}/sessions/byids](tag/Sessions/operation/getSessionsByIds) endpoint.\nThe 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.\n\n- Fixed the API documentation for the response body of the [POST /projects/{project}/sessions/byids](tag/Sessions/operation/getSessionsByIds) endpoint.\nThe 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.\n\n## 2023-04-04\n\n### Transformations\n\n#### Change\n\n- Transformations support new target types for view-centric data model instances.\n\n#### Added\n\n- Added target types `nodes` and `edges`.\n\n## 2023-03-06\n\n### Documents\n\n#### Change\n\n- Renamed \"approximateCardinality\" aggregate to \"cardinalityValues\" to unify the search spec in Cognite.\n- \"uniqueProperties\" aggregate no longer supports pagination. It returns unique properties (up to 10000) in the specified path. The results are sorted by frequency.\n\n#### Added\n\n- Added \"allUniqueProperties\" aggregate that returns all unique properties. The response contains a cursor that can be used to fetch all pages of data.\n\n## 2023-02-03\n\n### Seismic\n\n#### Added\n\n- 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.\n\n#### Fixed\n\n- 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.\n\n## 2023-02-07\n\n### Documents\n\n#### Added\n\n- Added `highlight` field in the `search` endpoint to indicate whether matches in search results should be highlighted.\n\n## 2023-01-18\n\n### 3D\n\n#### Added\n\n- Added support for using names filter in list nodes endpoint.\n\n## 2023-01-17\n\n### Authentication\n\n#### Removed\n\nWe've removed authentication via CDF service accounts and API keys, and user sign-in via `/login`.\n\n### 3D\n\n#### Added\n\n- Added support for storing translation and scale for model revision.\n\n## 2023-01-12\n\n### Documents\n\n#### Added\n\n- Added support for approximateCardinality aggregate.\n\n## 2023-01-10\n\n### Documents\n\n#### Added\n\n- Added the search leaf filter, to allow filtering by searching through specified properties.\n\n## 2023-01-09\n\n### Documents\n\n#### Added\n\n- Added the uniqueProperties aggregation, which can be used to find all the metadata keys in use.\n\n## 2023-01-06\n\n### Documents\n\n#### Added\n\n- Added inAssetSubtree filter to filter documents that have a related asset in a subtree rooted at any of the specified IDs.\n\n## 2023-01-02\n\n### Documents\n\n#### Added\n\n- Added advanced filters for metadata (prefix, in, equals)\n\n## 2022-12-06\n\n### 3D\n\n#### Added\n\n- Added get3DNodesById endpoint to be able to fetch 3D nodes mapped to an asset.\n\n## 2022-12-16\n\n### Time series\n\n#### Changed\n\n- 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.\n\n## 2022-11-29\n\n### Events\n\n#### Added\n\n- Added `nulls` field to the sort property specification\n\n## 2022-11-17\n\n### Time series\n\n#### Added\n\n- Added `nextCursor` field to [Retrieve data points](tag/Time-series/operation/getMultiTimeSeriesDatapoints), to support cursor pagination\n\n## 2022-10-14\n\n### Geospatial\n\n#### Added\n\n- Added the [POST /projects/{project}/geospatial/compute](tag/Geospatial/operation/compute) endpoint.\n\n## 2022-10-11\n\n### Transformations\n\n#### Added\n\n- Added capability to run a transformation with Nonce credentials provided through the Run endpoint.\n\n## 2022-10-06\n\n### IAM (Identity and access management)\n\n#### Added\n\n- Added the [POST /projects/{project}/sessions/byids](tag/Sessions/operation/getSessionsByIds) endpoint.\n\n## 2022-09-09\n\n### Vision (Contextualization)\n\n#### Added\n\n- Move Vision extract service from playground to V1.\n\n## 2022-08-12\n\n### Time series\n\n#### Changed\n\n- Updated datapoints timestamp range from 1971 - 2050 to 1900 - 2050.\n Affected endpoints:\n - [Insert data points](tag//Time-series/operation/postMultiTimeSeriesDatapoints)\n - [Retrieve data points](tag//Time-series/operation/getMultiTimeSeriesDatapoints)\n - [Delete data points](tag//Time-series/operation/deleteDatapoints)\n - [Retrieve latest data point](tag//Time-series/operation/getLatest)\n - [Synthetic query](tag//Synthetic-Time-Series/operation/querySyntheticTimeseries)\n\n## 2022-07-21\n\n### Transformations\n\n#### Added\n\n- Added authentication using nonce for transformation's exisiting endpoints.\n\n## 2022-06-21\n\n### Annotations (Data organization)\n\n#### Added\n\n- Moved the annotation service from playground to v1.\n\n## 2022-07-07\n\n### Events\n\n#### Removed\n\n- End-of-life for [filter.rootAssetIds](tag/Events/operation/advancedListEvents) filtering attribute.\n\n## 2022-06-13\n\n### IAM (Identity and access management)\n\n#### Added\n\n- Added the [POST /projects/{project}/sessions/revoke](tag/Sessions/operation/revokeSessions) endpoint.\n\n## 2022-05-20\n\n### Documents\n\n#### Added\n\n- 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.\n\n## 2022-05-12\n\n### Documents\n\n#### Added\n\n- Added the `POST /documents/list` endpoint. The endpoint allows you to iterate through all the documents in a project.\n- Added the `POST /documents/{documentId}/content` endpoint. The endpoint lets you download the entire extracted plain text of a document.\n\n## 2022-04-11\n\n### Documents\n\n#### Added\n\n- Added the [GET /documents/{documentId}/preview/image/pages/{pageNumber}](tag/Document-preview/operation/documentsPreviewImagePage) endpoint.\n- Added the [GET /documents/{documentId}/preview/pdf](tag/Document-preview/operation/documentsPreviewPdf) endpoint.\n- Added the [GET /documents/{documentId}/preview/pdf/temporarylink](tag/Document-preview/operation/documentsPreviewPdfTemporaryLink) endpoint.\n\n## 2022-03-15\n\n### Sequences\n\n#### Changed\n\n- 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.\n\n## 2022-03-02\n\n### Sequences\n\n#### Added\n\n- Added the [POST /sequences/data/latest](tag/Sequences/operation/getLatestSequenceRow) endpoint.\n\n## 2022-02-08\n\n### Time series\n\n#### Changed\n\n- Marked `isStep` parameter to be editable (i.e. removed description stating it is not updatable) in [POST /timeseries/create](tag/Time-series/operation/postTimeSeries).\n\n#### Added\n\n- Added `isStep` parameter to the `TimeSeriesPatch` object used in [POST /timeseries/update](tag/Time-series/operation/alterTimeSeries)\n\n## 2022-02-07\n\n### Documents\n\n#### Added\n\n- The [POST /documents/search](tag/Documents/operation/documentsSearch) endpoint now supports pagination.\n\n## 2022-01-25\n\n### Documents\n\n#### Added\n\n- Added the [POST /documents/search](tag/Documents/operation/documentsSearch) endpoint.\n\n## 2022-01-24\n\n### Time series\n\n#### Added\n\n- 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.\n\n## 2021-12-07\n\n### Transformations\n\n#### Added\n\n- New [Transformations](tag//Transformations) APIs to v1 to create,retrieve,list and delete transformations\n- New [Transformation Jobs](tag//Transformation-Jobs) APIs to v1 to retrieve and list transformation jobs or job metrics\n- New [Transformation Schedule](tag//Transformation-Schedules) APIs to v1 to manage schedules of transformations\n- New [Transformation Notifications](tag//Transformation-Notifications) APIs to v1 to manage notifications from transformation job\n\n## 2021-11-22\n\n### Contextualization\n\n#### Added\n\n- Added [diagram detect](tag/Engineering-diagrams/operation/diagramDetect) endpoint to v1 to detect annotations in engineering diagrams\n- Added [diagram detect results](tag/Engineering-diagrams/operation/diagramDetectResults) endpoint to v1 to get the results from an engineering diagram detect job\n- Added [diagram convert](tag/Engineering-diagrams/operation/diagramConvert) endpoint to v1 to create interactive engineering diagrams in SVG format with highlighted annotations\n- Added [diagram convert results](tag/Engineering-diagrams/operation/diagramConvertResults) endpoint to v1 to get the results for a job converting engineering diagrams to SVGs\n\n## 2021-11-17\n\n### 3D\n\n#### Added\n\n- Added `dataSetId` support to 3D models enabling data access scoping of 3D data\n\n## 2021-10-13\n\n### Raw\n\n#### Changed\n\n- To align with Microsoft Azure clusters, table and database names are now sensitive to trailing spaces also in Google Cloud Platform clusters.\n\n## 2021-10-05\n\n### Extraction Pipelines\n\n#### Added\n\n- 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.\n- 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).\n- 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.\n\n## 2021-09-28\n\n### Sequences\n\n#### Added\n\n- Added `partition` parameter to the [GET /sequences](tag/Sequences/operation/listSequences) endpoint to support [parallel retrieval](section/Parallel-retrieval).\n- [POST /sequences/list](tag/Sequences/operation/advancedListSequences) now supports [parallel retrieval](section/Parallel-retrieval).\n\n### Time series\n\n#### Added\n\n- Added `partition` parameter to the [GET /timeseries](tag/Time-series/operation/getTimeSeries) endpoint to support [parallel retrieval](section/Parallel-retrieval).\n\n## 2021-08-18\n\n### IAM (Identity and access management)\n\n#### Added\n\nAdded 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.\n\n## 2021-08-12\n\n### Relationships\n\n#### Added\n\n- Relationships now support [Parallel Retrieval](section/Parallel-retrieval)\n\n## 2021-07-01\n\n### 3D\n\n#### Added\n\n- Added filter3dNodes endpoint to allow for more advanced filtering on node metadata\n\n## 2021-06-29\n\n### Labels\n\n#### Added\n\n- [Dataset scoping](tag/Labels/operation/listLabels) based on `dataSetIds`.\n\n## 2021-06-08\n\n### Sequences\n\n#### Added\n\n- Added [syntax for updating columns](tag/Sequences/operation/updateSequences) of existing sequences. Can `remove` columns, `modify` existing columns, and `add` new columns as well.\n\n## 2021-06-01\n\n### Assets\n\n#### Added\n\n- Added labels replace (set) method for [assets update](tag/Assets/operation/updateAssets).\n\n## 2021-04-28\n\n### Time series\n\n#### Changed granularity limits on hour aggreagates\n\nYou can now ask for a [granularity](https://docs.cognite.com/dev/concepts/aggregation/#granularity)\nof up to 100000 hours (previously 48 hours), both in normal aggregates and in synthetic time series.\n\n## 2021-04-12\n\n### IAM (Identity and access management)\n\n#### Added\n\n- Added a [projects list](tag/Projects/operation/listProjects) endpoint to v1\n- Added a [token inspection](tag/Token/operation/inspectToken) endpoint to v1\n\n## 2021-04-06\n\n### Authentication\n\n#### Deprecated\n\nWe 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.\n\nThe 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.\n\nThe following API endpoints are deprecated:\n\n- `/api/v1/projects/*/apikeys`\n- `/api/v1/projects/*/serviceaccounts`\n- `/login`\n- `/logout`\n- `/api/v1/projects/*/groups/serviceaccounts` \\*\n\n\\*only the sub-resources for listing, adding, and removing members of groups.\n\n## 2021-03-22\n\nCDF API 0.5, 0.6 reached their end-of-life after its initial deprecation announcement in Summer 2019.\n\n## 2021-03-10\n\n### 3D\n\n#### Added\n\n- Added `partition` parameter to the List 3D Nodes endpoint for supporting parallel requests.\n- Added `sortByNodeId` parameter to the List 3D Nodes endpoint, improving request latency in most cases if set to `true`.\n\n## 2021-02-26\n\n### Entity matching\n\n#### Fixed\n\n- Fixed a bug in the documentation for Entity matching. The (job) `status` shall be capitalized string.\n\n## 2020-12-22\n\n### Files\n\n#### Added\n\n- New field `fileType` inside `derivedFields` to refer to a pre-defined subset of MIME types.\n- New filter `fileType` inside `derivedFields` to find files with a pre-defined subset of MIME types.\n\n## 2020-10-20\n\n### Files\n\n#### Added\n\n- New field `geoLocation` to refer to the geographic location of the file.\n- New filter `geoLocation` to find files matching a certain geographic location.\n\nTo learn how to leverage new geoLocation features, [follow our guide](https://developer.cognite.com/dev/concepts/resource_types/files.html).\n\n## 2020-08-29\n\n### Files\n\n#### Added\n\n- New field `directory` referring to the directory in the source containing the file.\n- New filter `directoryPrefix` allows you to find Files matching a certain directory prefix.\n\n## 2020-08-05\n\n### Files\n\n#### Added\n\n- New field `labels` allows you to attach labels to Files upon creation or updating.\n- New filter `labels` allows you to find Files that have been annotated with specific labels.\n\n## 2020-07-08\n\n### IAM (Identity and access management)\n\n#### Added\n\n- New project field `applicationDomains`. If this field is set, users only sign in to the project through applications hosted on\n a whitelisted domain. [Read more](https://developer.cognite.com/dev/guides/iam/#application-domains).\n\n## 2020-07-01\n\n### Events\n\n#### Added\n\n- New aggregation [`uniqueValues`](tag/Events/operation/aggregateEvents) allows you to find different types, subtypes of events in your project.\n\n## 2020-06-29\n\n### Labels\n\n#### Added\n\n- New data organization resource: [labels](tag//Labels). Manage terms that you can use to annotate and group assets.\n\n### Assets\n\n#### Added\n\n- New filter `labels` allows you to find resources that have been annotated with specific labels.\n\n### Time series\n\n#### Added\n\n- 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).\n\n## 2020-04-28\n\n### Events\n\n#### Added\n\n- New filtering capabilities to find open events [`endTime=null`](tag/Events/operation/advancedListEvents).\n- New filtering capabilities to find all events intersecting a timespan using [activeAtTime](tag/Events/operation/advancedListEvents).\n\n## 2020-03-12\n\n### General\n\n#### Added\n\n- 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.\n- New attribute `datasetId` introduced in assets, files, events, time series and sequences.\n- 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.\n- 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`.\n\n### Groups\n\n#### Added\n\n- Introduced a new capability: `datasetsAcl` for managing access to data set resources.\n- 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.\n\n## 2020-03-10\n\n### 3D\n\n#### Fixed\n\n- 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.\n\n## 2020-02-25\n\n### Assets\n\n#### Added\n\n- 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`.\n\n### Events\n\n#### Added\n\n- 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`.\n\n## 2020-02-12\n\n### Assets\n\n#### Added\n\n- We have added new aggregation properties: `depth` and `path`. You can use the properties in the filter and retrieve endpoints.\n\n## 2020-02-10\n\n### Assets\n\n#### Added\n\n- Added the property `parentExternalId` which is returned for all assets which have a parent with a defined `externalId`.\n\n## 2019-12-09\n\n### General\n\n#### Added\n\n- 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.\n\n## 2019-12-04\n\n### Assets\n\n#### Added\n\n- Added the ability to [filter](tag/Assets/operation/searchAssets) assets by parent external IDs.\n\n## 2019-11-18\n\n### Events\n\n#### Added\n\n- [Added the ability to filter events by the external ID of linked assets](tag/Events/operation/advancedListEvents)\n\n## 2019-11-12\n\n### Access control\n\n#### Removed\n\n- Groups can no longer be created with a permissions field in v0.5.\n\n## 2019-10-31\n\n### Assets\n\n#### Added\n\n- [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.\n\n### Time Series\n\n#### Changed\n\n- 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.\n\n## 2019-10-23\n\n### Files\n\n#### Added\n\n- Added support for updating the `mimeType` for existing files in files/update requests.\n\n## 2019-10-18\n\n### Time Series\n\n#### Added\n\n- Time series expanded their filtering capabilities with new `Filter time series` endpoint, allowing for additional filtering by:\n\n - Name\n - Unit\n - Type of time series: string or step series\n - Metadata objects\n - ExternalId prefix filtering\n - Create and last updated time ranges\n\n Endpoint in addition support pagination and partitioning. Check out detailed API documentation [here](/api/v1/#operation/listTimeSeries).\n\n## 2019-10-16\n\n### Events\n\n#### Added\n\n- [Added the ability to sort events on startTime, endTime, createdTime, and lastUpdatedTime](tag/Events/operation/advancedListEvents)\n\n## 2019-10-02\n\n### Sequences\n\n#### Added\n\n- 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).\n\n## 2019-09-30\n\n### 3D\n\n#### Added\n\n- Added endpoint to get multiple nodes for a 3D model by their IDs.\n- Added endpoint to get asset mappings for multiple node IDs or asset IDs.\n\n## 2019-09-23\n\n### Files\n\n#### Added\n\n- Added support for filter on `rootAssetIds` in files GET /files (using query parameter) and POST /files/list (in request body).\n\n## 2019-09-16\n\n### Assets and Events\n\n#### Added\n\n- Added support for `partition` in `/assets` and `/events` to support parallel retrieval. See guide for usage [here](./concepts/pagination)\n\n## 2019-08-22\n\n### 3D\n\n#### Added\n\n- 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.\n\n## 2019-08-21\n\n### Files\n\n#### Added\n\n- Added support for sourceCreatedTime and sourceModifiedTime fields in files v1 endpoints.\n\n### Assets\n\n#### Added\n\n- 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.\n- Support for ignoreUnknownIds when deleting assets.\n\n## 2019-08-15\n\n### 3D\n\n#### Added\n\n- Properties field for 3D nodes, extracted from uploaded 3D files.\n- Ability to filter nodes with a specific set of properties.\n\n## 2019-07-24\n\n### Files\n\n#### Changed\n\n- Allow lookup of names with length up to 256 characters (was 50) for GET /files and POST /files/search operations.\n- Allow creating and retrieving files with mimeType length up to 256 characters (was 64).\n\n## 2019-07-15\n\n### Time series\n\n#### Added\n\n- 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.\n\n## 2019-07-11\n\nList of changes for initial API v1 release in comparison to previous version - API 0.5\n\n### General\n\n#### Added\n\n- 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)\n- `externalIdPrefix` added as a parameter to the list events, assets and files operations.\n- Richer filtering on the list assets, files and events operations.\n- Search, list and filter operations for assets, events and files now support filtering on source and metadata field values.\n\n#### Changed\n\n- Core resources standardize on HTTP methods and URI naming for common operations such as search, partial updates, delete, list and filter\n- API responses are no longer wrapped in a top level `data` object.\n- Standardized pagination across resources through `limit`, `cursor` and `nextCursor` parameters.\n- The `limit` parameter no longer implicitly rounds down requested page size to maximum page size.\n- Standardized error responses and codes across all resources. Errors across CDF can be parsed into a single model.\n- Overall improvements to reference documentation. Including documented input constraints, required fields, individual attribute descriptions.\n\n#### Removed\n\n- The `sourceId` field has been removed from resources. Use `externalId` instead of `sourceId`+`source` to define unique IDs for data objects.\n- Sorting is removed from the search operations for files, assets, events and time series. Results are sorted by relevance.\n- `offset` and `previousCursor` parameters are no longer supported for pagination across resources.\n- Fetching an asset subtree is no longer supported by files, assets, events and time series.\n\n### Assets\n\n#### Added\n\n- Ability to select only root assets though new `root` filter.\n- Added the `rootId` field to specify the top element in an asset hierarchy.\n- Added the ability to filter by the root asset ID. This allows you to scope queries for one or many asset hierarchies.\n- List Assets allows for filtering assets belonging to set of root assets, specified by list of asset internal ids. New query parameter: `rootIds`.\n- 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`.\n\n#### Changed\n\n- Updating a single asset is no longer supported through a separate endpoint. Use the update multiple endpoint instead.\n- 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).\n\n#### Removed\n\n- Overwriting assets is no longer supported.\n- Filtering assets by their complete description is no longer supported.\n- Locating assets fuzzily by name has been removed. Instead, search for assets on the `name` property.\n- When searching assets, querying over both name and description in the same query is no longer supported.\n- The experimental query parameter `boostName` has been removed from the search for assets operation.\n- Removed the `path` and `depth` fields.\n\n### Events\n\n#### Added\n\n- Events can now be filtered on asset ID in combination with other filters.\n- New filter `rootAssetIds` allows for narrowing down events belonging only to list or specified root assets. Supported by Filter and Search API\n\n#### Removed\n\n- Events can no longer be filtered by empty description.\n- The 'dir' parameter has been removed from the search events operation.\n\n### Files\n\n#### Added\n\n- Filtering files by `assetIds` in list files operations now support multiple assets in the same request.\n\n#### Changed\n\n- Download file content has changed from HTTP GET to HTTP POST method.\n- We have renamed the `fileType` field to `mimeType`. The field now requires a MIME formatted string (e.g. `text/plain`).\n- We have renamed the `uploadedAt` field to `uploadedTime`.\n- Resumable is now the default behavior for file uploads.\n- Update metadata for single files is no longer supported by a separate operation. Instead, use the update multiple operation.\n\n#### Removed\n\n- Replace files metadata endpoint has been removed.\n- Directory has been removed as a property of files.\n- Updating the `name` or `mimeType` of a file through the update multiple files operation is no longer supported.\n- Query parameter for specifying the sort direction has been removed from list all files operations.\n\n### Raw\n\n#### Changed\n\n- Raw has changed structure to become resource-oriented. The URL structure has changed.\n- Recursively delete of tables and rows when deleting a database is now the default behavior without a control parameter.\n\n### Time series\n\n#### Added\n\n- Support for adding datapoints by `id` and `externalId` of time series. Adding datapoints to time series by `name` has been removed.\n- Add ability to update the new `externalId` attribute for time series.\n- Allow to set `externalId` during creation of time series. `ExternalId` requires uniqueness across time series.\n- Consolidate multiple APIs to allow adding datapoints into a single endpoint. Allows datapoints to be added to multiple time series at the same time.\n- Retrieve data points by using `id` and `externalId` of the time series.\n- 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.\n\n#### Changed\n\n- Get latest datapoints has been reworked. Introduces support for `id` and `externalId` lookup as well retrieval for multiple time series within the same request.\n- 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.\n- Delete time series endpoint has been redesigned to allow deletion of multiple time series by `id` and `externalId`.\n- 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.\n- Update multiple time series restructured to support lookup by `externalId`.\n- Retrieve time series by ID endpoint restructured adding the ability to get time series by `externalId`.\n- Set limit for data point value to min -1E100, max 1E100.\n\n#### Removed\n\n- Experimental feature for performing calculations across multiple time series (synthetic time series), function and alias attributes are no longer available.\n- The experimental query parameter `boostName` has been removed from search operation.\n- Short names for aggregate functions are no longer supported.\n- Ability to remove time series by `name` have been removed as names are no longer unique identifiers.\n- Select multiple time series and time ranges by `name` is no longer available.\n- The ability to update `isString` and `isStep` attributes is removed. The attributes are not intended to be modified after creation of time series.\n- The endpoint for updating single time series is removed. Use the update multiple time series endpoint instead.\n- Remove ability to overwrite time series object by `id`. Use the update multiple time series endpoint instead.\n- The ability to retrieve time series matching by `name` has been removed. Use `externalId` instead.\n- The ability to retrieve by `id` from a single time series has been removed. Use retrieve multiple datapoints for multiple time series instead.\n- The ability to retrieve time-aligned datapoints through \"dataframe\" API has been removed. Similar functionality is available through our supported SDKs.\n- The ability to add datapoints to time series by `name` has been removed.\n- The ability to look up by time series `name` has been removed.\n\n### IAM (Identity and access management)\n\n#### Added\n\n- The login status endpoint includes the ID of the API key making the request (new attribute: `apiKeyId`), if the request used an API key.\n\n#### Changed\n\n- The user resource type has been replaced with service accounts. Users from previous API versions are equivalent to service accounts.\n- Adding, listing and removing users from a group has been replaced by equivalent operations for service accounts.\n- Retrieve project returns a single object instead of a list.\n- API keys endpoints for list/create rename `userId` attribute to `serviceAccountId`.\n\n#### Removed\n\n- List and create groups no longer use the `permissions` and `source` attributes.\n\n### 3D\n\n#### Added\n\n- New 3D API lets you upload and process 3D models. Supported format: FBX.\n- Ability to create and maintain multiple revisions for the 3D models.\n- API for mapping relationships between 3D model nodes and asset hierarchy.\n" }, { "name": "Token", "description": "Access tokens issued by an IdP (Azure AD, Google, etc.) are used to access CDF resources.\n" }, { "name": "Assets", "description": "The assets resource type stores digital representations of objects or\ngroups of objects from the physical world. Assets are organized in hierarchies.\nFor example, a water pump asset can be a part of a subsystem asset on an\noil platform asset.\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as request per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits,\nfor all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response. More on limit types\nand how to avoid being throttled is described\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\nLimits are defined at both the overall API service level, and on the API endpoints belonging to the service.\\\nSome types of requests consume more resources (compute, storage IO) than others, and where a service handles\nmultiple concurrent requests with varying resource consumption.\nFor example, ‘CRUD’ type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete) are far less resource\nintensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource\nintensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\\\nThe version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\\\nThese limits are subject to change, pending review of changing consumption patterns and resource availability over time:\n\n\"\n\n### Translating RPS into data speed\nA single request may retrieve up to 1000 items. In the context of Assets, 1 item = 1 asset record\\\nTherefore, the maximum theoretical data speed at the top API service level is 200,000 items per second for all consumers,\nand 150,000 for a single identity or client in a project.\n\n### Use of Partitions / Parallel Retrieval\nAs a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a\nsingle request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the\nclient application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the\ncapacity limits defined for a given API service. For example (using the Assets API request budget):\n\n* A single request may retrieve up to 1000 items\n* Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints\n* This provides a theoretical maximum of 23,000 items read per second per identity\n* The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request\n* 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.\n\n**Important Note:**\nParallel retrieval should be only used in situations where, due to query complexity,\na single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\\\nParallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number\nof concurrent requests issued, the overall requests per second limit still applies.\\\nSo for example, a single request returning data at approximately 18,000 items per second will only\nbenefit from adding a second parallel request, the capacity of which goes somewhat wasted\nas 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).\n\nThis page contains the specifications for the 5 core data modeling resources:\n - Spaces\n - Instances (Nodes & Edges)\n - Containers\n - Views\n - Data Models\n", "x-uri-format-fragments": [] }, { "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).\nThe streams API lets you manage the streams that are used for storing records.\nWith the API you can create, list, retrieve, and delete streams, and view stream settings and statistics.\n\nA stream defines the data lifecycle,\nand not schema, type or source. Multiple different sets of data which have\nnothing in common can be put into the same stream, provided that settings of this stream\nfit lifecycle and usage patterns (volume, rate, etc) of the data involved.\n\nStreams can be either mutable or immutable, which affects how records can be modified,\nstorage capacity limits, and query performance characteristics.\n\nMutable streams allow records to be updated and deleted by the user. They provide\nconsistent low-latency access and optimal query performance.\nHowever, the total number of records that can be stored is limited. Mutable streams are\nwell-suited for use cases requiring frequent data access and updates.\n\nImmutable streams do not allow records to be updated or deleted by the user, but support\ningestion of very large amounts of data. Query performance may vary depending on the age\nof the data being accessed, as the system optimizes storage over time.\n\nTo delete all data in a stream, the stream itself should be deleted. To protect against irretrievable erroneous deletion,\nstreams are 'soft deleted' allowing them to be recovered for up to 6 weeks after the time of deletion.\nThe template used to create the stream determines the actual recovery time.\n\nA single project has a limited number of soft deleted streams at any given time. To avoid hitting this limit, please\navoid using any pattern of create and delete streams in a high frequency.\nPlease note that we expect streams to be long lived. The exception are streams created\nwith one of the `test` templates. Deleting a stream can take a long time.\nHow long depends on the stream settings and the volume of data stored.\nWhile a stream is soft deleted, it is not possible to recreate a stream with the same identifier as the deleted stream.\n\nOnce a stream is deleted, it does not count as one of the active streams, and more streams can be\ncreated to serve as active streams. If a stream is accidentally deleted, it is possible to recover\nthe data by contacting [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new).\nYou must contact Cognite no less than 1 week prior to the expiration of the stream retention period\nto ensure we can recover the data.\n\n## Available stream templates\n\n**Note: Stream Templates are in Beta**\n\nThe current Stream Templates are in beta. This means:\n- New templates may be added based on customer needs\n- Existing templates may be modified or removed if necessary\n- Such modifications will **not affect existing streams** created from these templates\n\nChoose your template carefully for production use, as templates cannot be changed after stream creation.\n\nThis section lists all currently available templates that can be used for creating streams.\n\n### Immutable streams\n\n#### ImmutableTestStream\n\nThis template should be used exclusively for experimentation. It is configured for high throughput\nand total data volume, but has a short data retention period. Low retention in a soft-deleted state\nmeans that such streams can be quickly discarded when no longer needed or recreated to remove the experimental data.\n\n**Note:** This template should never be used for production purposes. As this template\nallows significant load on the system, if we detect improper usage\npatterns, we can change setting of streams created from this template as a last resort.\n\n- Maximum total number of records - 50 M (50,000,000)\n- Maximum total data volume - 50 GB\n- Data retention - 7 days\n- Maximum ingestion throughput (per 10 minutes) - 1.5 GB\n- Maximum reading throughput (per 10 minutes) - 1.5 GB\n- Maximum records ingested (per 10 minutes) - 800,000 items\n- Maximum unique properties with data across all records - 1000\n- Maximum range filter interval for the `lastUpdatedTime` property - 7 days\n- Stream soft-delete retention (before hard delete) - 1 day\n- Maximum active streams per project - 3\n\n#### BasicArchive\n\nThis template is intended for perpetual storage of data. However, overall data volume\nis limited, which needs to be taken into account when planning usage.\n\n- Maximum total number of records - 50 M (50,000,000)\n- Maximum total data volume - 50 GB\n- Data retention - Unlimited (data never gets deleted)\n- Maximum ingestion throughput (per 10 minutes) - 170 MB\n- Maximum reading throughput (per 10 minutes) - 1.7 GB\n- Maximum records ingested (per 10 minutes) - 170,000 items\n- Maximum unique properties with data (across all records) - 1000\n- Maximum range filter interval for the `lastUpdatedTime` property - 365 days\n- Stream soft-delete retention (before hard delete) - 6 weeks\n- Maximum active streams per project - 2\n\n### Mutable streams\n\n#### BasicLiveData\n\nThis template is intended for production usage and offers significant data volume\nand throughput.\n\n- Maximum total number of records - 5 M (5,000,000)\n- Maximum total data volume - 15 GB\n- Maximum ingestion throughput (per 10 minutes) - 170 MB\n- Maximum reading throughput (per 10 minutes) - 500 MB\n- Maximum records ingested (per 10 minutes) - 170,000 items\n- Maximum records updated or deleted (per 10 minutes) - 85,000 items\n- Maximum unique properties with data (across all records) - 1000\n- Stream soft-delete retention (before hard delete) - 6 weeks\n- Maximum active streams per project - 1\n\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as request per second (‘**rps**’)) and the number of concurrent (parallel)\nrequests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response.\nSee [Resource throttling](https://docs.cognite.com/dev/concepts/resource_throttling) for limit types and how to avoid throttling.\n\nAs streams are intended to be long-lived, users are not expected to interact with these endpoints frequently.\n\nThe version limits for the streams endpoints are illustrated in the tables below.\nThese limits are subject to change, pending review of changing consumption patterns and resource availability over time:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Create and Delete request budget
OverallPer ID
Requests per second21
Concurrent requests11
\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Retrieve and List request budget
OverallPer ID
Requests per second53
Concurrent requests32
\n" }, { "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.\nRecords are shaped similarly to instances in the Data Modeling service, and their schema is defined by the containers referenced as sources.\nEach record is associated with a space. Space-based access control applies to records.\nThis section specifies the `records` resource and uses the following Data Modeling concepts:\n - [Spaces](https://docs.cognite.com/cdf/dm/dm_concepts/dm_spaces_instances#space)\n - [Containers](https://docs.cognite.com/cdf/dm/dm_concepts/dm_containers_views_datamodels#containers)\n\n**Note:** Every `record` has a required top-level `externalId` property, which can be used\nin some queries to retrieve or aggregate records (for filtering or sorting).\nFor mutable records, `externalId` (together with `space`) uniquely identifies a record for write operations (create, upsert, delete).\nFor immutable records, the records API does not enforce uniqueness of the `space` + `externalId` pair, so multiple records may share the same identifier.\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as requests per second, or ‘**rps**’) and the number of concurrent (parallel)\nrequests are governed by limits for all CDF API endpoints. If a request exceeds a limit,\nit 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.\n\nLimits apply to the API endpoints for this service.\nSome request types consume more resources (compute, storage I/O) than others. For example, ingest requests\nare less resource-intensive than analytical requests (Aggregate, Retrieve).\n\nLimits for query endpoints (Sync, Retrieve, Aggregate) are hierarchical:\n- All query endpoints share a common **Query request budget** (shown in the tables below)\n- The Retrieve endpoint has an **additional** dedicated budget that is checked first\n- The Aggregate endpoint has an **additional** dedicated budget that is checked first\n\nThe Sync endpoint only checks the Query request budget. The Retrieve and Aggregate endpoints\nmust pass both their dedicated budget check AND the Query request budget check.\n\nFor example, with mutable streams you can make up to 40 rps total across all query endpoints\n(Query budget limit), but only up to 20 of those can be Retrieve requests (Retrieve budget limit)\nand only up to 15 can be Aggregate requests (Aggregate budget limit).\nThat means you could send 20 Retrieve + 15 Aggregate + 5 Sync = 40 total RPS.\n\nQuery performance and rate limits vary between mutable and immutable streams because of\ntheir different storage characteristics.\n\nMutable streams provide consistent high-performance queries and higher rate limits\n(see \"mutable streams\" limits in the tables below).\n\nImmutable streams are optimized for ingesting very large amounts of data,\nwhich results in lower query performance and stricter rate limits than mutable streams\n(see \"immutable streams\" limits in the tables below).\n\nWhen designing data access patterns, use mutable streams for high-performance queries and higher rate limits, or immutable streams when the priority\nis high-volume ingestion and long-term storage.\n\nThe amount of data returned in responses from query endpoints (Sync, Retrieve, Aggregate)\nis also limited. Prefer reading only the data you need: use an appropriate `filter` and limit which `sources` are retrieved, rather than\nretrieving large result sets that you will not use.\n\nThe version limits for the records endpoints are shown in the tables below.\nThese limits are subject to change, pending review of consumption patterns and resource availability over time:\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Ingest request budget
OverallPer ID
Requests per second4030
Concurrent requests2015
\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Query request budget
OverallPer ID
Requests per second: mutable streams4030
Concurrent requests: mutable streams3022
Requests per second: immutable streams107
Concurrent requests: immutable streams107
Response MB per second43
\n\n

\n Additional dedicated budgets for Retrieve and Aggregate endpoints:\n

\n\n

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

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Retrieve request budget
OverallPer ID
Requests per second: mutable streams2015
Concurrent requests: mutable streams2015
Requests per second: immutable streams107
Concurrent requests: immutable streams107
\n\n

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

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Aggregate request budget
OverallPer ID
Requests per second: mutable streams1512
Concurrent requests: mutable streams107
Requests per second: immutable streams54
Concurrent requests: immutable streams54
\n\n

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

\n\n

\n Summary:\n

\n" }, { "name": "Events", "description": "Events objects store complex information about multiple assets over a time period.\nTypical types of events that would be stored in this service might include Alarms, Process Data, and Logs.\\\nFor the storage of low volume, manually generated, schedulable activities (such as maintenance schedules,\nwork orders or other ‘appointment’ type activities, the Data Modeling service is now recommended.\n\n#### Important Note:\nEvents and Time Series are somewhat closely related in that both are high volume types of data,\ncapable of recording data in microsecond resolutions. However, Events is not recommended as a Time Series store,\nsuch as where the data flow is from a single instance of sensors (i.e. temperature, pressure, voltage),\nsimulators or state machines (on, off, disconnected, etc).\\\nTime Series offers very low latency read and write performance, as well as specialised filters and aggregations that\nare tailored to the analysis of time series data.\n\nAn event’s time period is defined by a start time and end time, both millisecond timestamps since the UNIX epoch.\nThe timestamps can be in the future. In addition, events can have a text description as well as arbitrary metadata and properties.\\\nWhen storing event information in metadata, it should be considered that all data is stored as string format.\n\n#### Note:\nIn Events API, timestamps are treated as strings when added to\nmetadata fields and aren’t converted to the user’s local time zone.\n\n**Caveats:**\\\nDue to the eventually consistent nature of Asset IDs stored in Events,\nit should be noted that Asset ID references obtained from the Events API may\noccasionally be invalid (such as if an Asset ID is deleted,\nbut the reference to that ID remains in the Event record for a time).\n\nAsset references obtained from an event - through asset ids - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are maintained in an eventual consistent manner.\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as request per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits,\nfor all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response. More on limit types\nand how to avoid being throttled is described\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\nLimits are defined at both the overall API service level, and on the API endpoints belonging to the service.\\\nSome types of requests consume more resources (compute, storage IO) than others, and where a service handles\nmultiple concurrent requests with varying resource consumption.\nFor example, ‘CRUD’ type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete) are far less resource\nintensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource\nintensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\\\nThe version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\\\nThese limits are subject to change, pending review of changing consumption patterns and resource availability over time:\n\n\"\n\n### Translating RPS into data speed\nA single request may retrieve up to 1000 items. In the context of Events, 1 item = 1 event record\\\nTherefore, the maximum theoretical data speed at the top API service level is 200,000 items per second for all consumers,\nand 150,000 for a single identity or client in a project.\n\n### Use of Partitions / Parallel Retrieval\nAs a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a\nsingle request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the\nclient application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the\ncapacity limits defined for a given API service. For example (using the Events API request budget):\n\n* A single request may retrieve up to 1000 items\n* Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints\n* This provides a theoretical maximum of 23,000 items read per second per identity\n* The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request\n* 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.\n\n**Important Note:**\nParallel retrieval should be only used in situations where, due to query complexity,\na single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\\\nParallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number\nof concurrent requests issued, the overall requests per second limit still applies.\\\nSo for example, a single request returning data at approximately 18,000 items per second will only\nbenefit from adding a second parallel request, the capacity of which goes somewhat wasted\nas 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\nexample, a file can contain a piping and instrumentation diagram (P&IDs)\nshowing how multiple assets are connected.\n\nEach file is identified by the 'id' field, which is generated internally\nfor each new file. Each file's 'id' field is unique within a project.\n\nThe 'externalId' field is optional, but can also be used to identify a file.\nThe 'externalId' (if used) must be unique within a project.\n\nFiles are created in two steps; First the metadata is stored in a file\nobject, and then the file contents are uploaded. This means that files can\nexist in a non-uploaded state. The upload state is reflected in the 'uploaded'\nfield in responses.\n\nAsset references obtained from a file - through asset ids - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are maintained in an eventual consistent manner.\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as request per second, or ‘**rps**’) and the number of concurrent (parallel) requests are governed by limits,\nfor all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response. More on limit types\nand how to avoid being throttled is described\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\nLimits are defined at both the overall API service level, and on the API endpoints belonging to the service.\nSome types of requests consume more resources (compute, storage IO) than others, and where a service handles\nmultiple concurrent requests with varying resource consumption.\nFor example, ‘CRUD’ type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete and similar) are far less resource\nintensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource\nintensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\nThe version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\nThese limits are subject to change, pending review of changing consumption patterns and resource availability over time:\n\n\"\n\n### Translating RPS into data speed\nA single request may retrieve up to 1000 items. In the context of Files, 1 item = 1 file record\nTherefore, the maximum theoretical data speed at the top API service level is 160,000 items per second for all consumers,\nand 120,000 for a single identity or client in a project.\n\n### Use of Partitions / Parallel Retrieval\nAs a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a\nsingle request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the\nclient application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the\ncapacity limits defined for a given API service. For example (using the Files API request budget):\n\n* A single request may retrieve up to 1000 items\n* Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints\n* This provides a theoretical maximum of 23,000 items read per second per identity\n* The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request\n* 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.\n\n**Important Note:**\nParallel retrieval should be only used in situations where, due to query complexity,\na single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\nParallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number\nof concurrent requests issued, the overall requests per second limit still applies.\nSo for example, a single request returning data at approximately 18,000 items per second will only\nbenefit from adding a second parallel request, the capacity of which goes somewhat wasted\nas 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. \nThe 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\n> select customers. To request access, please reach out to your Cognite\n> contact or [Cognite Support](https://support.cognite.com/).\n\nCore operations for listing and retrieving Function Apps.\n" }, { "name": "Function App Calls", "description": "> **Private Beta:** This API is currently in private beta and available to\n> select customers. To request access, please reach out to your Cognite\n> contact or [Cognite Support](https://support.cognite.com/).\n\nInvoke Function App endpoints and view call history, responses, and logs.\n\nAll function invocations go through `POST /calls` with a `FunctionAppCallRequest`\nenvelope containing the target path, HTTP method, body, and session nonce.\n" }, { "name": "Function App MCP", "description": "> **Private Beta:** This API is currently in private beta and available to\n> select customers. To request access, please reach out to your Cognite\n> contact or [Cognite Support](https://support.cognite.com/).\n\n[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoints\nfor AI agent integration. Implements the\n[Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)\nwith [JSON-RPC 2.0](https://www.jsonrpc.org/specification) messaging\nand SSE streaming.\n\nNonce is passed per-call inside `params._meta[\"com.cognite/nonce\"]`\nfor methods that invoke the function (tools/list, tools/call, ping).\n" }, { "name": "3D", "description": "The CDF 3D API organizes 3D data into models and revisions.\nA model is just a container for a set of revisions. Revisions contains the actual 3D data.\nFor example you can have a model named `Compressor` and you can upload a revision under that model.\nWhen you create a revision you need to attach a file, which may be in 3D CAD or Point cloud format.\nFor every new version of the 3D model you upload a new revision under the model.\nYou can then easily track the history of a model by browsing the different revisions.\n\nWhen you upload a new revision the 3D API needs to process the 3D data to optimize it for rendering.\nThis can take some time. The Get3D api get revision endpoint provides a status string in the revision object.\nYou can then follow the process while you wait.\n\nA 3D CAD model is typically built up by a hierarchical structure.\nThis is related to the layout of the asset hierarchy in the Cognite Asset API.\nThe 3D API provides endpoints to extract the nodes from the 3D node hierarchy,\nand endpoints to make mappings from the 3D nodeIds to assetIds in the asset hierarchy.\nThe nodes are assigned an ID, nodeId, based on the node name and hierarchy.\nEach node in the 3D hierarchy gets a unique ID. This is the ID representing the object in the viewer.\nWhen a user click on a object in the 3D viewer it can returns the ID for the object that was clicked.\nYou can then use that ID to look up which node in the hierarchy the user clicked on.\n\nCognite also provides a [web based 3D viewer](https://www.npmjs.com/package/@cognite/reveal)\nto 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\nsingle asset. For example, a water pump asset can have a temperature time\nseries that records a data point in units of °C every second.\n\nA single asset can have several time series. The water pump could have additional time series\nmeasuring pressure within the pump, rpm, flow volume, power consumption, and more.Time\nseries store data points as either numbers or strings. This is controlled by the\nis_string flag on the time series object. Numerical data points can be aggregated\nbefore they are returned from a query (e.g., to find the average temperature for\na day). String data points, on the other hand, can't be aggregated by CDF but\ncan store arbitrary information like states (e.g., “open”/”closed”) or more complex\ninformation (JSON).\n\nCognite stores discrete data points, but the underlying\nprocess measured by the data points can vary continuously. When interpolating\nbetween data points, we can either assume that each value stays the same until\nthe next measurement or linearly changes between the two measurements.\nThe `isStep` flag controls this on the time series object. For example,\nif we estimate the average over a time containing two data points, the average\nwill either be close to the first (`isStep`) or close to the mean of the two (not\n`isStep`).\n\nA data point stores a single piece of information, a number or a\nstring, associated with a specific time. Data points are identified by their timestamps,\nmeasured in milliseconds since the unix epoch -- 00:00:00.000, January 1st, 1970.\nThe time series service accepts timestamps in the range from 00:00:00.000, January 1st, 1900\nthrough 23:59:59.999, December 31st, 2099 (in other words, every millisecond in the two\ncenturies from 1900 to but not including 2100). Negative timestamps are\nused to define dates before 1970. Milliseconds is the finest time resolution supported by CDF, i.e.,\nfractional milliseconds are not supported. Leap seconds are not counted.\n\nNumerical data points can be aggregated before they are retrieved from CDF. This allows for faster queries by reducing\nthe amount of data transferred. You can aggregate data points by specifying one\nor more aggregates (e.g., average, minimum, maximum) as well as the time granularity\nover which the aggregates should be applied (e.g., “1h” for one hour).\n\nAggregates are aligned to the start time modulo the granularity unit. For example, if you\nask for daily average temperatures since Monday afternoon last week, the first\naggregated data point will contain averages for Monday, the second for Tuesday,\netc. Determining aggregate alignment without considering data point timestamps\nallows CDF to pre-calculate aggregates (e.g., to quickly return daily average temperatures\nfor a year). Consequently, aggregating over 60 minutes can return a different\nresult than aggregating over 1 hour because the two queries will be aligned differently.\nAsset references obtained from a time series - through its asset ID - may be invalid simply\nby the non-transactional nature of HTTP. They are maintained in an eventually consistent\nmanner." }, { "name": "Data point subscriptions", "description": "A data point subscription is a way to listen to changes to time series data points, in ingestion order.\n\nA single subscription can listen to many time series, and a time series can be part of many subscriptions.\n\nYou listen to subscriptions by calling the “list subscription data“ endpoint. It will return\na list of data point upserts and deleted ranges, together with a cursor to retrieve the next\nbatch of updates. Updates written since the creation of the subscription, up to 7 days ago, can be\nretrieved through the subscription.\n\nSubscriptions can be defined explicitly through a list of time series external ids and\ninstance ids, or implicitly through a filter. The filter is a subset of the advanced filter\nquery in the regular “time series search“ endpoint.\n\nPartitions:\nSubscriptions can be further divided into a number of partitions, for the purpose of\nfetching subscription data in parallel. Each partition will return data in ingestion order,\nbut the order between partitions is not guaranteed.\n\nLimitations:\n- Each subscription can have at most 10000 time series.\n- A time series can be part of at most 10 subscriptions.\n- A project can have at most 1000 subscriptions, of which 100 are filter subscriptions.\n- Time series with security categories can not be shown in filter subscriptions.\n- Time series with neither external id nor instance id cannot be added to non-filter subscriptions.\n- The number of partitions cannot be changed after creation.\n\nAccess control:\nYou need READ access to subscriptions ACL to read/list\nsubscriptions or list data, and you need WRITE access to create/update/delete subscriptions.\nFurthermore, you need READ access to the time series you want to get updates from.\nFor filter subscriptions, you either need READ access to all time series, or the filter must\nbe restricted according to your access rights (e.g. by filtering on specific data set IDs).\n\nSubscriptions can have data sets that allow for more granular access\ncontrol. The data set on a subscription does not influence the data\nstream, but allows you to restrict who can read/update the subscription.\n\nName of ACL:\n `timeSeriesSubscriptionsAcl`\n\nSupported actions:\n - `READ`\n - `WRITE`\n\nExample capabilities:\n```\n[\n {\"timeSeriesAcl\":{\"actions\":[\"READ\"], \"scope\":{\"all\":{}}}},\n {\"timeSeriesSubscriptionsAcl\":{\"actions\":[\"WRITE\", \"READ\"], \"scope\":{\"all\":{}}}}\n]\n```" }, { "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.\n\nFor example can we use the expression `24 * TS{externalId='production/hour'}` to convert from hourly to daily production rates.\n\nBut STS is not limited to simple conversions.\n* We support combination of different time series `TS{id=123} + TS{externalId='hei'} / TS{space='data modeling space', externalId='dm id'}`.\n* Functions of time series `sin(pow(TS{id=123}, 2))`.\n* Aggregations of time series `TS{id=123, aggregate='average', granularity='1h'}+TS{id=456}`\n* Convert time series with `unitExternalId` to another unit `TS{externalId='temp_c', targetUnit='temperature:deg_f'}`.\n\nTo 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.\nEach 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.\nOnly queries on key are supported through this API.\\\n\n### Request and concurrency limits\n\nBoth the rate of requests and the number of concurrent (parallel) requests are governed by limits,\nfor all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response. More on limit types\nand how to avoid being throttled is described\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\nThe limits for the Raw service are described in the table below. Note that under high load,\nsome deviation from the limits might occur for short periods of time as the service is scaling up.\nThe `/rows` endpoints for inserting and retrieving data are governed by specific data rate limits.\n\n| Limit | Per project | Per user (identity) |\n|-----------------------|-----------------------|---------------------|\n| Concurrency | 64 parallel requests | 48 parallel requests|\n| Data rate (retrieve) | 8.3 GB / 10 minutes | 6.6 GB / 10 minutes |\n| Data rate (insert) | 1.6 GB / 10 minutes | 1.3 GB / 10 minutes |", "x-uri-format-fragments": [] }, { "name": "Groups", "description": "Groups are used to give principals the capabilities to access CDF resources.\nOne 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.\n\nGroups can either be managed through the external identity provider for the project or managed by CDF.\n- **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.\n- **Group Membership Managed within CDF**: Lets you see and edit group membership in CDF instead of relying on the external identity provider.\n" }, { "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.\n" }, { "name": "Security categories", "description": "Manage security categories for a specific project.\nSecurity categories can be used to restrict access to a resource.\nApplying a security category to a resource means that only principals (users or service accounts) that also have this security category can access the resource.\nTo learn more about security categories please read [this page](https://docs.cognite.com/api-reference/concepts/20230101/security-categories).\n" }, { "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.\n\n\nData 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.\n\n\nA 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.\n\n\nTo learn more about data sets, see [getting started guide](https://docs.cognite.com/cdf/data_governance/concepts/datasets/)" }, { "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.\n\nFor 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.\nTo learn more about sequences, see the [concept guide](https://docs.cognite.com/dev/concepts/resource_types/sequences).\n" }, { "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.\nEach 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.\nTo define and manage the available relationship types, use the labels resource type.\nThe 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**\nThis functionality is in beta. Callers need to provide the `cdf-version: beta` header to their requests.\n\nUsing Entity matching pipelines, you can configure re-runnable executions of entity matching.\nPipelines support expert knowledge (confirmed and/or rejected matches), regex rules (match rules), and entity\nmatching 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.\n\nThe 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.\n\nThis 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.\n\nAn agent includes prompts with instructions, industry-relevant tools, and access to industrial data stored in the Cognite Data Fusion (CDF) knowledge graph.\n\nA project can have a maximum of 30 agents. Each agent can have a maximum of 10 tools.\n\nFor more information about Atlas AI agents, see the [Atlas AI documentation](https://docs.cognite.com/cdf/atlas_ai/concepts/).\n ", "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": "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.\nEvery time a file is uploaded, updated or deleted in the Files API, it will also\nbe scheduled for processing by the document search engine. After some processing,\nit will be possible to search for the file in the document search API.\n\nThe document search engine is able to extract content from a variety of document\ntypes, and perform classification, contextualization and other operations on the\nfile. This extracted and derived information is made available in the form of a\n`Document` object.\n\nThe document structure consists of a selection of derived fields, such as the\n`title`, `author` and `language` of the document, plus some of the original fields\nfrom the raw file. The fields from the raw file can be found in the\n`sourceFile` structure. The derived fields are described in more detail below.\n\n### Derived fields\n\n#### title\nSome document types (such as PDFs) contain additional metadata fields. If the\ndocument contains its title as part of this metadata, this field will be populated\nwith that title.\n\nNote that we do not currently extract the title from the document content itself.\nIf there is a need for this, we may consider adding such functionality in the future.\n\n#### author\nSimilar to the `title` field, the author field is another field that can often be\nextracted from the document's metadata.\n\n#### producer\nThe `producer` field also exists in the document metadata. It contains information\nabout the software or the system that was used to create the document.\n\n#### createdTime\nThe `createdTime` we assign to the document is not exactly the same as the one found\nin the Files API. We first try to extract the created time from the document metadata.\nIf the document does not contain such a timestamp, we fall back to the time set in\nthe Files API.\n\n#### mimeType\nIf there is a mime type set in on the file in the Files API, this field will be set\nto the same mime type. If there is no mime type set on the file, we will try to\nauto-detect it.\n\n#### extension\nThis field contains the extension of the file, derived from the file name. For\ninstance, if the file name is `My Document.docx`, the `extension` field will contain\n`docx`.\n\n#### pageCount\nContains the number of pages in the document, if possible to determine.\n\n#### type\nThe `type` field contains a high level file type, derived from the mime type. Mime\ntypes are not that pleasant to look at, and not always easy to understand. That is\nwhy we map the mime types into more user-friendly types. Below is the list of types\ncurrently returned, but be aware that this list may be extended in the future.\n\n- `Document`: Document files from Microsoft Word or similar word processing software.\n- `PDF`: PDF files.\n- `Spreadsheet`: Files from Microsoft Excel or similar spreadsheet software.\n- `Presentation`: Slides from Microsoft Powerpoint or similar.\n- `Image`: Any kind of image such as PNG or JPG files.\n- `Video`: Any kind of video such as MOV or MP4 files.\n- `Tabular data`: Csv, tsv and other kinds of tabular data files.\n- `Plain text`: Plain text files.\n- `Compressed`: ZIP files and other kinds of compressed archive files.\n- `Script`: Program code such as python or matlab.\n- `Other`: Anything that doesn't fit in any of the above types.\n\n#### geoLocation\nIf there is a geolocation set on the file in the Files API, then this field will contain\nthe same geolocation. If there is no explicitly assigned geolocation, the document\nprocessing system will try to detect a location using two different techniques;\n\n1. We will extract locations from files that contain embedded GPS locations. Photos and\n videos often have this kind of metadata.\n2. We will look at related assets that have locations, and assign the same location(s) to\n the document.\n\n### File type support\n\nWe create a document for each uploaded file, but only derive data from certain files.\n\nThe following file types are eligible for further data extraction & enrichment:\n- PDF files\n- Spreadsheets, documents, and presentations from the Microsoft, Libre Office and macOS office suites\n- Plain text files\n- 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.\nThis can be very helpful if you want to display a preview of a file in a frontend, or for other\ntasks that require one of these formats.\n\nFor both rendered formats there is a concept of a page. The actual meaning of a page depends on\nthe source document. E.g. an image will always have exactly one page, while a spreadsheet\nwill typically have one page representing each individual sheet.\n\nThe document preview service can only generate preview for document sizes that do not\nexceed 150 MiB. Trying to preview a larger document will give an error.\n\n### File type support\nPreviews can be created for the following types of files:\n- PDF files\n- Spreadsheets, documents and presentations from the Microsoft and Libre Office office suites\n- Images" }, { "name": "Geospatial", "description": "The Geospatial API allows to model a problem domain when data has a geometric or geographic nature.\nThe 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.\nTo 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.\nSessions depend on the project OIDC configuration and may become invalid in the following cases\n- Project OIDC configuration has been updated through the [update project](#operation/updateProject)\n endpoint. This action invalidates all of the project's sessions.\n\n- The session was invalidated through the identity provider.\n" }, { "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.\nEach extractor has a list of releases, and each release may have a list of artifacts which are things like documentation PDFs, executables, and installers.\nExtractors may also be tied to source systems through solutions, representing concrete sources each extractor may connect to.\nThe 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\ndata from the CDF staging area, RAW, into the CDF data model.\n\n### Concurrency limits\n\nThe number of concurrent (parallel) jobs are governed by limits. If a request exceeds one of the limits,\nthe job fails to run. This limitation also applies to scheduled transformations.\n\nThe limits for the transformation service are described in the table below. Note that under high load,\nsome deviation from the limits might occur for short periods as the service scales up.\n\n| Limit | Per project |\n|-----------------------|-----------------------|\n| 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\npresent on the object itself. The benefits of the annotations concept are threefold:\n\n- The annotations concept is a good fit for enriching the base resources themselves, so that the overall data\n quality is higher in a given project.\n- It is also a good fit for building reference datasets for data problems uniformly across customer projects.\n Product teams can then use those reference datasets to train machine learning models or validate the\n performance of their algorithms on actual customer data.\n- Given a uniform way of labelling similar concepts across projects, it becomes easy for apps to agree on a consistent\n visual representation of those concepts." }, { "name": "User profiles", "description": "User profiles is an authoritative source of core user profile information (email,\nname, job title, etc.) for principals based on data from the identity provider\nconfigured for the CDF project.\n\nUser profiles are first created (usually within a few seconds) when a principal issues\na request against a CDF API. We currently don't support automatic exchange of user identity\ninformation between the identity provider and CDF, but the profile data is updated regularly\nwith the latest data from the identity provider for the principals issuing requests against\na CDF API.\n\nNote:\n- Do not use other fields than `userIdentifier` (e.g. email) to uniquely identify a\nprincipal. User profile data is mutable and is not guaranteed to be stable or unique (except\n`userIdentifier`).\n- Do not use user profile data for authentication or authorization purposes. It is not\nguaranteed to be under the strict governance necessary for that. For example, one should not\nuse email address as proof of identity or job title to give access to resources.\n- We strongly recommend _against_ storing any user profile data. It is intended for display\npurposes only and may update at any time. Clients should fetch user profile data at demand,\nand optionally cache for performance reasons.\n" }, { "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.\nA 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.\nMultiple 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.\nPreviews require a source, but not a mapping or a destination.\nThis 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).\n\nThe 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\n" }, { "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\ncontains all the information this API service needs to connect to an SAP S/4HANA destination.\n\nSupported SAP S/4HANA versions:\n* SAP S/4HANA OnPremise 2021 FPS01, and later\n* 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.\nIt defines which SAP Instance destination and which schema mapping should be used when processing a writeback request.\n\nSupported SAP entities:\n* [Maintenance Notifications](https://api.sap.com/api/OP_API_MAINTNOTIFICATION/overview)\n* [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.\n\nEach 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.\n\n#### Limitations:\n\n- A project can have a maximum of 100 simulators\n" }, { "name": "Simulator Integrations", "description": "\n\nThe 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.\n\n#### Limitations:\n\n- A project can have a maximum of 20 simulator integrations\n" }, { "name": "Simulator Routines", "description": "\n\nThe simulator routine resource defines instructions on interacting with a simulator model. A simulator routine includes:\n- Inputs (values set into the simulator model)\n- Commands (actions to be performed by the simulator)\n- Outputs (values read from the simulator model)\n\nSimulator 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.\n\n#### Limitations:\n\n- A project can have a maximum of 10000 simulator routines.\n- Each simulator model can have a maximum of 10 simulator routines.\n- Each simulator routine can have a maximum of 10 revisions.\n- The total size of each routine revision can be a maximum of 50.00 KB.\n" }, { "name": "Simulator Models", "description": "\n\nThe 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.\nThe 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.\n\nSimulator 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.\n\n#### Limitations:\n\n- A project can have a maximum of 1000 simulator models.\n- Each simulator model can have a maximum of 200 revisions.\n" }, { "name": "Simulation Runs", "description": "\nEvery 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.\n\nSimulation 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.\n\nWhen 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.\nWithout load balancing, the run initiates with status `ready` and is tied to the simulator integration specified on the routine.\n\n#### Limitations:\n\n- A retention policy is in place for simulation runs, allowing up to 100000 entries.\n When this limit is reached, the oldest runs are deleted to make room for new ones.\n- The total size of all inputs for a simulation run can be a maximum of 50.00 KB.\n- The total size of simulation run data sent by the connector can be a maximum of 100.00 KB.\n" }, { "name": "Simulator Logs", "description": "\nSimulator logs track what happens during simulation runs, model parsing, and generic connector logic. They provide valuable information for monitoring, debugging, and auditing.\n\nSimulator 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.\n\n#### Limitations:\n- A retention policy allows up to 10000 log entries per logId.\n When this limit is reached, the oldest logs are deleted to make room for new ones.\n" }, { "name": "Units", "description": "Units Catalog API provides a standardized list of units that can be used in Cognite Data Fusion.\nThe 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.\nThis 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.\n\nAn organization holds users, projects, and perhaps other organizations. The organization ID is what the users enter\nwhen logging into Cognite apps, such as Cognite Data Fusion. The organization has one IdP configuration, which is used\nfor both interactive login and service account authentication against all projects in the organization.\n\n### External identity providers (IdP)\nCDF supports interfacing with external IdPs to manage users and groups. The following vendors are supported:\n- Microsoft Entra ID (formerly known as Azure AD or Azure Active Directory)\n- Auth0\n- Keycloak\n\n### Users\nIf a user can log into the external IdP configured for the organization, then they have access to the CDF organization.\nWhich of the organization's projects they have access to, and what they may do inside those projects, is determined by\nthe access settings within each project.\n\nAfter a user has logged into the organization for the first time, they will be visible in the organization's user list.\nUsers can see each other, which enables them to collaborate on projects.\n\n### Organization hierarchy\nAn organization can have child organizations. The ownership relationship is materialized through the `parentId`\nfield of the organization resource.\n\n### Projects\nAn organization holds CDF projects. The users that are logged into the organization can see all the projects in the\norganization, but what they can actually do within each project is controlled by the project's access control lists\n(ACLs) and other access control settings.\n\n### Allowed clusters\nAn organization has a list of clusters on which it can hold projects. This is the `allowedClusters` field on the\nresource.\n\n### Organization admins\nAn organization can have admins, which are identified principals that can perform an extended set of modifications on\nthe organization, such as creating projects, changing who the admins are, and so on.\n\nAdmins are identified by the `adminGroupId` field on the organization resource, which is the ID of a group that is\nmanaged in the external IdP.\n\nThe different organization API endpoints have different access rules, which are documented under each endpoint.\nThe general rule is that admins of a given organization have control over most aspects of the organization itself\nand full control of any sub-organizations.\n\n### Authentication for this API\nOrganizations are global, which means that they are not tied to specific projects or clusters.\nAPI requests against organizations are directed to `auth.cognite.com`, instead of a specific cluster and projects\nas for other resources.\n\nOnly OAuth tokens issued by `https://auth.cognite.com` (such as the ones issued when logging into Fusion) are accepted\nby the organizations API.\n\nIt is also possible to obtain a token by initiating a login flow against the authorization server directly. See\nthe \"Authorizations\" sections for more information.\n" }, { "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, \nauthenticated, and authorized in CDF. Principals are unique within an organization, and therefore also within a project in the \norganization. Principals can access data and create and run processes (transformations, Functions) in a CDF project.\n\n* A **user account** is associated with a **person** who wants to interact with CDF. Each user account has a user \nprofile containing a unique user ID.\n* A **service account** is associated with an **application** or **process** that wants to interact with CDF, such as \nan extractor or Cognite Functions, rather than a person.\n\n## Authentication for this API\nRequests to the Principals API are directed to `auth.cognite.com`, like for organizations.\n\nOnly OAuth tokens issued by `https://auth.cognite.com` (such as the ones issued when logging into Fusion) are accepted\nby the Principals API.\n\nIt is also possible to obtain a token by initiating a login flow against the authorization server directly. See\nthe \"Authorizations\" sections for more information.\n\n## User Accounts\nThe Principals API lets you query user accounts in an organization, and retrieve profiles.\n" }, { "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.\nSubscriptions 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.\n\n **Key characteristics:**\n - **Clear ownership**: Defined data product owners with explicit access roles and accountability\n - **Rich metadata**: Comprehensive data modeling views, usage terms, access permissions, and descriptive documentation\n - **Self-service consumption**: Discoverable and well-documented for autonomous data consumer access\n - **Version management**: Immutable data modeling view versions with governed schemas and updatable metadata\n\n 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.\n\n **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.\n" } ], "paths": { "/token/inspect": { "get": { "servers": [ { "url": "https://{cluster}.cognitedata.com/api/v1", "description": "The URL for the CDF cluster to connect to", "variables": { "cluster": { "description": "The CDF cluster to connect to", "default": "api", "enum": [ "api", "az-tyo-gp-001", "az-eastus-1", "az-power-no-northeurope", "westeurope-1", "asia-northeast1-1", "gc-dsm-gp-001" ] } } } ], "x-capability": [ "projectsAcl:LIST", "groupsAcl:LIST" ], "tags": [ "Token" ], "summary": "Inspect", "description": "\n\n> **Required capabilities:** `projectsAcl:LIST` `groupsAcl:LIST`\n\nInspect CDF access granted to an IdP issued token", "operationId": "inspectToken", "responses": { "200": { "description": "Ok response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInspectionResponse" } } } }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/assets": { "get": { "tags": [ "Assets" ], "summary": "List assets", "description": "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nList all assets, or only the assets matching the specified query.\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "getAssets", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IncludeMetadata" }, { "in": "query", "name": "name", "schema": { "$ref": "#/components/schemas/AssetName" } }, { "in": "query", "name": "parentIds", "description": "List only assets that have one of the parentIds as a parent. The parentId for root assets is null.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "parentExternalIds", "description": "List only assets that have one of the parentExternalIds as a parent. The parentId for root assets is null.", "example": "[externalId_1, externalId_2, externalId_3]", "schema": { "$ref": "#/components/schemas/JsonArrayString" } }, { "in": "query", "name": "rootIds", "description": "This parameter is deprecated. Use assetSubtreeIds instead. List only assets that have one of the rootIds as a root asset. A root asset is its own root asset.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "deprecated": true, "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "assetSubtreeIds", "description": "List only assets that are in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "assetSubtreeExternalIds", "description": "List only assets that are in a subtree rooted at any of these assetExternalIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.", "example": "[externalId_1, externalId_2, externalId_3]", "schema": { "$ref": "#/components/schemas/JsonArrayString" } }, { "in": "query", "name": "source", "schema": { "maxLength": 128, "type": "string", "description": "The source of the asset, for example which database it's from." } }, { "in": "query", "name": "root", "schema": { "type": "boolean", "default": false, "description": "Whether the filtered assets are root assets, or not. Set to True to only list root assets." } }, { "in": "query", "name": "minCreatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxCreatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minLastUpdatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxLastUpdatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "externalIdPrefix", "schema": { "$ref": "#/components/schemas/CogniteExternalIdPrefix" } }, { "$ref": "#/components/parameters/partitionLimited10" } ], "responses": { "200": { "$ref": "#/components/responses/AssetDataWithCursorResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = await client.assets.list({ filter: { name: '21PT1019' } });" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.filter(filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.filter(\n filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\nasset_list = client.assets.list(limit=5)\n\nfor asset in client.assets:\n asset # do something with the asset\n\nfor asset_list in client.assets(chunk_size=2500):\n asset_list # do something with the assets\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"PUMP\", \"VERIFIED\"])\nasset_list = client.assets.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.list(\n advanced_filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.assets.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" } ] }, "post": { "tags": [ "Assets" ], "summary": "Create assets", "description": "\n\n> **Required capabilities:** `assetsAcl:WRITE`\n\nCreate multiple asset objects in the same project.\nIt is possible to create a maximum of 1000 assets per request.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "createAssets", "requestBody": { "description": "List of the assets to create. You can create a maximum of 1000 assets per request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExternalAsset" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/AssetDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = [\n { name: 'First asset' },\n { name: 'Second asset', description: 'Another asset', externalId: 'anotherAsset' },\n { name: 'Child asset', parentExternalId: 'anotherAsset'},\n];\nconst createdAssets = await client.assets.create(assets);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import AssetWrite\nassets = [AssetWrite(name=\"asset1\"), AssetWrite(name=\"asset2\")]\nres = client.assets.create(assets)\n\nfrom cognite.client.data_classes import AssetWrite, Label\nasset = AssetWrite(name=\"my_pump\", labels=[Label(external_id=\"PUMP\")])\nres = client.assets.create(asset)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertAssetsList = List.of(Asset.newBuilder()\n .setExternalId(\"10\")\n .setName(\"generated_asset_\")\n .setDescription(\"generated_asset_description_\")\n .setSource(\"sdk-data-generator\")\n .putMetadata(\"type\", \"sdk-data-generator\")\n .build()); \nList upsertedAssets = client.assets().upsert(upsertAssetsList); \n\n" } ] } }, "/assets/{id}": { "get": { "tags": [ "Assets" ], "summary": "Retrieve an asset by its ID", "description": "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nRetrieve an asset by its internal ID. If you want to retrieve assets by externalIds, use Retrieve assets instead.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "getAsset", "parameters": [ { "$ref": "#/components/parameters/CogniteInternalId" } ], "responses": { "200": { "$ref": "#/components/responses/AssetResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = await client.assets.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.assets.retrieve(id=1)\n\nres = client.assets.retrieve(external_id=\"1\")\n" } ] } }, "/assets/list": { "post": { "tags": [ "Assets" ], "summary": "Filter assets", "description": "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nRetrieve a list of assets in the same project. This operation supports pagination by cursor.\nApply Filtering and Advanced filtering criteria to select a subset of assets.\n\n### Advanced filtering\nAdvanced filter lets you create complex filtering expressions that combine simple operations,\nsuch as `equals`, `prefix`, `exists`, etc., using boolean operators `and`, `or`, and `not`.\nIt applies to basic fields as well as metadata.\n\nSee the `advancedFilter` attribute in the example.\n\nSee more information about filtering DSL [here](https://docs.cognite.com/dev/concepts/resource_filtering_dsl/ \"filtering DSL\").\n\n#### Supported leaf filters\n\n| Leaf filter | Supported fields | Description |\n|----------------|------------------------------------|--------------|\n| `containsAll` | Array type fields | Only includes results which contain all of the specified values.
`{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values.
`{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value.
`{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has value).
`{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values.
`{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified value.
`{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range.
`{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}`
Supported operators: `gt`, `lt`, `gte`, `lte` |\n| `search` | `[\"name\"]`, `[\"description\"]` | Introduced to provide functional parity with /assets/search endpoint.
`{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n##### Search\nThe `search` leaf filter provides functional parity with the `/assets/search` endpoint.\nIt's available only for the `[\"description\"]` and `[\"name\"]` properties. When specifying only this filter with no explicit ordering,\nbehavior is the same as of the `/assets/search/` endpoint without specifying filters.\nExplicit sorting overrides the default ordering by relevance.\nIt's possible to use the `search` leaf filter as any other leaf filter for creating complex queries.\n\nSee the `search` filter in the `advancedFilter` attribute in the example.\n\n#### advancedFilter attribute limits\n- filter query max depth: 10\n- filter query max number of clauses: 100\n- `and` and `or` clauses must have at least one element\n- `property` array of each leaf filter has the following limitations:\n - number of elements in the array is in the range [1, 2]\n - elements must not be blank\n - each element max length is 128 symbols\n - property array must match one of the existing properties (static or dynamic metadata).\n- `containsAll`, `containsAny`, and `in` filter `values` array size must be in the range [1, 100]\n- `containsAll`, `containsAny`, and `in` filter `values` array must contain elements of a primitive type (number, string)\n- `range` filter must have at least one of `gt`, `gte`, `lt`, `lte` attributes.\n But `gt` is mutually exclusive to `gte`, while `lt` is mutually exclusive to `lte`.\n At least one of the bounds must be specified.\n- `gt`, `gte`, `lt`, `lte` in the `range` filter must be a primitive value\n- `search` filter `value` must not be blank and the length must be in the range [1, 128]\n- filter query may have maximum 2 search leaf filters\n- maximum leaf filter string value length is different depending on the property the filter is using:\n - `externalId` - 255\n - `name` - 128 for the `search` filter and 255 for other filters\n - `description` - 128 for the `search` filter and 255 for other filters\n - `labels` item - 255\n - `source` - 128\n - any `metadata` key - 128\n\n### Sorting\nBy default, assets are sorted by `id` in the ascending order.\nUse the `search` leaf filter to sort the results by relevance.\nSorting by other fields can be explicitly requested. The `order` field is optional\nand defaults to `desc` for `_score_` and `asc` for all other fields.\nThe `nulls` field is optional and defaults to `auto`. `auto` is translated to\n`last` for the `asc` order and to `first` for the `desc` order by the service.\nPartitions are done independently of sorting; there's no guarantee of the sort order between elements from different partitions.\n\nSee the `sort` attribute in the example.\n\n#### Null values\nIn case the `nulls` attribute has the `auto` value or the attribute isn't specified,\nnull (missing) values are considered to be bigger than any other values.\nThey are placed last when sorting in the `asc` order and first when sorting in `desc`.\nOtherwise, missing values are placed according to the `nulls` attribute (last or first), and their placement doesn't depend on the `order` value.\nValues, such as empty strings, aren't considered as nulls.\n\n#### Sorting by score\nUse a special sort property `_score_` when sorting by relevance.\nThe more filters a particular asset matches, the higher its score is. This can be useful,\nfor example, when building UIs. Let's assume we want exact matches to be be displayed above matches by\nprefix as in the request below. An asset named `pump` will match both `equals` and `prefix`\nfilters and, therefore, have higher score than assets with names like `pump valve` that match only `prefix` filter.\n\n```\n\"advancedFilter\" : {\n \"or\" : [\n {\n \"equals\": {\n \"property\": [\"name\"],\n \"value\": \"pump\"\n }\n },\n {\n \"prefix\": {\n \"property\": [\"name\"],\n \"value\": \"pump\"\n }\n }\n ]\n},\n\"sort\": [\n {\n \"property\" : [\"_score_\"]\n }\n]\n```\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "listAssets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListScope" } } } }, "responses": { "200": { "$ref": "#/components/responses/AssetDataWithCursorResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = await client.assets.list({ filter: { name: '21PT1019' } });" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.filter(filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.filter(\n filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\nasset_list = client.assets.list(limit=5)\n\nfor asset in client.assets:\n asset # do something with the asset\n\nfor asset_list in client.assets(chunk_size=2500):\n asset_list # do something with the assets\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"PUMP\", \"VERIFIED\"])\nasset_list = client.assets.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.list(\n advanced_filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.assets.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listAssetsResults = new ArrayList<>(); \nclient.assets() \n .list() \n .forEachRemaining(listAssetsResults::addAll); \n\n \nclient.assets() \n .list(Request.create() \n .withFilterParameter(\"source\", \"source\")) \n .forEachRemaining(listAssetsResults::addAll); \n\n" } ] } }, "/assets/aggregate": { "post": { "tags": [ "Assets" ], "summary": "Aggregate assets", "description": "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nThe aggregation API lets you compute aggregated results on assets,\nsuch as getting the count of all assets in a project, checking\ndifferent names and descriptions of assets in your project, etc.\n\n#### Aggregate filtering\n##### Filter (filter & advancedFilter) data for aggregates\nFilters behave the same way as for the `Filter assets` endpoint.\nIn text properties, the values are aggregated in a case-insensitive manner.\n\n##### aggregateFilter to filter aggregate results\n`aggregateFilter` works similarly to `advancedFilter` but always applies to aggregate properties.\nFor instance, in case of an aggregation for the `source` property, only the values (aka buckets) of the `source` property can be filtered out.\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\\\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "aggregateAssets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetAggregateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/AggregateResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const aggregates = await client.assets.aggregate({ filter: { root: true } });\nconsole.log('Number of root assets: ', aggregates[0].count)" }, { "lang": "Python", "label": "Python SDK", "source": "aggregate_by_prefix = client.assets.aggregate(filter={\"external_id_prefix\": \"prefix\"})\nfrom cognite.client.data_classes.assets import AssetProperty\nkey_count = client.assets.aggregate_cardinality_properties(AssetProperty.metadata)\nfrom cognite.client.data_classes.assets import AssetProperty\nlabel_count = client.assets.aggregate_cardinality_values(AssetProperty.labels)\n\nfrom cognite.client.data_classes.filters import Search\nfrom cognite.client.data_classes.assets import AssetProperty\nis_critical = Search(AssetProperty.description, \"critical\")\ncritical_assets = client.assets.aggregate_cardinality_values(\n AssetProperty.metadata_key(\"timezone\"),\n advanced_filter=is_critical)\ncount = client.assets.aggregate_count()\n\nfrom cognite.client.data_classes.filters import ContainsAny\nfrom cognite.client.data_classes.assets import AssetProperty\nhas_timezone = ContainsAny(AssetProperty.metadata, \"timezone\")\nasset_count = client.assets.aggregate_count(advanced_filter=has_timezone)\nfrom cognite.client.data_classes.assets import AssetProperty\nresult = client.assets.aggregate_unique_properties(AssetProperty.metadata)\nfrom cognite.client.data_classes.assets import AssetProperty\nresult = client.assets.aggregate_unique_values(AssetProperty.metadata_key(\"timezone\"))\nprint(result.unique)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty\nfrom cognite.client.utils import timestamp_to_ms\nfrom datetime import datetime\ncreated_after_2020 = filters.Range(AssetProperty.created_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.assets.aggregate_unique_values(AssetProperty.labels, advanced_filter=created_after_2020)\nprint(result.unique)\n\nfrom cognite.client.data_classes.assets import AssetProperty\nfrom cognite.client.data_classes import aggregations\nfrom cognite.client.data_classes import filters\nnot_test = aggregations.Not(aggregations.Prefix(\"test\"))\ncreated_after_2020 = filters.Range(AssetProperty.last_updated_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.assets.aggregate_unique_values(AssetProperty.labels, advanced_filter=created_after_2020, aggregate_filter=not_test)\nprint(result.unique)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Aggregate aggregateResult = client.assets() \n .aggregate(Request.create().withFilterParameter(\"source\", \"\")); \n\n" } ] } }, "/assets/byids": { "post": { "tags": [ "Assets" ], "summary": "Retrieve assets", "operationId": "byIdsAssets", "description": "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nRetrieve assets by IDs or external IDs.\nIf you specify to get aggregates, then be aware that the aggregates are eventually consistent.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "requestBody": { "description": "All provided IDs and external IDs must be unique.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDataIds" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/AssetDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = await client.assets.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.assets.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.assets.retrieve_multiple(external_ids=[\"abc\", \"def\"], ignore_unknown_ids=True)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList retrievedAssets = client.assets().retrieve(byExternalIds);// by list of items \nList retrievedAssets = client.assets().retrieve(\"10\", \"20\");// by varargs of String \n\nList byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList retrievedAssets = client.assets().retrieve(byInternalIds);// by list of items \nList retrievedAssets = client.assets().retrieve(10, 20);// by varargs of Long \n\n" } ] } }, "/assets/update": { "post": { "tags": [ "Assets" ], "summary": "Update assets", "description": "\n\n> **Required capabilities:** `assetsAcl:WRITE`\n\nUpdate the attributes of assets.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "updateAssets", "requestBody": { "description": "All provided IDs and external IDs must be unique. Fields that aren't included in the request aren't changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataAssetChange" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/AssetDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = await client.assets.update([{id: 123, update: {name: {set: 'New name'}}}]);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import AssetUpdate\nmy_update = AssetUpdate(id=1).description.set(\"New description\").metadata.add({\"key\": \"value\"})\nres1 = client.assets.update(my_update)\nanother_update = AssetUpdate(id=1).description.set(None)\nres2 = client.assets.update(another_update)\n\nfrom cognite.client.data_classes import AssetUpdate\nmy_update = AssetUpdate(id=1).metadata.add({\"key\": \"value\"})\nres1 = client.assets.update(my_update)\nanother_update = AssetUpdate(id=1).metadata.set(None)\nanother_update2 = AssetUpdate(id=1).metadata.set({})\nres2 = client.assets.update(another_update)\n\nfrom cognite.client.data_classes import AssetUpdate\nmy_update = AssetUpdate(id=1).labels.add([\"PUMP\", \"VERIFIED\"])\nres = client.assets.update(my_update)\n\nfrom cognite.client.data_classes import AssetUpdate\nmy_update = AssetUpdate(id=1).labels.remove(\"PUMP\")\nres = client.assets.update(my_update)\n\nfrom cognite.client.data_classes import AssetUpdate\nmy_update = AssetUpdate(id=1).labels.set(\"PUMP\")\nres = client.assets.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertedAssets = client.assets().upsert(upsertAssetsList); \n\n" } ] } }, "/assets/search": { "post": { "tags": [ "Assets" ], "summary": "Search assets", "description": "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nFulltext search for assets based on result relevance. Primarily meant\nfor human-centric use-cases, not for programs, since matching and\nordering may change over time. Additional filters can also be\nspecified. This operation doesn't support pagination.\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "searchAssets", "requestBody": { "description": "Search query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSearchFilter" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/AssetDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assets = await client.assets.search({\n filter: {\n parentIds: [1, 2]\n },\n search: {\n query: '21PT1019'\n }\n});" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.assets.search(name=\"some name\")\n\nres = client.assets.search(filter={\"name\": \"some name\"})\n\nres = client.assets.search(query=\"TAG 30 XV\")\n\nres = client.assets.search(name=\"xyz\",filter={\"parent_ids\": [123,456],\"source\": \"some source\"})\n\nmy_label_filter = LabelFilter(contains_all=[\"PUMP\"])\nres = client.assets.search(name=\"xyz\",filter=AssetFilter(labels=my_label_filter))\n" } ] } }, "/assets/delete": { "post": { "tags": [ "Assets" ], "summary": "Delete assets", "description": "\n\n> **Required capabilities:** `assetsAcl:WRITE`\n\nDelete assets. By default, `recursive=false` and the request would fail if attempting to delete assets that are referenced as parent by other assets.\nTo delete such assets and all its descendants, set recursive to true.\nThe limit of the request does not include the number of descendants that are deleted.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information.", "operationId": "deleteAssets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRequest" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "assetsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.assets.delete([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.assets.delete(id=[1,2,3], external_id=\"3\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList deletedAssets = client.assets().delete(byInternalIds); \n\nList byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList deletedAssets = client.assets().delete(byExternalIds); \n\n" } ] } }, "/models/spaces": { "post": { "tags": [ "Spaces" ], "summary": "Create or update spaces", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nAdd or update (upsert) spaces. For unchanged space specifications, the operation completes without making any changes. We will not update the ```lastUpdatedTime``` value for spaces that remain unchanged.", "operationId": "ApplySpaces", "requestBody": { "description": "Spaces to add or update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceCreateCollection" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/SpaceCollectionResponseV3" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "Space conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertConflict" } } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import SpaceApply\nspaces = [SpaceApply(space=\"mySpace\", description=\"My first space\", name=\"My Space\"),\nSpaceApply(space=\"myOtherSpace\", description=\"My second space\", name=\"My Other Space\")]\nres = client.data_modeling.spaces.apply(spaces)\n" } ] }, "get": { "tags": [ "Spaces" ], "summary": "List spaces defined in the project", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nList spaces defined in the current project.", "operationId": "listSpacesV3", "parameters": [ { "$ref": "#/components/parameters/ReducedLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IncludeGlobal" } ], "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/SpaceCollectionResponseWithCursor" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "space_list = client.data_modeling.spaces.list(limit=5)\n\nfor space in client.data_modeling.spaces:\n space # do something with the space\n\nfor space_list in client.data_modeling.spaces(chunk_size=2500):\n space_list # do something with the spaces\n" } ] } }, "/models/spaces/byids": { "post": { "tags": [ "Spaces" ], "summary": "Retrieve spaces by their space-ids", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nRetrieve up to 100 spaces by specifying their space-ids.", "operationId": "bySpaceIdsSpaces", "requestBody": { "description": "List of space-ids for the spaces to return.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfSpaceIdsRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/SpaceCollectionResponseV3" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.data_modeling.spaces.retrieve(spaces='mySpace')\n\nres = client.data_modeling.spaces.retrieve(spaces=[\"MySpace\", \"MyAwesomeSpace\", \"MyOtherSpace\"])\n" } ] } }, "/models/spaces/delete": { "post": { "tags": [ "Spaces" ], "summary": "Delete spaces", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete one or more spaces, maximum 100 spaces at a time.\n\n\nOnly empty spaces can be deleted. ", "operationId": "deleteSpacesV3", "requestBody": { "description": "List of space-ids for spaces to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfSpaceIdsRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfSpaceIdsResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.spaces.delete(spaces=[\"mySpace\", \"myOtherSpace\"])\n" } ] } }, "/models/datamodels": { "post": { "tags": [ "Data models" ], "summary": "Create or update data models", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nAdd or update (upsert) data models. For unchanged data model specifications, the operation completes without making any changes. We will not update the ```lastUpdatedTime``` value for models that remain unchanged.", "operationId": "createDataModels", "requestBody": { "description": "List of data models to add", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataModelCreateCollection" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/DataModelCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "Data model conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertConflict" } } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import DataModelApply\ndata_models = [\n DataModelApply(space=\"mySpace\",external_id=\"myDataModel\",version=\"v1\"),\n DataModelApply(space=\"mySpace\",external_id=\"myOtherDataModel\",version=\"v1\")]\nres = client.data_modeling.data_models.apply(data_models)\n" } ] }, "get": { "tags": [ "Data models" ], "summary": "List data models defined in the project", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nList data models defined in the project. You can filter the returned models by the specified space.", "operationId": "listDataModels", "parameters": [ { "$ref": "#/components/parameters/ReducedLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/InlineViews" }, { "$ref": "#/components/parameters/Space" }, { "$ref": "#/components/parameters/AllVersions" }, { "$ref": "#/components/parameters/IncludeGlobal" } ], "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/DataModelCollectionResponseWithCursor" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "data_model_list = client.data_modeling.data_models.list(limit=5)\n\nfor data_model in client.data_modeling.data_models:\n data_model # do something with the data_model\n\nfor data_model_list in client.data_modeling.data_models(chunk_size=10):\n data_model_list # do something with the data model\n" } ] } }, "/models/datamodels/byids": { "post": { "tags": [ "Data models" ], "summary": "Retrieve data models by their external ids", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nRetrieve up to 100 data models by their external ids. Views can be auto-expanded when the ```InlineViews``` query parameter is set.", "operationId": "byExternalIdsDataModels", "parameters": [ { "$ref": "#/components/parameters/InlineViews" } ], "requestBody": { "description": "List of external-ids of data models to retrieve.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ListOfVersionReferences" }, { "$ref": "#/components/schemas/ListOfAllVersionsReferences" } ] } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/DataModelCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.data_modeling.data_models.retrieve((\"mySpace\", \"myDataModel\", \"v1\"))\n" } ] } }, "/models/datamodels/delete": { "post": { "tags": [ "Data models" ], "summary": "Delete data models", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete one or more data models. Currently limited to 100 models at a time. This does not delete the views, nor the containers they reference.", "operationId": "deleteDataModels", "requestBody": { "description": "List of references to data models you wish to delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfVersionReferences" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/VersionReferencesCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.data_models.delete((\"mySpace\", \"myDataModel\", \"v1\"))\n" } ] } }, "/models/views": { "post": { "tags": [ "Views" ], "summary": "Create or update views", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nAdd or update (upsert) views. For unchanged view specifications, the operation completes without making any changes. We will not update the ```lastUpdatedTime``` value for views that remain unchanged.", "operationId": "ApplyViews", "requestBody": { "description": "Views to add or update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewCreateCollection" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ViewCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "View conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertConflict" } } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import ViewApply, MappedPropertyApply, ContainerId\nviews = [\n ViewApply(\n space=\"mySpace\",\n external_id=\"myView\",\n version=\"v1\",\n properties={\n \"someAlias\": MappedPropertyApply(\n container=ContainerId(\"mySpace\", \"myContainer\"),\n container_property_identifier=\"someProperty\",\n ),\n }\n )\n]\nres = client.data_modeling.views.apply(views)\n\nfrom cognite.client.data_classes.data_modeling import (\n ContainerId,\n DirectRelationReference,\n MappedPropertyApply,\n MultiEdgeConnectionApply,\n ViewApply,\n ViewId\n)\nacts_in_edge_type = DirectRelationReference(space=\"imdb\", external_id=\"acts-in\")\nmovie_view = ViewApply(\n space=\"imdb\",\n external_id=\"Movie\",\n version=\"1\",\n name=\"Movie\",\n properties={\n \"title\": MappedPropertyApply(\n container=ContainerId(space=\"imdb\", external_id=\"Movie\"),\n container_property_identifier=\"title\",\n ),\n \"actors\": MultiEdgeConnectionApply(\n type=acts_in_edge_type,\n direction=\"inwards\",\n source=ViewId(\"imdb\", \"Actor\", \"1\"),\n name=\"actors\",\n ),\n }\n)\nactor_view = ViewApply(\n space=\"imdb\",\n external_id=\"Actor\",\n version=\"1\",\n name=\"Actor\",\n properties={\n \"name\": MappedPropertyApply(\n container=ContainerId(\"imdb\", \"Actor\"),\n name=\"name\",\n container_property_identifier=\"name\",\n ),\n \"movies\": MultiEdgeConnectionApply(\n type=acts_in_edge_type,\n direction=\"outwards\",\n source=ViewId(\"imdb\", \"Movie\", \"1\"),\n name=\"movies\",\n ),\n }\n)\nres = client.data_modeling.views.apply([movie_view, actor_view])\n" } ] }, "get": { "tags": [ "Views" ], "summary": "List views defined in the project", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nList of views defined in the current project. You can filter the list by specifying a space.", "operationId": "listViews", "parameters": [ { "$ref": "#/components/parameters/ReducedLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Space" }, { "$ref": "#/components/parameters/IncludeInheritedProperties" }, { "$ref": "#/components/parameters/AllVersions" }, { "$ref": "#/components/parameters/IncludeGlobal" } ], "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/ViewCollectionResponseWithCursor" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "view_list = client.data_modeling.views.list(limit=5)\n\nfor view in client.data_modeling.views:\n view # do something with the view\n\nfor view_list in client.data_modeling.views(chunk_size=10):\n view_list # do something with the views\n" } ] } }, "/models/views/byids": { "post": { "tags": [ "Views" ], "summary": "Retrieve views by their external ids", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nRetrieve up to 100 views by their external ids.", "operationId": "byExternalIdsViews", "parameters": [ { "$ref": "#/components/parameters/IncludeInheritedProperties" } ], "requestBody": { "description": "List of external-ids of views to retrieve.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ListOfVersionReferences" }, { "$ref": "#/components/schemas/ListOfAllVersionsReferences" } ] } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/ViewCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.data_modeling.views.retrieve(('mySpace', 'myView', 'v1'))\n" } ] } }, "/models/views/delete": { "post": { "tags": [ "Views" ], "summary": "Delete views", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete one or more views. Currently limited to 100 views at a time.", "operationId": "deleteViews", "requestBody": { "description": "List of references to views you want to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfVersionReferences" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/VersionReferencesCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.views.delete(('mySpace', 'myView', 'v1'))\n" } ] } }, "/models/containers": { "post": { "tags": [ "Containers" ], "summary": "Create or update containers", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nAdd or update (upsert) containers. For unchanged container specifications, the operation completes without making any changes. We will not update the ```lastUpdatedTime``` value for containers that remain unchanged.", "operationId": "ApplyContainers", "requestBody": { "description": "Containers to add or update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerCreateCollection" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ContainerCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "View conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertConflict" } } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import ContainerApply, ContainerProperty, Text\ncontainer = [ContainerApply(space=\"mySpace\", external_id=\"myContainer\",\n properties={\"name\": ContainerProperty(type=Text, name=\"name\")})]\nres = client.data_modeling.containers.apply(container)\n\nfrom cognite.client.data_classes.data_modeling import Float64\nfrom cognite.client.data_classes.data_modeling.data_types import UnitReference\ncontainer = ContainerApply(\n space=\"mySpace\",\n external_id=\"myContainer\",\n properties={\n \"maxPressure\": ContainerProperty(\n nullable=True,\n description=\"Maximum Pump Pressure\",\n name=\"maxPressure\",\n type=Float64(\n unit=UnitReference(\n external_id=\"pressure:bar\",\n source_unit=\"BAR\"\n )\n )\n ),\n \"rotationConfigurations\": ContainerProperty(\n nullable=True,\n description=\"Rotation Configurations\",\n name=\"rotationConfigurations\",\n type=Float64(\n is_list=True,\n unit=UnitReference(\n external_id=\"angular_velocity:rev-per-min\"\n )\n )\n )\n }\n)\nres = client.data_modeling.containers.apply(container)\n\nfrom cognite.client.data_classes.data_modeling.data_types import UnitReference, EnumValue\nfrom cognite.client.data_classes.data_modeling.data_types import (\n Boolean, Date, DirectRelation, Enum, FileReference, Float32, Float64,\n Int32, Int64, Json, SequenceReference, Text, TimeSeriesReference, Timestamp\n)\ncontainer_properties = {\n \"prop01\": ContainerProperty(Boolean),\n \"prop02\": ContainerProperty(Boolean(is_list=True)),\n \"prop03\": ContainerProperty(Date),\n \"prop04\": ContainerProperty(Date(is_list=True)),\n \"prop05\": ContainerProperty(Timestamp),\n \"prop06\": ContainerProperty(Timestamp(is_list=True)),\n \"prop07\": ContainerProperty(Text),\n \"prop08\": ContainerProperty(Text(is_list=True)),\n # Note: DirectRelation(list) support `container`: The (optional) required type for the node\n # the direct relation points to.\n \"prop09\": ContainerProperty(DirectRelation),\n \"prop10\": ContainerProperty(DirectRelation(is_list=True)),\n # Note: Enum also support `unknown_value`: The value to use when the enum value is unknown.\n \"prop11\": ContainerProperty(\n Enum({\"Closed\": EnumValue(\"Valve is closed\"),\n \"Opened\": EnumValue(\"Valve is opened\")})),\n # Note: Floats support unit references, e.g. `unit=UnitReference(\"pressure:bar\")`:\n \"prop12\": ContainerProperty(Float32),\n \"prop13\": ContainerProperty(Float32(is_list=True)),\n \"prop14\": ContainerProperty(Float64),\n \"prop15\": ContainerProperty(Float64(is_list=True)),\n \"prop16\": ContainerProperty(Int32),\n \"prop17\": ContainerProperty(Int32(is_list=True)),\n \"prop18\": ContainerProperty(Int64),\n \"prop19\": ContainerProperty(Int64(is_list=True)),\n \"prop20\": ContainerProperty(Json),\n \"prop21\": ContainerProperty(Json(is_list=True)),\n \"prop22\": ContainerProperty(SequenceReference),\n \"prop23\": ContainerProperty(SequenceReference(is_list=True)),\n # Note: It is adviced to represent files and time series directly as nodes\n # instead of referencing existing:\n \"prop24\": ContainerProperty(FileReference),\n \"prop25\": ContainerProperty(FileReference(is_list=True)),\n \"prop26\": ContainerProperty(TimeSeriesReference),\n \"prop27\": ContainerProperty(TimeSeriesReference(is_list=True)),\n}\ncontainer = ContainerApply(\n space=\"my-space\",\n external_id=\"my-everything-container\",\n properties=container_properties,\n)\n" } ] }, "get": { "tags": [ "Containers" ], "summary": "List containers defined in the project", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nList of containers defined in the current project. You can filter the list by specifying a space.", "operationId": "listContainers", "parameters": [ { "$ref": "#/components/parameters/ReducedLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Space" }, { "$ref": "#/components/parameters/IncludeGlobal" }, { "$ref": "#/components/parameters/FilterUsedFor" } ], "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/ContainerCollectionResponseWithCursor" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "container_list = client.data_modeling.containers.list(limit=5)\n\nfor container in client.data_modeling.containers:\n container # do something with the container\n\nfor container_list in client.data_modeling.containers(chunk_size=10):\n container_list # do something with the containers\n" } ] } }, "/models/containers/byids": { "post": { "tags": [ "Containers" ], "summary": "Retrieve containers by their external ids", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nRetrieve up to 100 containers by their specified external ids.", "operationId": "byExternalIdsContainers", "requestBody": { "description": "List of external-ids of containers to retrieve.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfSpaceExternalIdsRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/ContainerCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.data_modeling.containers.retrieve(('mySpace', 'myContainer'))\n\nfrom cognite.client.data_classes.data_modeling import ContainerId\nres = client.data_modeling.containers.retrieve(ContainerId(space='mySpace', external_id='myContainer'))\n" } ] } }, "/models/containers/delete": { "post": { "tags": [ "Containers" ], "summary": "Delete containers", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete one or more containers. Currently limited to 100 containers at a time.", "operationId": "deleteContainers", "requestBody": { "description": "List of spaces and external-ids for the containers you want to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfSpaceExternalIdsRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfSpaceExternalIdsResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.containers.delete((\"mySpace\", \"myContainer\"))\n" } ] } }, "/models/containers/indexes/delete": { "post": { "tags": [ "Containers" ], "summary": "Delete indexes from containers", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete one or more container indexes. Currently limited to 10 indexes at a time.", "operationId": "deleteContainerIndexes", "requestBody": { "description": "List of references to the indexes you want to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfContainerSubObjectIdentifierResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.containers.delete_indexes(\n [(ContainerId(\"mySpace\", \"myContainer\"), \"myIndex\")]\n)\n" } ] } }, "/models/containers/indexes/retry": { "post": { "tags": [ "Containers" ], "summary": "Retry failed indexes", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nTriggers a retry of the given failed container indexes. This will usually entail scanning through all the data in the container, so use this sparingly. There are strict limits as to how often a given index can be retried, and how many schema entities can be in a retrying state simultaneously.", "operationId": "retryContainerIndexes", "requestBody": { "description": "List of references to the indexes you want to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfContainerSubObjectIdentifierResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/models/containers/constraints/delete": { "post": { "tags": [ "Containers" ], "summary": "Delete constraints from containers", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete one or more container constraints. Currently limited to 10 constraints at a time.", "operationId": "deleteContainerConstraints", "requestBody": { "description": "List of references to the constraints you want to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfContainerSubObjectIdentifierResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.containers.delete_constraints(\n [(ContainerId(\"mySpace\", \"myContainer\"), \"myConstraint\")]\n)\n" } ] } }, "/models/containers/constraints/retry": { "post": { "tags": [ "Containers" ], "summary": "Retry failed container constraints", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nTriggers a revalidation of the given failed container constraints. This will usually entail scanning through all the data in the container, so use this sparingly. There are strict limits as to how often a given constraint can be revalidated, and how many schema entities can be in a retrying state simultaneously.", "operationId": "retryContainerConstraints", "requestBody": { "description": "List of references to the constraints you want to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfContainerSubObjectIdentifierResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/models/containers/properties/retry": { "post": { "tags": [ "Containers" ], "summary": "Retry failed property constraints", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nTriggers a revalidation of failed constraints on the given properties. This includes `nullable`, `maxListSize` and `maxTextSize`. Revalidation usually entails scanning through all the data in the container, so use this sparingly. There are strict limits as to how often a given property can be revalidated, and how many schema entities can be in a retrying simultaneously.", "operationId": "retryPropertyConstraints", "requestBody": { "description": "List of references to properties with property-level constraints that you want to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/ListOfContainerSubObjectIdentifierResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/models/containers/inspect": { "post": { "tags": [ "Containers" ], "summary": "Inspect containers", "operationId": "containerInspect", "requestBody": { "description": "Which containers to inspect and the inspection operations to run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerInspectRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/ContainerInspectResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n" } }, "/models/instances": { "post": { "tags": [ "Instances" ], "summary": "Create or update nodes/edges", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nCreate or update nodes and edges in a transaction. The ```items``` field of the payload is an array of objects\nwhere each object describes a node or an edge to create, patch or replace. The ```instanceType``` field of\neach object must be ```node``` or ```edge``` and determines how the rest of the object is interpreted.\n\nThis operation is currently limited to 1000 nodes and/or edges at a time.\n\nIndividual nodes and edges are uniquely identified by their externalId and space.\n\nInstances will be returned in the same order as they are supplied in the request.\n\nFor more details on ingesting instances into a graph, see [Ingesting instances]\n(https://docs.cognite.com/cdf/dm/dm_concepts/dm_ingestion).\n\n### Creating new instances\n\nWhen there is no node or edge with the given externalId in the given space, a node will be created and the\nproperties provided for each of the containers or views in the ```sources``` array will be populated for the\nnode/edge. Nodes can also be created implicitly when an edge between them is created (if\n```autoCreateStartNodes``` and/or ``` autoCreateEndNodes``` is set), or when a direct relation\nproperty is set, the target node does not exist and ```autoCreateDirectRelations``` is set.\n\nTo add a node or edge, the user must have capabilities to access (write to) both the view(s) referenced in\n```sources``` and the container(s) underlying these views, as well as any directly referenced containers.\n\n### Updating (patching) or replacing instances\n\nWhen a node or edge (instance) with the given externalId already exists in a space, the\nproperties named in the ```sources``` field will be written to the instance. Other properties will remain\nunchanged. To replace the whole set of properties for an instance (a node or an edge) rather than patch the\ninstance, set the ```replace``` parameter to ```true```.\n\nNote: When using ```replace``` as ```true``` it will replace any omitted property to either it's default\nvalue as defined on the container(s) or null if no default value is set. All properties on the related\ncontainer(s) referenced in the provided ```sources``` view(s) will be replaced, so even when the provided\nview(s) only contains a subset of properties from a container all the properties in that container for that\ninstance will be replaced. If the underlying container(s) have any required properties that are not provided,\nthe operation will fail.\n\nIf you use a writable view to update properties (that is, the source you are referring to in ```sources```\nis a view), you must have write access to the view as well as all of its backing containers.\n\n### No-change patch operations\nWhen a node/edge item has no changes compared to the existing instance - that is, when the supplied property\nvalues are equal to the corresponding values in the existing node/edge, the node/edge will stay unchanged.\nIn this case, the ```lastUpdatedTime``` values for the nodes/edges in question will not change.\n\n### Deleting instances\nIt's also possible to delete instances by passing instance references to the `delete` field. Upserts and\ndeletes can be combined in the same request and will be executed atomically. The total number of ingested and\ndeleted items cannot exceed 1000. If an instance doesn’t exist, the delete operation skips it and it won't be\nincluded in the response.\n", "operationId": "applyNodeAndEdges", "requestBody": { "description": "Nodes/edges to add or update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceBulk" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/SlimNodeAndEdgeCollectionResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "Ingestion conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertConflict" } } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply\nnode = NodeApply(\"mySpace\", \"myNodeId\")\nres = client.data_modeling.instances.apply(node)\n\nfrom cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply, ViewId\nactor = NodeApply(\n space=\"actors\",\n external_id=\"arnold_schwarzenegger\",\n sources=[\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n {\"name\": \"Arnold Schwarzenegger\", \"birthYear\": 1947}\n ),\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"ActorView\", \"v1\"),\n {\"wonOscar\": False}\n )\n ]\n)\nmovie = NodeApply(\n space=\"movies\",\n external_id=\"Terminator\",\n sources=[\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"MovieView\", \"v1\"),\n {\"title\": \"Terminator\", \"releaseYear\": 1984}\n )\n ]\n)\n# This is one-to-many edge, in this case from a person to a movie\nactor_to_movie = EdgeApply(\n space=\"actors\",\n external_id=\"relation:arnold_schwarzenegger:terminator\",\n type=(\"types\", \"acts-in\"),\n start_node=(\"actors\", \"arnold_schwarzenegger\"),\n end_node=(\"movies\", \"Terminator\"),\n)\nres = client.data_modeling.instances.apply([actor, movie], [actor_to_movie])\n\nfrom cognite.client.data_classes.data_modeling import EdgeApply\nactor_to_movie = EdgeApply(\n space=\"actors\",\n external_id=\"relation:arnold_schwarzenegger:terminator\",\n type=(\"types\", \"acts-in\"),\n start_node=(\"actors\", \"arnold_schwarzenegger\"),\n end_node=(\"movies\", \"Terminator\"),\n)\nres = client.data_modeling.instances.apply(\n edges=actor_to_movie,\n auto_create_start_nodes=True,\n auto_create_end_nodes=True\n)\n\nfrom cognite.client.utils import datetime_to_ms_iso_timestamp\nfrom datetime import datetime, timezone\nmy_date = datetime(2020, 3, 14, 15, 9, 26, 535000, tzinfo=timezone.utc)\ndata_model_timestamp = datetime_to_ms_iso_timestamp(my_date) # \"2020-03-14T15:09:26.535+00:00\"\n\nfrom cognite.client.data_classes.data_modeling import TypedNodeApply, PropertyOptions\nclass PersonApply(TypedNodeApply):\n birth_year = PropertyOptions(identifier=\"birthYear\")\n\n def __init__(self, space: str, external_id, name: str, birth_year: int):\n super().__init__(space, external_id, type=(\"sp_model_space\", \"Person\"))\n self.name = name\n self.birth_year = birth_year\n def get_source(self):\n return ViewId(\"sp_model_space\", \"Person\", \"v1\")\nperson = PersonApply(\"sp_date_space\", \"my_person\", \"John Doe\", 1980)\nres = client.data_modeling.instances.apply(nodes=person)\n" } ] } }, "/models/instances/list": { "post": { "tags": [ "Instances" ], "summary": "Filter nodes/edges", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nFilter the instances - nodes and edges - in a project.", "operationId": "advancedListInstance", "requestBody": { "description": "Filter based on the instance type, the name, the external-ids, and on properties. The filter supports sorting and pagination. The instances must have data in all the views referenced by the sources field. Properties for up to 10 views can be retrieved in one query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeOrEdgeListRequestV3" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/NodeAndEdgeCollectionResponseWithCursorV3" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "instance_list = client.data_modeling.instances.list(limit=5)\n\ninstance_list = client.data_modeling.instances.list(space=\"my-space\")\n\nfrom cognite.client.data_classes.data_modeling import InstanceSort\nproperty_sort = InstanceSort(\n property=('space', 'view_xid/view_version', 'some_property'),\n direction=\"descending\",\n nulls_first=True)\ninstance_list = client.data_modeling.instances.list(sort=property_sort)\n\nfor instance in client.data_modeling.instances:\n instance # do something with the instance\n\nfor instance_list in client.data_modeling.instances(chunk_size=100):\n instance_list # do something with the instances\n" } ] } }, "/models/instances/byids": { "post": { "tags": [ "Instances" ], "summary": "Retrieve nodes/edges by their external ids", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nRetrieve up to 1000 nodes or edges by their external ids.", "operationId": "byExternalIdsInstances", "requestBody": { "description": "List of external-ids for nodes or edges to retrieve. Properties for **up to 10 unique views** (in total across the external ids requested) can be retrieved in one query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfSpaceExternalIdsRequestWithTyping" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/ByIdsResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.data_modeling.instances.retrieve(\n nodes=(\"mySpace\", \"myNodeExternalId\"),\n edges=(\"mySpace\", \"myEdgeExternalId\"),\n sources=(\"mySpace\", \"myViewExternalId\", \"myViewVersion\"))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId, ViewId\nres = client.data_modeling.instances.retrieve(\n NodeId(\"mySpace\", \"myNode\"),\n EdgeId(\"mySpace\", \"myEdge\"),\n ViewId(\"mySpace\", \"myViewExternalId\", \"myViewVersion\"))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId\nres = client.data_modeling.instances.retrieve(\n NodeId(\"mySpace\", \"myNode\"),\n EdgeId(\"mySpace\", \"myEdge\"),\n sources=(\"myspace\", \"myView\"))\nfrom cognite.client.data_classes.data_modeling import EdgeId, TypedEdge, PropertyOptions, DirectRelationReference, ViewId\nclass Flow(TypedEdge):\n flow_rate = PropertyOptions(identifier=\"flowRate\")\n\n def __init__(\n self,\n space: str,\n external_id: str,\n version: int,\n type: DirectRelationReference,\n last_updated_time: int,\n created_time: int,\n flow_rate: float,\n start_node: DirectRelationReference,\n end_node: DirectRelationReference,\n deleted_time: int | None = None,\n ) -> None:\n super().__init__(\n space, external_id, version, type, last_updated_time, created_time, start_node, end_node, deleted_time\n )\n self.flow_rate = flow_rate\n\n @classmethod\n def get_source(cls) -> ViewId:\n return ViewId(\"sp_model_space\", \"flow\", \"1\")\nres = client.data_modeling.instances.retrieve_edges(\n EdgeId(\"mySpace\", \"theFlow\"), edge_cls=Flow\n)\nisinstance(res, Flow)\nfrom cognite.client.data_classes.data_modeling import NodeId, TypedNode, PropertyOptions, DirectRelationReference, ViewId\nclass Person(TypedNode):\n birth_year = PropertyOptions(identifier=\"birthYear\")\n\n def __init__(\n self,\n space: str,\n external_id: str,\n version: int,\n last_updated_time: int,\n created_time: int,\n name: str,\n birth_year: int | None = None,\n type: DirectRelationReference | None = None,\n deleted_time: int | None = None,\n ):\n super().__init__(\n space=space,\n external_id=external_id,\n version=version,\n last_updated_time=last_updated_time,\n created_time=created_time,\n type=type,\n deleted_time=deleted_time\n )\n self.name = name\n self.birth_year = birth_year\n\n @classmethod\n def get_source(cls) -> ViewId:\n return ViewId(\"myModelSpace\", \"Person\", \"1\")\nres = client.data_modeling.instances.retrieve_nodes(\n NodeId(\"myDataSpace\", \"myPerson\"), node_cls=Person\n)\nisinstance(res, Person)\n" } ] } }, "/models/instances/search": { "post": { "tags": [ "Instances" ], "summary": "Search for nodes/edges", "description": "\n\n> **Required capabilities:** `DataModels:READ`\n\nSearch text fields in views for nodes or edge(s). The service will return up to 1000 results. This operation orders the results by relevance, across the specified spaces.", "operationId": "searchInstances", "requestBody": { "description": "The search specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeOrEdgeSearchRequest" } } }, "required": true }, "x-capability": [ "DataModels:READ" ], "responses": { "200": { "$ref": "#/components/responses/SearchResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import ViewId\nres = client.data_modeling.instances.search(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n query=\"Arnold\",\n properties=[\"name\"])\n\nfrom cognite.client.data_classes.data_modeling import ViewId\nfrom cognite.client.data_classes import filters\nborn_after_1970 = filters.Range([\"mySpace\", \"PersonView/v1\", \"birthYear\"], gt=1970)\nres = client.data_modeling.instances.search(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n query=\"Quentin\",\n properties=[\"name\"],\n filter=born_after_1970)\n" } ] } }, "/models/instances/aggregate": { "post": { "tags": [ "Instances" ], "summary": "Aggregate data across nodes/edges", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nAggregate data for nodes or edges in a project. You can use an optional query or filter specification to limit the result.", "operationId": "aggregateInstances", "requestBody": { "description": "Aggregation specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregationRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/AggregationResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import ViewId, aggregations as aggs\navg_run_time = aggs.Avg(\"runTimeMinutes\")\nview_id = ViewId(\"mySpace\", \"PersonView\", \"v1\")\nres = client.data_modeling.instances.aggregate(view_id, avg_run_time, group_by=\"releaseYear\")\nfrom cognite.client.data_classes.data_modeling import aggregations as aggs, ViewId\nbirth_by_decade = aggs.Histogram(\"birthYear\", interval=10.0)\nview_id = ViewId(\"mySpace\", \"PersonView\", \"v1\")\nres = client.data_modeling.instances.histogram(view_id, birth_by_decade)\n" } ] } }, "/models/instances/delete": { "post": { "tags": [ "Instances" ], "summary": "Delete nodes/edges", "description": "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nDelete nodes and edges in a transaction. Limited to 1000 nodes/edges at a time.\n\n\nWhen a node is selected for deletion, all connected incoming and outgoing edges that point to or from it are also deleted. However, please note that the operation might fail if the node has a high number of edge connections. If this is the case, consider deleting the edges connected to the node before deleting the node itself.\nNodes and/or edges that do not exist in the graph when the delete request is processed will be ignored. The rationale for this is that the end-state will reflect the desired state regardless of the instance's previous state.\nNote that attempting to delete something from a space that does not exist will be considered an invalid request, as the API does not affect spaces themselves, only graph nodes and edges. ", "operationId": "deleteBulk", "requestBody": { "description": "List of types, spaces, and external-ids for nodes and edges to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeOrEdgeDeleteRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/NodeOrEdgeDeleteResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.data_modeling.instances.delete(nodes=(\"mySpace\", \"myNode\"))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId\nclient.data_modeling.instances.delete(NodeId('mySpace', 'myNode'), EdgeId('mySpace', 'myEdge'))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId\nmy_view = client.data_modeling.views.retrieve(('mySpace', 'myView'))\nmy_nodes = client.data_modeling.instances.list(instance_type='node', sources=my_view, limit=None)\nclient.data_modeling.instances.delete(nodes=my_nodes.as_ids())\n" } ] } }, "/models/instances/query": { "post": { "tags": [ "Instances" ], "summary": "Query nodes/edges", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nSpecification of query endpoint. For more information, see [Query language](https://docs.cognite.com/cdf/dm/dm_concepts/dm_querying).", "operationId": "queryContent", "requestBody": { "description": "Query specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/QueryResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling.query import Query, Select, NodeResultSetExpression, EdgeResultSetExpression, SourceSelector\nfrom cognite.client.data_classes.filters import Range, Equals\nfrom cognite.client.data_classes.data_modeling.ids import ViewId\nmovie_id = ViewId(\"mySpace\", \"MovieView\", \"v1\")\nactor_id = ViewId(\"mySpace\", \"ActorView\", \"v1\")\nquery = Query(\n with_ = {\n \"movies\": NodeResultSetExpression(filter=Range(movie_id.as_property_ref(\"releaseYear\"), lt=2000)),\n \"actors_in_movie\": EdgeResultSetExpression(from_=\"movies\", filter=Equals([\"edge\", \"type\"], {\"space\": movie_id.space, \"externalId\": \"Movie.actors\"})),\n \"actors\": NodeResultSetExpression(from_=\"actors_in_movie\"),\n },\n select = {\n \"actors\": Select(\n [SourceSelector(actor_id, [\"name\"])], sort=[InstanceSort(actor_id.as_property_ref(\"name\"))]),\n },\n)\nres = client.data_modeling.instances.query(query)\n\nfrom cognite.client.data_classes.data_modeling.data_types import UnitReference, UnitSystemReference\nselected_source = SourceSelector(\n source=ViewId(\"my-space\", \"my-xid\", \"v1\"),\n properties=[\"f32_prop1\", \"f32_prop2\", \"f64_prop1\", \"f64_prop2\"],\n target_units=[\n TargetUnit(\"f32_prop1\", UnitReference(\"pressure:kilopa\")),\n TargetUnit(\"f32_prop2\", UnitReference(\"pressure:barg\")),\n TargetUnit(\"f64_prop1\", UnitSystemReference(\"SI\")),\n TargetUnit(\"f64_prop2\", UnitSystemReference(\"Imperial\")),\n ],\n)\n\nSourceSelector(source=ViewId(\"my-space\", \"my-xid\", \"v1\"), properties=[\"*\"])\n" } ] } }, "/models/instances/sync": { "post": { "tags": [ "Instances" ], "summary": "Sync nodes/edges", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nSubscribe to changes for nodes and edges in a project, matching a supplied filter. This endpoint will always return a ```NextCursor```. The sync specification mirrors the query interface, but sorting is not currently supported. For more information, see [Query language](https://docs.cognite.com/cdf/dm/dm_concepts/dm_querying).", "operationId": "syncContent", "requestBody": { "description": "Change filter specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/QueryResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling.instances import InstanceSort\nfrom cognite.client.data_classes.data_modeling.query import Query, Select, NodeResultSetExpression, EdgeResultSetExpression, SourceSelector\nfrom cognite.client.data_classes.filters import Range, Equals\nfrom cognite.client.data_classes.data_modeling.ids import ViewId\nmovie_id = ViewId(\"mySpace\", \"MovieView\", \"v1\")\nactor_id = ViewId(\"mySpace\", \"ActorView\", \"v1\")\nquery = Query(\n with_ = {\n \"movies\": NodeResultSetExpression(filter=Range(movie_id.as_property_ref(\"releaseYear\"), lt=2000)),\n \"actors_in_movie\": EdgeResultSetExpression(from_=\"movies\", filter=Equals([\"edge\", \"type\"], {\"space\": movie_id.space, \"externalId\": \"Movie.actors\"})),\n \"actors\": NodeResultSetExpression(from_=\"actors_in_movie\"),\n },\n select = {\n \"actors\": Select(\n [SourceSelector(actor_id, [\"name\"])], sort=[InstanceSort(actor_id.as_property_ref(\"name\"))]),\n },\n)\nres = client.data_modeling.instances.sync(query)\nquery.cursors = res.cursors\nres_new = client.data_modeling.instances.sync(query)\n" } ] } }, "/models/instances/inspect": { "post": { "tags": [ "Instances" ], "summary": "Inspect instances", "operationId": "instanceInspect", "requestBody": { "description": "Change filter specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceInspectRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/InstanceInspectResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import NodeId, EdgeId\nres = client.data_modeling.instances.inspect(\n nodes=NodeId(\"my-space\", \"foo1\"),\n edges=EdgeId(\"my-space\", \"bar2\"),\n)\n" } ], "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n" } }, "/models/statistics": { "get": { "tags": [ "Statistics" ], "summary": "Retrieve project-wide statistics and limits", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nReturns statistics and limits for data modeling resources across the project. Use this endpoint to monitor your overall data modeling usage and available capacity.", "operationId": "getStatistics", "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "description": "Statistics and limits for data modeling related resources in the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectStatistics" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/models/statistics/spaces": { "get": { "tags": [ "Statistics" ], "summary": "Retrieve statistics by space", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nReturns statistics for data modeling resources grouped by each space in the project.", "operationId": "getSpaceStatistics", "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "description": "List of spaces with associated data modeling statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceStatisticsResponseList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/models/statistics/spaces/byids": { "post": { "tags": [ "Statistics" ], "summary": "Retrieve statistics by space for specific space-ids", "description": "\n\n> **Required capabilities:** `dataModelsAcl:READ`\n\nReturns statistics for data modeling resources grouped by space for a specified list of spaces.", "operationId": "getSpaceStatisticsByIds", "requestBody": { "description": "List of space-ids to return statistics for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOfSpaceIdsRequest" } } }, "required": true }, "x-capability": [ "dataModelsAcl:READ" ], "responses": { "200": { "description": "List of spaces with associated data modeling statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceStatisticsResponseList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/datadomains": {}, "/datadomains/{externalId}": {}, "/datadomains/delete": {}, "/datadomains/update": {}, "/streams": { "post": { "tags": [ "Streams" ], "summary": "Create stream", "description": "\n\n> **Required capabilities:** `streamsAcl:CREATE`\n\nCreate a new stream. A stream is a target for high volume data ingestion,\nwith data shaped by the Data Modeling concepts. Specify an external ID and a stream template for each stream. The template defines the stream's mutability, limits, and lifecycle.\n", "operationId": "createStream", "requestBody": { "description": "Stream to create.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "title": "streamItems", "description": "List of streams.\n", "items": { "allOf": [ { "$ref": "#/components/schemas/StreamRequestItem" } ], "minItems": 1, "maxItems": 1 } } } } } }, "required": true }, "x-capability": [ "streamsAcl:CREATE" ], "responses": { "201": { "description": "Stream created.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamResponse" } } } }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "409": { "description": "Stream with the requested ID already exists.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamCreateConflict" } } } } } }, "get": { "tags": [ "Streams" ], "summary": "List streams", "description": "\n\n> **Required capabilities:** `streamsAcl:READ`\n\nList all streams available in the project.\n", "operationId": "listStreams", "x-capability": [ "streamsAcl:READ" ], "responses": { "200": { "description": "List of streams.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "title": "streamItems", "description": "List of streams.\n", "items": { "allOf": [ { "$ref": "#/components/schemas/StreamResponseItem" } ] } } } } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/streams/{streamId}": { "get": { "tags": [ "Streams" ], "summary": "Retrieve stream", "description": "\n\n> **Required capabilities:** `streamsAcl:READ`\n\nRetrieve a stream by its identifier.\n", "operationId": "getStream", "parameters": [ { "$ref": "#/components/parameters/StreamId" }, { "name": "includeStatistics", "in": "query", "required": false, "description": "If set to ```true```, usage statistics will be returned together with stream settings.\n", "schema": { "type": "boolean" } } ], "x-capability": [ "streamsAcl:READ" ], "responses": { "200": { "description": "Stream retrieved.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamResponseItem" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } }, "delete": { "tags": [ "Streams" ], "summary": "Delete stream (DEPRECATED)", "description": "\n\n> **Required capabilities:** `streamsAcl:DELETE`\n\n**DEPRECATED**: This endpoint is no longer supported and returns HTTP 410 Gone.\nPlease use `POST /streams/delete` instead.\n", "operationId": "deleteStream", "deprecated": true, "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "x-capability": [ "streamsAcl:DELETE" ], "responses": { "410": { "description": "This endpoint is deprecated and no longer supported.\nPlease use POST /streams/delete instead.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "example": 410 }, "message": { "type": "string", "example": "This endpoint is deprecated and no longer supported. Please use POST /streams/delete instead with body: {\"items\": [{\"externalId\": \"your-stream-id\"}]}" } } } } } } } } } } }, "/streams/delete": { "post": { "tags": [ "Streams" ], "summary": "Delete stream", "description": "\n\n> **Required capabilities:** `streamsAcl:DELETE`\n\nDelete a stream by its identifier, along with all records stored in the stream.\n\nIf the stream does not exist, the operation succeeds without error (idempotent delete).\n", "operationId": "deleteStreams", "requestBody": { "description": "Stream to delete.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamDeleteRequest" } } }, "required": true }, "x-capability": [ "streamsAcl:DELETE" ], "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/streams/{streamId}/records": { "post": { "tags": [ "Records" ], "summary": "Ingest records into a stream", "description": "\n\n> **Required capabilities:** `streamRecordsAcl:WRITE` `dataModelsAcl:READ`\n\nBefore a user can add records, all referenced schema elements (Spaces, Containers, Properties) must be defined/created in [Data Modeling](https://docs.cognite.com/cdf/dm)\n\nTo add records, the user must have capabilities to access (read) the referenced containers as well as capabilities to access (write) the referenced record ```space```.\n\nBatches of records are ingested into a ```stream```.\n\nUnder normal ingestion operation, and where the data ```stream``` does not contain any duplicated records,\nthe record will be created, and the properties defined in each of the containers in the ```sources``` array will be populated.\n\nFor immutable streams a duplicate record is defined as one which is being written to the same ```space```,\nwhich uses the same container definitions in the ```sources``` array,\nand all the properties (names and values) are the same.\n\nFor immutable streams under most circumstances, when duplicate records are encountered during ingestion, the duplicate is discarded.\nHowever there are rare occasions when certain internal database operations occur, a duplicate may be stored.\n\nFor mutable streams duplicated record identifiers (```space``` + ```externalId```) are not allowed\nand a request which tries to create a record with existing identifier will be rejected.\n\n**Note:** The maximum total request size is 10MB.\n", "operationId": "ingestRecords", "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "requestBody": { "description": "Records to ingest into a stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRecordsRequest" } } }, "required": true }, "x-capability": [ "streamRecordsAcl:WRITE", "dataModelsAcl:READ" ], "responses": { "202": { "$ref": "#/components/responses/RecordsIngestResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "Some mutable records with the specified `space` and `externalId` already exist in the stream.\nBut some records might have been created successfully.\nWhich records were successfully created and which were rejected with a conflict can be understood from the response content.\n\n**Note:** the error may appear due to some HTTP request retries (in intermediate components like SDK, Load balancers, Application Gateway, etc),\nso better to check which records are in the stream when you receive this error.\n`.../records/filter` or `.../records/sync` endpoints with a filter by `space` and `externalId` can be used to check the stored state of the conflicting records.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } }, "422": { "description": "Some mutable record identifiers (`space` and `externalId`) are duplicated in the request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableRecords" } } } }, "500": { "description": "If at least one record was not ingested due to an internal error, and all other errors in the `failed` list were non-retryable,\nthis error code will be returned.\n\n**Note:** Record operations are not transactional. This means that during batch ingestion,\nsome records may be created successfully even if the creation of others fails.\nThe response body indicates which records were successfully created and which were not.\n\nAn internal server error usually indicates an issue that requires investigation. A simple retry might not help,\nbut a few retries could be a reasonable approach.\n\n**Note:** If you choose to retry on a 500 error, it is recommended to retry only the failed records rather than the entire request.\nFor mutable streams this helps avoid receiving 409 status codes records that were already successfully created in a previous attempt.\nFor immutable streams, this helps prevent accidental duplicate records from appearing in the stream (in rare cases when the deduplication mechanism fails).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } }, "503": { "description": "If at least one record was not ingested due to the service being temporarily unavailable,\nthis error code will be returned.\n\n**Note:** Record operations are not transactional. This means that during batch ingestion, some records may be created successfully\neven if the creation of others fails. The response body indicates which records were successfully created and which were not.\n\nA \"service temporarily unavailable\" error usually indicates a temporary issue, and several retries may help complete the record creation.\n\n**Note:** It is recommended to retry ingestion of only the failed records rather than the entire request.\nFor mutable streams, this helps avoid receiving 409 status codes for records that were already successfully created in a previous attempt.\nFor immutable streams, this helps prevent accidental duplicate records from appearing in the stream (in rare cases when the deduplication mechanism fails).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } } } } }, "/streams/{streamId}/records/upsert": { "post": { "tags": [ "Records" ], "summary": "Upsert (create or update) records into a stream", "description": "\n\n> **Required capabilities:** `streamRecordsAcl:WRITE` `dataModelsAcl:READ`\n\n**Note:** This endpoint is only available for mutable streams.\n\nBefore a user can upsert records, all referenced schema elements (Spaces, Containers, Properties) must be defined/created in [Data Modeling](https://docs.cognite.com/cdf/dm).\n\nTo upsert records, the user must have capabilities to access (read) the referenced containers as well as capabilities to access (write) the referenced record ```space```.\n\nBatches of records are ingested or updated into a ```stream```.\n\nUnder normal upsert operation, the record will be created or updated, and the properties defined in each of the containers in the ```sources``` array will be populated.\n\nIf record identifiers (```space``` + ```externalId```) are already in the stream, records are fully updated (no partial updates for this endpoint).\nOtherwise, records are created.\n\n**Note:** The maximum total request size is 10MB.\n", "operationId": "upsertRecords", "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "requestBody": { "description": "Records to upsert into a stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRecordsRequest" } } }, "required": true }, "x-capability": [ "streamRecordsAcl:WRITE", "dataModelsAcl:READ" ], "responses": { "202": { "$ref": "#/components/responses/RecordsIngestResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "description": "Some records with the specified `space` and `externalId` are being concurrently modified by this and other requests.\nBut some records might have been created or updated successfully.\nWhich records were successfully upserted and which were rejected with a conflict can be understood from the response content.\n\n**Note:** better to check which records are in the stream when you receive this error.\n`.../records/filter` or `.../records/sync` endpoints with a filter by `space` and `externalId` can be used\nto check the stored state of the conflicting records.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } }, "422": { "description": "Some record identifiers (`space` and `externalId`) are duplicated in the request or attempt to modify records in an immutable stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableRecords" } } } }, "500": { "description": "If at least one record was not upserted due to an internal error, and all other errors in the `failed` list were non-retryable,\nthis error code will be returned.\n\n**Note:** Record operations are not transactional. This means that during batch upsert,\nsome records may be created/updated successfully even if the creation/updating of others fails.\nThe response body indicates which records were successfully upserted and which were not.\n\nAn internal server error usually indicates an issue that requires investigation. A simple retry might not help,\nbut a few retries could be a reasonable approach.\n\n**Note:** If you choose to retry on a 500 error, it is recommended to retry only the failed records rather than the entire request.\nThis helps avoid receiving 409 status codes or overriding records to outdated state (if multiple threads update records in your app).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } }, "503": { "description": "If at least one record was not upserted due to the service being temporarily unavailable,\nthis error code will be returned.\n\n**Note:** Record operations are not transactional. This means that during batch upsert, some records may be created/updated successfully\neven if the creation/updating of others fails. The response body indicates which records were successfully upserted and which were not.\n\nA \"service temporarily unavailable\" error usually indicates a temporary issue, and several retries may help complete the record upserting.\n\n**Note:** It is recommended to retry only the failed records rather than the entire request.\nThis helps avoid receiving 409 status codes or overriding records to outdated state (if multiple threads update records in your app).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } } } } }, "/streams/{streamId}/records/delete": { "post": { "tags": [ "Records" ], "summary": "Delete records from a stream", "description": "\n\n> **Required capabilities:** `streamRecordsAcl:WRITE`\n\n**Note:** This endpoint is only available for mutable streams.\n\nTo delete records, the user must have capabilities to access (write to) the referenced record ```space```.\n\nBatches of records are deleted from a ```stream``` with implicit `ignoreUnknownIds=true` semantic.\n\nThe record operations are eventually consistent,\nbut under normal conditions deleted records stop being returned by other endpoints within a few seconds.\nSync endpoint is returning a \"tombstone\" record (which only has a few top level fields and a deleted status)\nfor at least 3 days since deleting the actual record.\n", "operationId": "deleteRecords", "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "requestBody": { "description": "Records to delete from a stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRecordsRequest" } } }, "required": true }, "x-capability": [ "streamRecordsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/RecordsDeleteResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "422": { "description": "Some record identifiers (`space` and `externalId`) are duplicated in the request or attempt to delete records from an immutable stream.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableRecords" } } } }, "500": { "description": "If at least one record was not deleted due to an internal error, and all other errors in the `failed` list were non-retryable,\nthis error code will be returned.\n\n**Note:** Record operations are not transactional. This means that during batch delete,\nsome records may be deleted successfully even if the deletion of others fails.\nThe response body indicates which records were successfully deleted and which were not.\n\nAn internal server error usually indicates an issue that requires investigation. A simple retry might not help,\nbut a few retries could be a reasonable approach.\n\n**Note:** If you choose to retry on a 500 error, it is recommended to retry only the failed records rather than the entire request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } }, "503": { "description": "If at least one record was not deleted due to the service being temporarily unavailable,\nthis error code will be returned.\n\n**Note:** Record operations are not transactional. This means that during batch delete, some records may be deleted successfully\neven if the deletion of others fails. The response body indicates which records were successfully deleted and which were not.\n\nA \"service temporarily unavailable\" error usually indicates a temporary issue, and several retries may help complete the records deletion.\n\n**Note:** It is recommended to retry deletion of only the failed records rather than the entire request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPartialSuccessResponse" } } } } } } }, "/streams/{streamId}/records/filter": { "post": { "tags": [ "Records" ], "summary": "Retrieve records from a stream", "description": "\n\n> **Required capabilities:** `streamRecordsAcl:READ` `dataModelsAcl:READ`\n\nFilter the records from the ```stream```.\n", "operationId": "filterRecords", "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "requestBody": { "description": "Filter records based on the last updated time, on the space and on container(s) properties.\nThe response supports custom sorting. Otherwise, the records in the response are sorted by last updated time.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterRecordsRequest" } } }, "required": true }, "x-capability": [ "streamRecordsAcl:READ", "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/RecordsFilterResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/streams/{streamId}/records/aggregate": { "post": { "tags": [ "Records" ], "summary": "Aggregate records data from a stream", "description": "\n\n> **Required capabilities:** `streamRecordsAcl:READ` `dataModelsAcl:READ`\n\nAggregate data for records from the ```stream```.\n\nYou can use an optional filter specification to limit the results.\n\nThe Records API supports three main groups of aggregates:\n\n*Metric aggregates*: ```sum```, ```min```, ```max```, ```count```, etc.\n\n*Bucket aggregates* (result records are aggregated into groups (buckets) — similar to the Data Model Instances ```groupBy``` concept):\n ```uniqueValues``` (group by property values), ```timeHistogram``` (group by date/time ranges), ```filters``` (group by filter criteria), etc.\n\n*Pipeline aggregates*: ```movingFunction```.\n**Note:** The pipeline aggregate applies to the results of another histogram aggregate.\n It applies to metrics (such as count, min, max, sum, etc.), not to the records in the parent aggregate buckets.\n This differs from sub-aggregates, which apply directly to records within each bucket.\n\nEvery aggregate request can contain multiple aggregate entries.\nEvery bucket aggregate can contain multiple sub-aggregates (of any type), which are applied to records in each bucket of the parent aggregate.\n\nExample:\n\nImagine there is paddle-tennis players `game_statistics` container with model:\n```\n{\n game_id: Long,\n game_time: Instant,\n player_name: String,\n points_scored: Int,\n ...\n}\n```\n\nTo get the following data:\n```\nfor each day\n calculate average number of points scored by players in all games on that day\n and for each player\n calculate the total number of points scored by the player in all games they participated in on that day\n and find the max number of points scored by the player in all games they participated in on that day\nand find the max number of points scored by players in all games they participated in during the entire search period.\n```\n\nUse aggregates like these (meta language):\n```\ntimeHistogram(daily, game_time) // group by (form buckets) 1-day range based on `game_time` property values\n avg(points_scored) // inside every day group calculate average value in `points_scored` property\n uniqueValues(player_name) // inside every day group group by (form buckets) player names\n sum(points_scored) // inside every player group which is inside every day group calculate the sum of points scored\n max(points_scored) // inside every player group which is inside every day group find the maximum of points scored\nmax(points_scored) // find the maximum number of points scored across all statistic records (without any grouping)\n```\n\nOr the same in Cognite Records Aggregates DSL (Json):\n```\n{\n \"my_groups_by_1d_range\": {\n \"timeHistogram\": {\n \"calendarInterval\": \"1d\",\n \"property\": [ \"paddle\", \"game_statistics\", \"game_time\" ],\n \"aggregates\": {\n \"my_groups_by_player_name\": {\n \"uniqueValues\": {\n \"property\": [ \"paddle\", \"game_statistics\", \"player_name\" ],\n \"aggregates\": {\n \"my_player_daily_scores_sum\": {\n \"sum\": { \"property\": [ \"paddle\", \"game_statistics\", \"points_scored\" ] }\n },\n \"my_player_daily_scores_maximum\": {\n \"max\": { \"property\": [ \"paddle\", \"game_statistics\", \"points_scored\" ] }\n }\n }\n }\n },\n \"my_daily_scores_average\": {\n \"avg\": { \"property\": [ \"paddle\", \"game_statistics\", \"points_scored\" ] }\n }\n }\n }\n },\n \"my_scores_maximum_across_all_games\": {\n \"max\": { \"property\": [ \"paddle\", \"game_statistics\", \"points_scored\" ] }\n }\n}\n```\n\nand the response would be\n```\n{\n \"my_groups_by_1d_range\": {\n \"timeHistogramBuckets\": [\n {\n \"count\": 13\n \"intervalStart\": \"2025-05-25T00:00:00Z\",\n \"aggregates\": {\n \"my_groups_by_player_name\": {\n \"uniqueValueBuckets\": [\n {\n \"count\": 3\n \"value\": \"Vasya Rogov\",\n \"aggregates\": {\n \"my_player_daily_scores_sum\": {\n \"sum\": 57\n },\n \"my_player_daily_scores_maximum\": {\n \"max\": 25\n }\n }\n },\n {\n \"count\": 5\n \"value\": \"Vinni Pooh\",\n \"aggregates\": {\n \"my_player_daily_scores_sum\": {\n \"sum\": 53\n },\n \"my_player_daily_scores_maximum\": {\n \"max\": 21\n }\n }\n },\n ...\n ]\n },\n \"my_daily_scores_average\": {\n \"avg\": 33\n }\n }\n },\n {\n \"count\": 7\n \"intervalStart\": \"2025-05-26T00:00:00Z\",\n \"aggregates\": {\n \"my_groups_by_player_name\": {\n \"uniqueValueBuckets\": [\n {\n \"count\": 1\n \"value\": \"Vasya Rogov\",\n \"aggregates\": {\n \"my_player_daily_scores_sum\": {\n \"sum\": 24\n },\n \"my_player_daily_scores_maximum\": {\n \"max\": 24\n }\n }\n },\n {\n \"count\": 2\n \"value\": \"Pyatochok\",\n \"aggregates\": {\n \"my_player_daily_scores_sum\": {\n \"sum\": 42\n },\n \"my_player_daily_scores_maximum\": {\n \"max\": 23\n }\n }\n },\n ...\n ]\n },\n \"my_daily_scores_average\": {\n \"avg\": 22\n }\n }\n },\n ...\n ]\n },\n \"my_scores_maximum_across_all_games\": {\n \"max\": 42\n }\n}\n```\n", "operationId": "aggregateRecords", "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "requestBody": { "description": "Aggregation specification.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregateRecordsRequest" } } }, "required": true }, "x-capability": [ "streamRecordsAcl:READ", "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/RecordsAggregationResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/streams/{streamId}/records/sync": { "post": { "tags": [ "Records" ], "summary": "Sync records from a stream", "description": "\n\n> **Required capabilities:** `streamRecordsAcl:READ` `dataModelsAcl:READ`\n\nSubscribe to changes for records from the ```stream```, matching a supplied filter.\n", "operationId": "syncRecords", "parameters": [ { "$ref": "#/components/parameters/StreamId" } ], "requestBody": { "description": "Change filter specification.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRecordsRequest" } } }, "required": true }, "x-capability": [ "streamRecordsAcl:READ", "dataModelsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/RecordsSyncResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/events": { "post": { "tags": [ "Events" ], "summary": "Create events", "description": "\n\n> **Required capabilities:** `eventsAcl:WRITE`\n\nCreates multiple event objects in the same project.\nIt is possible to post a maximum of 1000 events per request.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "createEvents", "requestBody": { "description": "List of events to be posted. It is possible to post a maximum of 1000 events per request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExternalEvent" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/EventDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = [\n { description: 'Workorder pump abc', startTime: new Date('22 jan 2019') },\n { description: 'Broken rule', externalId: 'rule123', startTime: 1557346524667000 },\n];\nconst createdEvents = await client.events.create(events);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import EventWrite\nevents = [EventWrite(start_time=0, end_time=1), EventWrite(start_time=2, end_time=3)]\nres = client.events.create(events)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertEventsList = List.of(Event.newBuilder() \n .setExternalId(\"10\") \n .setStartTime(1552566113) \n .setEndTime(1553566113) \n .setDescription(\"generated_event_\") \n .setType(\"generated_event\") \n .setSubtype(\"event_sub_type\") \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .build()); \nclient.events().upsert(upsertEventsList); \n\n " } ] }, "get": { "tags": [ "Events" ], "summary": "List events", "description": "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nList events optionally filtered on query parameters\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "listEvents", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "in": "query", "name": "minStartTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxStartTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minEndTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxEndTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minActiveAtTime", "schema": { "description": "Event is considered active from its startTime to endTime inclusive. If startTime is null, event is never active. If endTime is null, event is active from startTime onwards. activeAtTime filter will match all events that are active at some point from min to max, from min, or to max, depending on which of min and max parameters are specified.", "allOf": [ { "$ref": "#/components/schemas/EpochTimestamp" } ] } }, { "in": "query", "name": "maxActiveAtTime", "schema": { "description": "Event is considered active from its startTime to endTime inclusive. If startTime is null, event is never active. If endTime is null, event is active from startTime onwards. activeAtTime filter will match all events that are active at some point from min to max, from min, or to max, depending on which of min and max parameters are specified.", "allOf": [ { "$ref": "#/components/schemas/EpochTimestamp" } ] } }, { "in": "query", "name": "assetIds", "description": "Asset IDs of equipment that this event relates to. Format is list of IDs serialized as JSON array(int64). Takes [ 1 .. 100 ] of unique items.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "assetExternalIds", "description": "Asset external IDs of equipment that this event relates to. Takes 1..100 unique items.", "example": "[\"externalId1\", \"externalId2\", \"externalId3\"]", "schema": { "$ref": "#/components/schemas/JsonArrayString" } }, { "in": "query", "name": "assetSubtreeIds", "description": "Only include events that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "assetSubtreeExternalIds", "description": "Only include events that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.", "example": "[\"externalId1\", \"externalId2\", \"externalId3\"]", "schema": { "$ref": "#/components/schemas/JsonArrayString" } }, { "in": "query", "name": "source", "schema": { "maxLength": 128, "type": "string", "description": "The source of this event." } }, { "in": "query", "name": "type", "schema": { "$ref": "#/components/schemas/EventType" } }, { "in": "query", "name": "subtype", "schema": { "$ref": "#/components/schemas/EventSubType" } }, { "in": "query", "name": "minCreatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxCreatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minLastUpdatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxLastUpdatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "externalIdPrefix", "schema": { "$ref": "#/components/schemas/CogniteExternalIdPrefix" }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/partitionLimited10" }, { "$ref": "#/components/parameters/IncludeMetadata" }, { "in": "query", "name": "sort", "description": "Sort by an array of the selected fields. Syntax: `[\":asc|desc\"]`. Default sort order is `asc` with short syntax: `[\"\"]`.\nFilter accepts the following field names:\n `dataSetId`,\n `externalId`,\n `type`,\n `subtype`,\n `startTime`,\n `endTime`,\n `createdTime`,\n `lastUpdatedTime`,\n `source`,\n `description`,\n `metadata`.\nPartitions are done independently of sorting, there's no guarantee on sort order between elements from different partitions.\n", "example": [ "endTime:desc" ], "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "$ref": "#/components/responses/EventDataWithCursorResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = await client.events.list({ filter: { startTime: { min: new Date('1 jan 2018') }, endTime: { max: new Date('1 jan 2019') } } });" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import filters\nis_workorder = filters.Prefix(\"external_id\", \"workorder\")\nhas_failure = filters.Search(\"description\", \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure), sort=(\"start_time\", \"desc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nis_workorder = filters.Prefix(EventProperty.external_id, \"workorder\")\nhas_failure = filters.Search(EventProperty.description, \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure),\n sort=(SortableEventProperty.start_time, \"desc\"))\nevent_list = client.events.list(limit=5, start_time={\"max\": 1500000000})\n\nfor event in client.events:\n event # do something with the event\n\nfor event_list in client.events(chunk_size=2500):\n event_list # do something with the events\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.events.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nin_timezone = filters.Prefix(EventProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.events.list(\n advanced_filter=in_timezone,\n sort=(SortableEventProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.events.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" } ] } }, "/events/{id}": { "get": { "tags": [ "Events" ], "summary": "Receive an event by its ID", "description": "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nRetrieves an event by its internal (service-generated) ID.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "getEventByInternalId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/CogniteInternalId" } } ], "responses": { "200": { "$ref": "#/components/responses/EventResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = await client.events.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.events.retrieve(id=1)\n\nres = client.events.retrieve(external_id=\"1\")\n" } ] } }, "/events/list": { "post": { "tags": [ "Events" ], "summary": "Filter events", "description": "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nRetrieve a list of events in the same project. This operation supports pagination by cursor.\nApply Filtering and Advanced filtering criteria to select a subset of events.\n\n### Advanced filtering\nAdvanced filter lets you create complex filtering expressions that combine simple operations,\nsuch as `equals`, `prefix`, `exists`, etc., using boolean operators `and`, `or`, and `not`.\nIt applies to basic fields as well as metadata.\n\nSee the `advancedFilter` attribute in the example.\n\nSee more information about filtering DSL [here](https://docs.cognite.com/dev/concepts/resource_filtering_dsl/ \"filtering DSL\").\n\n#### Supported leaf filters\n| Leaf filter | Supported fields | Description |\n|----------------|------------------------|--------------|\n| `containsAll` | Array type fields | Only includes results which contain all of the specified values.
`{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values.
`{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value.
`{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has value).
`{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values.
`{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified value.
`{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range.
`{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}`
Supported operators: `gt`, `lt`, `gte`, `lte` |\n| `search` | `[\"description\"]` | Introduced to provide functional parity with /events/search endpoint.
`{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n##### Search\nThe `search` leaf filter provides functional parity with the `/events/search` endpoint.\nIt's available only for the `[\"description\"]` field. When specifying only this filter with no explicit ordering,\nbehavior is the same as of the `/events/search/` endpoint without specifying filters.\nExplicit sorting overrides the default ordering by relevance.\nIt's possible to use the `search` leaf filter as any other leaf filter for creating complex queries.\n\nSee the `search` filter in the `advancedFilter` attribute in the example.\n\n#### advancedFilter attribute limits\n- filter query max depth: 10\n- filter query max number of clauses: 100\n- filter by metadata is case-insensitive, and it supports filtering on keys and values up to 256 characters\n- `and` and `or` clauses must have at least one element\n- `property` array of each leaf filter has the following limitations:\n - number of elements in the array is in the range [1, 2]\n - elements must not be blank\n - each element max length is 128 symbols\n - property array must match one of the existing properties (static or dynamic metadata)\n- `containsAll`, `containsAny`, and `in` filter `values` array size must be in the range [1, 100]\n- `containsAll`, `containsAny`, and `in` filter `values` array must contain elements of a primitive type (number, string)\n- `range` filter must have at least one of `gt`, `gte`, `lt`, `lte` attributes.\n But `gt` is mutually exclusive to `gte`, while `lt` is mutually exclusive to `lte`.\n For metadata, both upper and lower bounds must be specified.\n- `gt`, `gte`, `lt`, `lte` in the `range` filter must be a primitive value\n- `search` filter `value` must not be blank and the length must be in the range [1, 128]\n- filter query may have maximum 2 search leaf filters\n- maximum leaf filter string value length is different depending on the property the filter is using:\n - `externalId` - 255\n - `description` - 128 for the `search` filter and 255 for other filters\n - `type` - 64\n - `subtype` - 64\n - `source` - 128\n - any `metadata` key - 128\n\n### Sorting\nBy default, events are sorted by their creation time in the ascending order.\nUse the `search` leaf filter to sort the results by relevance.\nSorting by other fields can be explicitly requested. The `order` field is optional and defaults\nto `desc` for `_score_` and `asc` for all other fields.\nThe `nulls` field is optional and defaults to `auto`. `auto` is translated to `last`\nfor the `asc` order and to `first` for the `desc` order by the service.\nPartitions are done independently of sorting: there's no guarantee of the sort order between elements from different partitions.\n\nSee the `sort` attribute in the example.\n\n#### Null values\nIn case the `nulls` attribute has the `auto` value or the attribute isn't specified,\nnull (missing) values are considered to be bigger than any other values.\nThey are placed last when sorting in the `asc` order and first when sorting in `desc`.\nOtherwise, missing values are placed according to the `nulls` attribute (last or first), and their placement doesn't depend on the `order` value.\nValues, such as empty strings, aren't considered as nulls.\n\n#### Sorting by score\nUse a special sort property `_score_` when sorting by relevance.\nThe more filters a particular event matches, the higher its score is. This can be useful,\nfor example, when building UIs. Let's assume we want exact matches to be be displayed above matches by\nprefix as in the request below. An event with the type `fire` will match both `equals` and `prefix`\nfilters and, therefore, have higher score than events with names like `fire training` that match only the `prefix` filter.\n\n```\n\"advancedFilter\" : {\n \"or\" : [\n {\n \"equals\": {\n \"property\": [\"type\"],\n \"value\": \"fire\"\n }\n },\n {\n \"prefix\": {\n \"property\": [\"type\"],\n \"value\": \"fire\"\n }\n }\n ]\n},\n\"sort\": [\n {\n \"property\" : [\"_score_\"]\n }\n]\n```\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "advancedListEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventFilterRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/EventDataWithCursorResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = await client.events.list({ filter: { startTime: { min: new Date('1 jan 2018') }, endTime: { max: new Date('1 jan 2019') } } });" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import filters\nis_workorder = filters.Prefix(\"external_id\", \"workorder\")\nhas_failure = filters.Search(\"description\", \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure), sort=(\"start_time\", \"desc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nis_workorder = filters.Prefix(EventProperty.external_id, \"workorder\")\nhas_failure = filters.Search(EventProperty.description, \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure),\n sort=(SortableEventProperty.start_time, \"desc\"))\nevent_list = client.events.list(limit=5, start_time={\"max\": 1500000000})\n\nfor event in client.events:\n event # do something with the event\n\nfor event_list in client.events(chunk_size=2500):\n event_list # do something with the events\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.events.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nin_timezone = filters.Prefix(EventProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.events.list(\n advanced_filter=in_timezone,\n sort=(SortableEventProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.events.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listEventsResults = new ArrayList<>(); \nclient.events() \n .list() \n .forEachRemaining(events -> listEventsResults.addAll(events)); \n\nclient.events() \n .list(Request.create() \n .withFilterParameter(\"source\", \"source\")) \n .forEachRemaining(events -> listEventsResults.addAll(events)); \n\n" } ] } }, "/events/aggregate": { "post": { "tags": [ "Events" ], "summary": "Aggregate events", "description": "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nThe aggregation API lets you compute aggregated results on events,\nsuch as getting the count of all Events in a project, checking\ndifferent descriptions of events in your project, etc.\n\n#### Aggregate filtering\n##### Filter (filter & advancedFilter) data for aggregates\nFilters behave the same way as for the `Filter events` endpoint.\nIn text properties, the values are aggregated in a case-insensitive manner.\n\n##### aggregateFilter to filter aggregate results\n`aggregateFilter` works similarly to `advancedFilter` but always applies to aggregate properties.\nFor instance, in an aggregation for the `source` property, only the values (aka buckets) of the `source` property can be filtered out.\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\\\nThe Aggregates endpoint, as with all endpoints in the Events API, is subject to a request budget that applies\nlimits to both request rate and concurrency.\nPlease check [Events resource description](../../) for more information.", "operationId": "aggregateEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAggregateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/AggregateResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const aggregates = await client.events.aggregate.count({ filter: { assetIds: [1, 2, 3] } });\nconsole.log('Number of events: ', aggregates[0].count)\n\nconst uniqueValues = await client.events.aggregate.uniqueValues({ filter: { assetIds: [1, 2, 3] }, fields: ['subtype'] });\nconsole.log('Unique values: ', uniqueValues)" }, { "lang": "Python", "label": "Python SDK", "source": "aggregate_type = client.events.aggregate(filter={\"type\": \"failure\"})\nfrom cognite.client.data_classes.events import EventProperty\ntype_count = client.events.aggregate_cardinality_properties(EventProperty.metadata)\nfrom cognite.client.data_classes.events import EventProperty\ntype_count = client.events.aggregate_cardinality_values(EventProperty.type)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty\nis_asset = filters.ContainsAny(EventProperty.asset_ids, 123)\nplain_text_author_count = client.events.aggregate_cardinality_values(EventProperty.type, advanced_filter=is_asset)\ncount = client.events.aggregate_count()\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty\nis_workorder = filters.Equals(EventProperty.type, \"workorder\")\nworkorder_count = client.events.aggregate_count(advanced_filter=is_workorder)\nfrom cognite.client.data_classes.events import EventProperty\nresult = client.events.aggregate_unique_properties(EventProperty.metadata)\nprint(result.unique)\nfrom cognite.client.data_classes.events import EventProperty\nresult = client.events.aggregate_unique_values(property=EventProperty.type)\nprint(result.unique)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty\nfrom cognite.client.utils import timestamp_to_ms\nfrom datetime import datetime\nis_after_2020 = filters.Range(EventProperty.start_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.events.aggregate_unique_values(EventProperty.type, advanced_filter=is_after_2020)\nprint(result.unique)\n\nfrom cognite.client.data_classes.events import EventProperty\nfrom cognite.client.data_classes import aggregations\nagg = aggregations\nnot_planned = agg.Not(agg.Prefix(\"planned\"))\nis_after_2020 = filters.Range(EventProperty.start_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.events.aggregate_unique_values(EventProperty.type, advanced_filter=is_after_2020, aggregate_filter=not_planned)\nprint(result.unique)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Aggregate aggregateResult = \n client.events().aggregate(Request.create().withFilterParameter(\"source\", \"source\")); \n\n" } ] } }, "/events/byids": { "post": { "tags": [ "Events" ], "summary": "Retrieve events", "description": "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nRetrieves information about events in the same project. Events\nare returned in the same order as the ids listed in the query.\n\nA maximum of 1000 event IDs may be listed per request and all of them\nmust be unique.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "byIdsEvents", "requestBody": { "description": "List of IDs of events to retrieve. Must be up to a maximum of 1000 IDs, and all of them must be unique.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDataIds" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EventDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = await client.events.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.events.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.events.retrieve_multiple(external_ids=[\"abc\", \"def\"])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList resultByExternalIds = \n client.events().retrieve(byExternalIds);//by list of items \nList resultByExternalIds = \n client.events().retrieve(\"10\", \"20\");//by varargs of String \n\n List byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList resultByInternalIds = \n client.events().retrieve(byInternalIds);//by list of items \nList resultByInternalIds = \n client.events().retrieve(10, 20);//by varargs of Long \n\n" } ] } }, "/events/update": { "post": { "tags": [ "Events" ], "summary": "Update events", "description": "\n\n> **Required capabilities:** `eventsAcl:WRITE`\n\nUpdates events in the same project. This operation supports\npartial updates; Fields omitted from queries will remain unchanged on\nobjects.\n\nFor primitive fields (String, Long, Int), use 'set': 'value' to update\nvalue; use 'setNull': true to set that field to null.\n\nFor the Json Array field (e.g. assetIds), use 'set': [value1, value2] to\nupdate value; use 'add': [v1, v2] to add values to current list of\nvalues; use 'remove': [v1, v2] to remove these values from current list\nof values if exists.\n\nA maximum of 1000 events can be updated per request, and all of the\nevent IDs must be unique.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "updateEvents", "requestBody": { "description": "List of changes. A maximum of 1000 events can be updated per request, and all of the event IDs must be unique.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataEventChange" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EventDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = await client.events.update([{id: 123, update: {description: {set: 'New description'}}}]);" }, { "lang": "Python", "label": "Python SDK", "source": "event = client.events.retrieve(id=1)\nevent.description = \"New description\"\nres = client.events.update(event)\n\nfrom cognite.client.data_classes import EventUpdate\nmy_update = EventUpdate(id=1).description.set(\"New description\").metadata.add({\"key\": \"value\"})\nres = client.events.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "\nclient.events().upsert(upsertEventsList); \n\n" } ] } }, "/events/search": { "post": { "tags": [ "Events" ], "summary": "Search events", "description": "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nFulltext search for events based on result relevance. Primarily meant\nfor human-centric use-cases, not for programs, since matching and\nordering may change over time. Additional filters can also be\nspecified. This operation doesn't support pagination.\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "searchEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSearchRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/EventDataResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const events = await client.events.search({\n filter: {\n assetIds: [1, 2]\n },\n search: {\n description: 'Pump'\n }\n});" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.events.search(description=\"some description\")\n" } ] } }, "/events/delete": { "post": { "tags": [ "Events" ], "summary": "Delete events", "description": "\n\n> **Required capabilities:** `eventsAcl:WRITE`\n\nDeletes events with the given ids.\nA maximum of 1000 events can be deleted per request.\n\n### Request throttling\nThis endpoint is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Events resource description](../../) for more information.", "operationId": "deleteEvents", "requestBody": { "description": "List of IDs to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDataIds" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/400ErrorResponse" }, "429": { "$ref": "#/components/responses/429ErrorResponse" } }, "x-capability": [ "eventsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.events.delete([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.events.delete(id=[1,2,3], external_id=\"3\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList resultByExternalIds = \n client.events().delete(byExternalIds); \n\nList byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList resultByInternalIds = \n client.events().delete(byInternalIds); \n\n" } ] } }, "/files": { "post": { "tags": [ "Files" ], "summary": "Upload file", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nCreate metadata information and get an uploadUrl for a file.\n\nTo upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant 'Content-Type' and 'Content-Length' headers.\n\nIf the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request\nas documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.\n\nThe uploadUrl expires after one week.\nAny file info entry that does not have the actual file uploaded within one week will be automatically deleted.\n\nNote: The single part uploadUrl from initFileUpload supports uploading files up to 5000 MB (5,000,000,000 bytes) in size. For larger files than that, please use the multipart upload API.\n\nThe initMultiPartUpload and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1000 GiB in size.\nThese endpoints exposes a uniform multipart upload API for all cloud vendor environments for CDF. Optionally parallel part uploads can be used, for faster uploads.\n\n### Request throttling\nThis endpoint is subject to the new throttling policy, which enforces limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "initFileUpload", "parameters": [ { "in": "header", "name": "Origin", "description": "The 'Origin' header parameter is required if there is a Cross Origin issue.", "schema": { "type": "string" } }, { "in": "query", "name": "overwrite", "schema": { "type": "boolean", "default": false }, "description": "If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false.\n\nIf metadata is included in the request body, all of the original metadata will be overwritten.\nThe actual file will be overwritten after a successful upload with the uploadUrl from the response.\nIf there is no successful upload, the current file contents will be kept.\n\nFile-Asset mappings only change if explicitly stated in the assetIds field of the POST json body.\nDo not set assetIds in request body if you want to keep the current file-asset mappings." } ], "requestBody": { "description": "Fields to be set for the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFilesMetadata" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/UploadFileMetadataResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const fileContent = 'file data here'; // can also be of type ArrayBuffer, Buffer, Blob, File or any\n// automatic upload:\nconst file = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpeg'}, fileContent);\n\n// manual with uploadUrl:\nconst file2 = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpeg'});\n// then upload using the file.uploadUrl" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.files.upload(\"/path/to/file\", name=\"my_file\")\n\nres = client.files.upload(\"/path/to/file\")\n\nres = client.files.upload(\"/path/to/my/directory\")\n\nfrom cognite.client.data_classes import Label\nres = client.files.upload(\"/path/to/file\", name=\"my_file\", labels=[Label(external_id=\"WELL LOG\")])\n\nfrom cognite.client.data_classes import GeoLocation, Geometry\ngeometry = Geometry(type=\"LineString\", coordinates=[[30, 10], [10, 30], [40, 40]])\nres = client.files.upload(\"/path/to/file\", geo_location=GeoLocation(type=\"Feature\", geometry=geometry))\n" }, { "lang": "Java", "label": "Java SDK", "source": "Path fileAOriginal = Paths.get(\"./src/test/resources/csv-data.txt\"); \nList fileContainerInput = new ArrayList<>(); \nFileMetadata fileMetadata = FileMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_file_.test\") \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .build(); \n\n FileContainer fileContainer = FileContainer.newBuilder() \n .setFileMetadata(fileMetadata) \n .setFileBinary(FileBinary.newBuilder() \n .setBinaryUri(fileAOriginal.toUri().toString())) \n .build(); \n fileContainerInput.add(fileContainer); \n\n List uploadFileResult = \n client.files().upload(fileContainerInput); \n\n" } ] }, "get": { "tags": [ "Files" ], "summary": "List files", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nThe GET /files operation can be used to return information for all files in a project.\n\nOptionally you can add one or more of the following query parameters.\nThe filter query parameters will filter the results to only include files that match all filter parameters.\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "listFiles", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Name" }, { "in": "query", "name": "mimeType", "schema": { "$ref": "#/components/schemas/MimeType" } }, { "in": "query", "name": "source", "schema": { "$ref": "#/components/schemas/FileSource" } }, { "in": "query", "name": "assetIds", "schema": { "$ref": "#/components/schemas/AssetIds" } }, { "in": "query", "name": "assetExternalIds", "description": "Asset external IDs of related equipment that this file relates to. Takes 1..100 unique items.", "example": "[\"externalId1\", \"externalId2\", \"externalId3\"]", "schema": { "$ref": "#/components/schemas/JsonArrayString" } }, { "in": "query", "name": "dataSetIds", "schema": { "$ref": "#/components/schemas/DataSetIdEithers" } }, { "in": "query", "name": "rootAssetIds", "description": "Only include files that have a related asset in a tree rooted at any of these root assetIds.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "assetSubtreeIds", "description": "Only include files that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "assetSubtreeExternalIds", "description": "Only include files that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.", "example": "[\"externalId1\", \"externalId2\", \"externalId3\"]", "schema": { "$ref": "#/components/schemas/JsonArrayString" } }, { "in": "query", "name": "minCreatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxCreatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minLastUpdatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxLastUpdatedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minUploadedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxUploadedTime", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minSourceCreatedTime", "description": "Include files that have sourceCreatedTime set and with minimum this value.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxSourceCreatedTime", "description": "Include files that have sourceCreatedTime set and with maximum this value.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "minSourceModifiedTime", "description": "Include files that have sourceModifiedTime set and with minimum this value.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "maxSourceModifiedTime", "description": "Include files that have sourceModifiedTime set and with maximum this value.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "in": "query", "name": "externalIdPrefix", "schema": { "$ref": "#/components/schemas/CogniteExternalIdPrefix" }, "style": "form", "explode": false }, { "in": "query", "name": "uploaded", "description": "Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.", "schema": { "type": "boolean" }, "example": true }, { "$ref": "#/components/parameters/partitionLimited10" } ], "responses": { "200": { "$ref": "#/components/responses/FileMetadataWithCursorResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const files = await client.files.list({filter: {mimeType: 'image/png'}});" }, { "lang": "Python", "label": "Python SDK", "source": "file_list = client.files.list(limit=5, external_id_prefix=\"prefix\")\n\nfor file_metadata in client.files:\n file_metadata # do something with the file metadata\n\nfor file_list in client.files(chunk_size=2500):\n file_list # do something with the files\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"WELL LOG\", \"VERIFIED\"])\nfile_list = client.files.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import GeoLocationFilter, GeometryFilter\nmy_geo_location_filter = GeoLocationFilter(relation=\"intersects\", shape=GeometryFilter(type=\"Point\", coordinates=[35,10]))\nfile_list = client.files.list(geo_location=my_geo_location_filter)\n" } ] } }, "/files/initmultipartupload": { "post": { "tags": [ "Files" ], "summary": "Upload multipart file", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nMultipart file upload enables upload of files larger than 5000 MB, using a uniform API on all cloud environments for CDF.\n\nEach file part must be larger than 5 MiB, and smaller than 4000 MiB. The file part for the last uploadURL can be smaller than 5 MiB. Maximum 250 upload URLs can be requested.\nThe supported maximum size for each file uploaded with the multi-part upload API is therefore 1000 GiB (1.073 TB / 0.976 TiB).\nThe client should calculate the ideal number of parts depending on predetermined or estimated file size, between 1 and the maximum.\nSpecify the number of parts in the `parts` URL query parameter. The `parts` parameter is required.\n\nThe request creates metadata information for a new file, and returns in addition to the file `id`, also a `uploadId`, and a list of `uploadUrls` for uploading the file contents.\nTo upload a file, send an HTTP PUT request to each of the uploadUrls, with the corresponding part of the file in the request body.\nYou may use a 'Content-Length' header in the PUT request for each part, but this is not required.\nA failed part PUT upload can be retried.\n\nThe client must ensure that the parts of the source file are stored in the correct order, using the order of the `uploadUrls` as specified in the response.\nThis to avoid ending up with a corrupt final file.\n\nThe parts can optionally be uploaded in parallel, preferably on a subset of parts at a time, for example maximum 3 concurrent PUT operations.\n\nOnce all file parts have been uploaded, the client should call the 'files/completemultipartupload' endpoint,\nwith the required file ID (as `id` or `externalId`) and `uploadId` fields in the request body. This will assemble the parts into one file.\nThe file's `uploaded` flag will then eventually be set to `true`.\n\nA standard sequence of calls to upload a large file with multipart upload would be for example as follows:\n1. POST files/initmultipartupload?parts=8, to start a multipart upload session with 8 parts. Expect a 201 CREATED response code, and a response body with information to be used in the part uploads and completemultipartupload requests.\n2. PUT `uploadUrl`, for each of the `uploadUrls` in the response from files/initmultipartupload. Expect a 200 OK or 201 CREATED response for each PUT request.\n3. POST files/completemultipartupload, with request body '{ \"id\":123456789, \"uploadId\":\"ABCD4321EFGH\" }'. This will assemble the file. Expect a 200 OK response.\n\nConsider verifying that the file is eventually marked as uploaded with a call to the getFileByInternalId endpoint.\n\nNOTE: The uploadUrls expires after one week.\nA file that does not have the file content parts uploaded and completed within one week will be automatically deleted.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "initMultiPartUpload", "parameters": [ { "in": "query", "name": "overwrite", "schema": { "type": "boolean", "default": false }, "description": "If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false.\n\nIf metadata is included in the request body, all of the original metadata will be overwritten.\nThe actual file will be overwritten after a successful upload with the uploadUrls from the response.\nIf there is no successful upload, the current file contents will be kept.\n\nFile-Asset mappings only change if explicitly stated in the assetIds field of the POST json body.\nDo not set assetIds in request body if you want to keep the current file-asset mappings." }, { "in": "query", "name": "parts", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 250 }, "description": "The 'parts' parameter specifies how many uploadURLs should be returned, for uploading the file contents in parts. See main endpoint description for more details." } ], "requestBody": { "description": "Fields to be set for the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFilesMetadata" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/MultiPartUploadFileMetadataResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ] } }, "/files/uploadlink": { "post": { "tags": [ "Files" ], "summary": "Get upload file link", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`\n\nGet an uploadUrl for a file.\n\nTo upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant 'Content-Type' and 'Content-Length' headers.\n\nIf the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request\nas documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.\n\nThe uploadUrl expires after one week.\nAny file info entry that does not have the actual file uploaded within one week will be automatically deleted.\n\nNote: The single part uploadUrl from getUploadLink only supports uploading files up to 5000 MB (5,000,000,000 bytes) in size.\n\nThe getMultiPartUploadLink and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1000 GiB in size.\nThese endpoints exposes a uniform multipart upload API for all cloud vendor environments for CDF. Optionally parallel part uploads can be used, for faster uploads.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "getUploadLink", "parameters": [ { "in": "header", "name": "Origin", "description": "The 'Origin' header parameter is required if there is a Cross Origin issue.", "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to be set for the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDataUploadIds" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/UploadFileMetadataResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ], "x-cdm-capability": [ "dataModelInstancesAcl:WRITE" ] } }, "/files/multiuploadlink": { "post": { "tags": [ "Files" ], "summary": "Get multipart file upload link", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`\n\nMultipart file upload enables upload of files larger than 5000 MB, using a uniform API on all cloud environments for CDF.\n\nEach file part must be larger than 5 MiB, and smaller than 4000 MiB. The file part for the last uploadURL can be smaller than 5 MiB. Maximum 250 upload URLs can be requested.\nThe supported maximum size for each file uploaded with the multi-part upload API is therefore 1000 GiB (1.073 TB / 0.976 TiB).\nThe client should calculate the ideal number of parts depending on predetermined or estimated file size, between 1 and the maximum.\nSpecify the number of parts in the `parts` URL query parameter. The `parts` parameter is required.\n\nThe request returns in addition to the file `id`, also a `uploadId`, and a list of `uploadUrls` for uploading the file contents.\nTo upload a file, send an HTTP PUT request to each of the uploadUrls, with the corresponding part of the file in the request body.\nYou may use a 'Content-Length' header in the PUT request for each part, but this is not required.\nA failed part PUT upload can be retried.\n\nThe client must ensure that the parts of the source file are stored in the correct order, using the order of the `uploadUrls` as specified in the response.\nThis to avoid ending up with a corrupt final file.\n\nThe parts can optionally be uploaded in parallel, preferably on a subset of parts at a time, for example maximum 3 concurrent PUT operations.\n\nOnce all file parts have been uploaded, the client should call the 'files/completemultipartupload' endpoint,\nwith the required file ID (as `id` or `externalId`) and `uploadId` fields in the request body. This will assemble the parts into one file.\nThe file's `uploaded` flag will then eventually be set to `true`.\n\nA standard sequence of calls to upload a large file with multipart upload would be for example as follows:\n1. POST files/initmultipartupload?parts=8, to start a multipart upload session with 8 parts. Expect a 201 CREATED response code, and a response body with information to be used in the part uploads and completemultipartupload requests.\n2. PUT `uploadUrl`, for each of the `uploadUrls` in the response from files/initmultipartupload. Expect a 200 OK or 201 CREATED response for each PUT request.\n3. POST files/completemultipartupload, with request body '{ \"id\":123456789, \"uploadId\":\"ABCD4321EFGH\" }'. This will assemble the file. Expect a 200 OK response.\n\nConsider verifying that the file is eventually marked as uploaded with a call to the getFileByInternalId endpoint.\n\nNOTE: The uploadUrls expires after one week.\nA file that does not have the file content parts uploaded and completed within one week will be automatically deleted.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "getMultiPartUploadLink", "parameters": [ { "in": "query", "name": "parts", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 250 }, "description": "The 'parts' parameter specifies how many uploadURLs should be returned, for uploading the file contents in parts. See main endpoint description for more details." } ], "requestBody": { "description": "Fields to be set for the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDataUploadIds" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/MultiPartUploadFileMetadataResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ], "x-cdm-capability": [ "dataModelInstancesAcl:WRITE" ] } }, "/files/{id}": { "get": { "tags": [ "Files" ], "summary": "Retrieve a file by its ID", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nReturns file info for the file ID\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "getFileByInternalId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/CogniteInternalId" } } ], "responses": { "200": { "$ref": "#/components/responses/FileMetadataResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-cdm-capability": [ "dataModelInstancesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const files = await client.files.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.files.retrieve(id=1)\n\nres = client.files.retrieve(external_id=\"1\")\n" } ] } }, "/files/list": { "post": { "tags": [ "Files" ], "summary": "Filter files", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nRetrieves a list of all files in a project. Criteria can be supplied to\nselect a subset of files. This operation supports pagination with cursors.\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "advancedListFiles", "requestBody": { "description": "The project name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFilterRequest" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/FileMetadataWithCursorResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const files = await client.files.list({filter: {mimeType: 'image/png'}});" }, { "lang": "Python", "label": "Python SDK", "source": "file_list = client.files.list(limit=5, external_id_prefix=\"prefix\")\n\nfor file_metadata in client.files:\n file_metadata # do something with the file metadata\n\nfor file_list in client.files(chunk_size=2500):\n file_list # do something with the files\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"WELL LOG\", \"VERIFIED\"])\nfile_list = client.files.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import GeoLocationFilter, GeometryFilter\nmy_geo_location_filter = GeoLocationFilter(relation=\"intersects\", shape=GeometryFilter(type=\"Point\", coordinates=[35,10]))\nfile_list = client.files.list(geo_location=my_geo_location_filter)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listFilesResults = new ArrayList<>(); \nclient.files() \n .list() \n .forEachRemaining(files -> listFilesResults.addAll(files)); \n\nclient.files() \n .list(Request.create() \n .withFilterParameter(\"source\", \"sourceValue\")) \n .forEachRemaining(files -> listFilesResults.addAll(files)); \n\n" } ] } }, "/files/byids": { "post": { "tags": [ "Files" ], "summary": "Retrieve files", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nRetrieves metadata information about multiple specific files in the same project.\nResults are returned in the same order as in the request. This operation does not return the file contents.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "byIdsFiles", "requestBody": { "description": "List of IDs of files to retrieve. Must be up to a maximum of 1000 IDs, and all of them must be unique.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDataIdsWithIgnoreUnknownIds" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/FileResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-cdm-capability": [ "dataModelInstancesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const files = await client.files.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.files.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.files.retrieve_multiple(external_ids=[\"abc\", \"def\"])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List retrievedFilesByExternalIds = client.files().retrieve(\"10\");//by varargs of String \nList itemsExternalId = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList resultsExternal = client.files().retrieve(itemsExternalId);//by list of items \n\nList retrievedFilesByInternalIds = client.files().retrieve(10, 20);//by varargs of Long \nList itemsInternalId = List.of(Item.newBuilder().setId(10).build()); \nList resultsInternal = client.files().retrieve(itemsInternalId);//by list of items \n\n" } ] } }, "/files/search": { "post": { "tags": [ "Files" ], "summary": "Search files", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nSearch for files based on relevance.\nYou can also supply a strict match filter as in Filter files, and search in the results from the filter.\nReturns first 1000 results based on relevance. This operation does not support pagination.\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "searchFiles", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesSearchFilter" } } } }, "responses": { "200": { "$ref": "#/components/responses/FileResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const files = await client.files.search({\n filter: {\n mimeType: 'image/jpeg',\n },\n search: {\n name: 'Pump'\n }\n});" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.files.search(name=\"some name\")\n\nmy_label_filter = LabelFilter(contains_all=[\"WELL LOG\"])\nres = client.assets.search(name=\"xyz\",filter=FileMetadataFilter(labels=my_label_filter))\n" } ] } }, "/files/delete": { "post": { "tags": [ "Files" ], "summary": "Delete files", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nDeletes the files with the given ids.\n\nA maximum of 1000 files can be deleted per request.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "deleteFiles", "requestBody": { "description": "List of IDs of files to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteByIds" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.files.delete([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.files.delete(id=[1,2,3], external_id=\"3\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List deleteByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList deleteItemsResults = client.files().delete(deleteByExternalIds); \n\nList deleteByInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList deleteItemsResults = client.files().delete(deleteByInternalIds); \n\n" } ] } }, "/files/downloadlink": { "post": { "tags": [ "Files" ], "summary": "Download files", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nRetrieves a list of download URLs for the specified list of file IDs.\nAfter getting the download links, the client has to issue a GET request to the returned URLs,\nwhich will respond with the contents of the file. The links will by default expire after 30 seconds.\nIf providing the query parameter extendedExpiration the links will expire after 1 hour.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "downloadLinks", "parameters": [ { "in": "query", "name": "extendedExpiration", "schema": { "type": "boolean", "default": false, "description": "if set to true, will extend the expiration period of the link to 1 hour." } } ], "requestBody": { "description": "List of file IDs to retrieve the download URL for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileLinkIds" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/DataWithLinks" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-cdm-capability": [ "dataModelInstancesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.files.getDownloadUrls([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.files.download(directory=\"my_directory\", id=[1,2,3], external_id=[\"abc\", \"def\"])\n\nclient.files.download(directory=\".\", id=[1,2,3])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List downloadByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList downloadFilesResults = \n client.files().downloadToPath(downloadByExternalIds, Paths.get(\"\")); \n\nList downloadByInternallIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList downloadFilesResults = \n client.files().downloadToPath(downloadByInternallIds, Paths.get(\"\")); \n\n" } ] } }, "/files/icon": { "get": { "tags": [ "Files" ], "summary": "Get icon", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nThe GET /files/icon operation can be used to get an image representation of a file.\n\nEither id or externalId must be provided as a query parameter (but not both).\nSupported file formats:\n- Normal jpeg and png files are currently fully supported.\n- Other image file formats might work, but continued support for these are not guaranteed.\n- Currently only supporting thumbnails for image files.\nAttempts to get icon for unsupported files will result in status 400.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "getIcon", "parameters": [ { "in": "query", "name": "id", "schema": { "$ref": "#/components/schemas/CogniteInternalId" } }, { "in": "query", "name": "externalId", "schema": { "$ref": "#/components/schemas/CogniteExternalId" } }, { "in": "query", "name": "space", "schema": { "$ref": "#/components/schemas/InstanceSpace" } }, { "in": "query", "name": "instanceExternalId", "schema": { "$ref": "#/components/schemas/InstanceExternalId" } } ], "responses": { "200": { "description": "Thumbnail image (JPEG)", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-cdm-capability": [ "dataModelInstancesAcl:READ" ] } }, "/files/update": { "post": { "tags": [ "Files" ], "summary": "Update files", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nUpdates the information for the files specified in the request body.\n\nIf you want to update the file content, uploaded using the uploadUrl, please\nuse the initFileUpload request with the query parameter 'overwrite=true'.\nAlternatively, delete and recreate the file.\n\nFor primitive fields (String, Long, Int), use 'set': 'value' to update\nvalue; use 'setNull': true to set that field to null.\n\nFor the Json Array field (e.g. assetIds and securityCategories): Use either only 'set', or a combination of 'add' and/or 'remove'.\n\n__AssetIds update examples__:\n\nExample request body to overwrite assetIds with a new set, asset ID 1 and 2.\n\n```\n{\n \"items\": [\n {\n \"id\": 1,\n \"update\": {\n \"assetIds\" : {\n \"set\" : [ 1, 2 ]\n }\n }\n }\n ]\n}\n```\n\nExample request body to add one asset Id, and remove another asset ID.\n\n```\n{\n \"items\": [\n {\n \"id\": 1,\n \"update\": {\n \"assetIds\" : {\n \"add\" : [ 3 ],\n \"remove\": [ 2 ]\n }\n }\n }\n ]\n}\n```\n\n__Metadata update examples__:\n\nExample request body to overwrite metadata with a new set.\n```\n{\n \"items\": [\n {\n \"id\": 1,\n \"update\": {\n \"metadata\": {\n \"set\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n }\n }\n }\n }\n ]\n}\n```\n\nExample request body to add two key-value pairs and remove two other key-value pairs by key for\nthe metadata field.\n```\n{\n \"items\": [\n {\n \"id\": 1,\n \"update\": {\n \"metadata\": {\n \"add\": {\n \"key3\": \"value3\",\n \"key4\": \"value4\"\n },\n \"remove\": [\n \"key1\",\n \"key2\"\n ]\n }\n }\n }\n ]\n}\n```\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "updateFiles", "requestBody": { "description": "The JSON request body which specifies which files and fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataFileChange" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/FileResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const files = await client.files.update([{\n id: 123,\n update: {\n source: { set: 'new source' }\n }\n}]);" }, { "lang": "Python", "label": "Python SDK", "source": "file_metadata = client.files.retrieve(id=1)\nfile_metadata.description = \"New description\"\nres = client.files.update(file_metadata)\n\nfrom cognite.client.data_classes import FileMetadataUpdate\nmy_update = FileMetadataUpdate(id=1).source.set(\"new source\").metadata.add({\"key\": \"value\"})\nres = client.files.update(my_update)\n\nfrom cognite.client.data_classes import FileMetadataUpdate\nmy_update = FileMetadataUpdate(id=1).labels.add([\"PUMP\", \"VERIFIED\"])\nres = client.files.update(my_update)\n\nfrom cognite.client.data_classes import FileMetadataUpdate\nmy_update = FileMetadataUpdate(id=1).labels.remove(\"PUMP\")\nres = client.files.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List editFilesInput = listFilesResults.stream() \n .map(fileMetadata -> fileMetadata.toBuilder() \n .putMetadata(\"addedField\", \"new field value\") \n .build()) \n .collect(Collectors.toList()); \n\n List editFilesResult = \n client.files().upsert(editFilesInput); \n\n" } ] } }, "/files/aggregate": { "post": { "tags": [ "Files" ], "summary": "Aggregate files", "description": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nCalculate aggregates for files, based on optional filter specification.\nReturns the following aggregates: `count`\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "aggregateFiles", "requestBody": { "description": "Files aggregate request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFilter" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/FilesAggregateResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const aggregates = await client.files.aggregate({ filter: { uploaded: true } });\nconsole.log('Number of uploaded files: ', aggregates[0].count)" }, { "lang": "Python", "label": "Python SDK", "source": "aggregate_uploaded = client.files.aggregate(filter={\"uploaded\": True})\n" }, { "lang": "Java", "label": "Java SDK", "source": "Aggregate fileAggregate = \n client.files().aggregate(Request.create() \n .withFilterParameter(\"source\", \"source\")); \n\n" } ] } }, "/files/completemultipartupload": { "post": { "tags": [ "Files" ], "summary": "Complete multipart upload", "description": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`\n\nCompletes a multipart file upload.\nThis endpoint must be called by the client when an 'initMultiPartUpload' operation (POST /files/initmultipartupload) was called,\nand all file content parts have been successfully uploaded using PUT for all upload URLs.\nEither `id` or `externalId` must be specified in the request body, but not both. The `uploadId` is also required.\nThe values for these properties can be retrieved from the response of the initMultiPartUpload operation.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../).", "operationId": "completeMultiPartUpload", "requestBody": { "required": true, "description": "The JSON request body which specifies which file id/externalId and uploadId to complete the multipart upload for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteMultiPartUpload" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "filesAcl:WRITE" ], "x-cdm-capability": [ "dataModelInstancesAcl:WRITE" ] } }, "/functions": { "get": { "tags": [ "Functions" ], "summary": "List functions", "operationId": "getFunctions", "parameters": [ { "$ref": "#/components/parameters/LimitQuery" } ], "responses": { "200": { "$ref": "#/components/responses/FunctionList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nList functions.", "x-capability": [ "functionsAcl:READ" ] }, "post": { "summary": "Create functions", "operationId": "postFunctions", "responses": { "201": { "$ref": "#/components/responses/FunctionList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "\n\n> **Required capabilities:** `functionsAcl:WRITE`\n\nYou can only create one function per request.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of functions to create.", "maxItems": 1, "minItems": 1, "items": { "$ref": "#/components/schemas/Function" } } }, "required": [ "items" ] }, "examples": { "Minimal function": { "value": { "items": [ { "name": "My awesome function", "fileId": 5467347282343 } ] } }, "With secrets": { "value": { "items": [ { "name": "My awesome function", "fileId": 5467347282343, "secrets": { "key1": "secret1", "key2": "secret2" } } ] } }, "Full example": { "value": { "items": [ { "name": "My awesome function", "description": "This function does some things", "owner": "user@cognite.com", "fileId": 5467347282343, "externalId": "my-function", "metadata": { "key1": "value1", "key2": "value2" }, "secrets": { "key1": "secret1", "key2": "secret2" }, "functionPath": "myfunction/handler.py", "envVars": { "ENV_VAR": "value" }, "cpu": 0.2, "memory": 0.4, "runtime": "py313", "indexUrl": "https://pypi.org", "extraIndexUrls": [ "https://user:password@some.index.org" ] } ] } } } } }, "description": "" }, "tags": [ "Functions" ], "x-capability": [ "functionsAcl:WRITE" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "function = client.functions.create(\n name=\"myfunction\",\n folder=\"path/to/code\",\n function_path=\"path/to/function.py\")\n\nfunction = client.functions.create(\n name=\"myfunction\", file_id=123, function_path=\"path/to/function.py\")\n\nfunction = client.functions.create(name=\"myfunction\", function_handle=handle)\n\ndef handle(client, data):\n \"\"\"\n [requirements]\n numpy\n [/requirements]\n \"\"\"\n pass\nfunction = client.functions.create(name=\"myfunction\", function_handle=handle)\n" } ] } }, "/functions/limits": { "get": { "tags": [ "Functions" ], "summary": "Functions limits", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nService limits for the associated project.", "operationId": "functionsLimits", "responses": { "200": { "$ref": "#/components/responses/FunctionsLimits" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "functionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "limits = client.functions.limits()\n" } ] } }, "/functions/list": { "post": { "summary": "Filter functions", "operationId": "listFunctions", "responses": { "200": { "$ref": "#/components/responses/FunctionList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "Use advanced filtering options to find functions.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionListScope" }, "examples": { "Filter by status": { "value": { "filter": { "status": "Queued", "createdTime": { "min": 10, "max": 199 } } } } } } } }, "tags": [ "Functions" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "functions_list = client.functions.list()\n" } ] } }, "/functions/delete": { "post": { "summary": "Delete functions", "operationId": "deleteFunctions", "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "\n\n> **Required capabilities:** `functionsAcl:WRITE`\n\nDelete functions. You can delete a maximum of 10 functions per request. Function source files stored in the Files API must be deleted separately.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionDeleteRequest" } } } }, "tags": [ "Functions" ], "x-capability": [ "functionsAcl:WRITE" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.functions.delete(id=[1,2,3], external_id=\"function3\")\n" } ] } }, "/functions/{functionId}/call": { "parameters": [ { "$ref": "#/components/parameters/functionId" } ], "post": { "tags": [ "Function calls" ], "x-capability": [ "functionsAcl:RUN" ], "summary": "Call a function asynchronously", "operationId": "postFunctionsCall", "responses": { "201": { "$ref": "#/components/responses/FunctionCalled" }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "The response for too many requests (concurrency or rate throttling).", "content": { "application/json": { "schema": { "$ref": "#/components/responses/429ErrorResponse/content/application~1json/schema" }, "example": { "error": { "code": 429, "message": "Function {function_id} has reached maximum number of concurrent calls. Limit is 100." } } } } } }, "description": "\n\n> **Required capabilities:** `functionsAcl:RUN`\n\nPerform a function call. To provide input data to the function, add the data in an object called `data` in the request body. It will be available as the `data` argument into the function. Info about the function call at runtime can be obtained through the `function_call_info` argument if added in the function handle. **WARNING:** Secrets or other confidential information should not be passed via the `data` object. There is a dedicated `secrets` object in the request body to \"Create functions\" for this purpose.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionCallRequest" } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "call = client.functions.call(id=1)\n\nfunc = client.functions.retrieve(id=1)\ncall = func.call()\n" } ] } }, "/functions/{functionId}/calls": { "parameters": [ { "$ref": "#/components/parameters/functionId" }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "summary": "List function calls", "responses": { "200": { "$ref": "#/components/responses/FunctionCallListWithCursor" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getFunctionCalls", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nList function calls.", "tags": [ "Function calls" ], "x-capability": [ "functionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "logs = client.functions.calls.get_logs(call_id=2, function_id=1)\n\ncall = client.functions.calls.retrieve(call_id=2, function_id=1)\nlogs = call.get_logs()\n" } ] } }, "/functions/{functionId}/calls/byids": { "parameters": [ { "$ref": "#/components/parameters/functionId" } ], "post": { "summary": "Retrieve calls", "requestBody": { "description": "List of IDs of calls to retrieve. Must be up to a maximum of 10000 items and all of them must be unique.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/FunctionCallIds" }, { "$ref": "#/components/schemas/IgnoreUnknownIdsField" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/FunctionCallList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "byIdsFunctionCalls", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve function calls by call ids.", "tags": [ "Function calls" ], "x-capability": [ "functionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "call = client.functions.calls.retrieve(call_id=2, function_id=1)\n\nfunc = client.functions.retrieve(id=1)\ncall = func.retrieve_call(id=2)\n" } ] } }, "/functions/{functionId}/calls/{callId}": { "parameters": [ { "$ref": "#/components/parameters/callId" }, { "$ref": "#/components/parameters/functionId" } ], "get": { "operationId": "getFunctionCall", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve function calls.", "tags": [ "Function calls" ], "x-capability": [ "functionsAcl:READ" ], "summary": "Retrieve a function call by its id", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionCall" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/functions/{functionId}/calls/{callId}/logs": { "parameters": [ { "$ref": "#/components/parameters/callId" }, { "$ref": "#/components/parameters/functionId" } ], "get": { "tags": [ "Function calls" ], "x-capability": [ "functionsAcl:READ" ], "summary": "Retrieve logs for function call", "responses": { "200": { "$ref": "#/components/responses/FunctionCallLog" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getFunctionCallLogs", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nGet logs from a function call." } }, "/functions/{functionId}": { "parameters": [ { "$ref": "#/components/parameters/functionId" } ], "get": { "operationId": "getFunction", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve a function by its id. If you want to retrieve functions by names, use Retrieve functions instead.", "x-capability": [ "functionsAcl:READ" ], "summary": "Retrieve a function by its id", "tags": [ "Functions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Function" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/functions/byids": { "post": { "tags": [ "Functions" ], "x-capability": [ "functionsAcl:READ" ], "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve functions by ids.", "summary": "Retrieve functions", "operationId": "byIdsFunctions", "responses": { "200": { "$ref": "#/components/responses/FunctionList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionIdEitherList" } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.functions.retrieve(id=1)\n\nres = client.functions.retrieve(external_id=\"abc\")\nres = client.functions.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.functions.retrieve_multiple(external_ids=[\"func1\", \"func2\"])\n" } ] } }, "/functions/status": { "post": { "summary": "Activate Functions", "responses": { "202": { "$ref": "#/components/responses/FunctionsActivation" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "postFunctionsStatus", "description": "\n\n> **Required capabilities:** `functionsAcl:WRITE`\n\nActivate Cognite Functions. This will create the necessary backend infrastructure for Cognite Functions.", "tags": [ "Functions" ], "x-capability": [ "functionsAcl:WRITE" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "status = client.functions.activate()\n" } ] }, "get": { "summary": "Get activation status", "responses": { "200": { "$ref": "#/components/responses/FunctionsActivation" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getFunctionsStatus", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nGet activation status", "tags": [ "Functions" ], "x-capability": [ "functionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "status = client.functions.status()\n" } ] } }, "/functions/schedules": { "get": { "parameters": [ { "$ref": "#/components/parameters/LimitQuery" } ], "operationId": "getFunctionSchedules", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nList function schedules in project.", "tags": [ "Function schedules" ], "x-capability": [ "functionsAcl:READ" ], "summary": "List schedules", "responses": { "200": { "$ref": "#/components/responses/FunctionScheduleList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "description": "\n\n> **Required capabilities:** `functionsAcl:WRITE`\n\nCreate function schedules. Function schedules trigger asynchronous calls with specific input data, based on a cron expression that determines when these triggers should be fired. Use e.g. http://www.cronmaker.com to be guided on how to generate a cron expression. One of `FunctionId` or `FunctionExternalId` (deprecated) must be set (but not both). When creating a schedule with a session, i.e. with a `nonce`, `FunctionId` must be used. The `nonce` will be used to bind the session before function execution, and the session will be kept alive for the lifetime of the schedule. **WARNING:** Secrets or other confidential information should not be passed via the `data` object. There is a dedicated `secrets` object in the request body to \"Create functions\" for this purpose.", "tags": [ "Function schedules" ], "x-capability": [ "functionsAcl:WRITE" ], "summary": "Create schedules", "operationId": "postFunctionSchedules", "responses": { "201": { "$ref": "#/components/responses/FunctionScheduleCreated" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 1, "minItems": 1, "items": { "$ref": "#/components/schemas/FunctionSchedule" } } } } } }, "description": "" }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "import os\nfrom cognite.client.data_classes import ClientCredentials\nschedule = client.functions.schedules.create(\n name=\"My schedule\",\n function_id=123,\n cron_expression=\"*/5 * * * *\",\n client_credentials=ClientCredentials(\"my-client-id\", os.environ[\"MY_CLIENT_SECRET\"]),\n description=\"This schedule does magic stuff.\",\n data={\"magic\": \"stuff\"},\n)\n\nschedule = client.functions.schedules.create(\n name=\"My schedule\",\n function_id=456,\n cron_expression=\"*/5 * * * *\",\n description=\"A schedule just used for some temporary testing.\",\n)\n" } ] } }, "/functions/schedules/list": { "post": { "summary": "Filter function schedules", "operationId": "listFunctionSchedules", "responses": { "200": { "$ref": "#/components/responses/FunctionScheduleList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "Use advanced filtering options to find function schedules. At most one of `FunctionId` or `FunctionExternalId` can be specified.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionScheduleScope" }, "examples": { "Filter by status": { "value": { "filter": { "name": "MySchedule", "cronExpression": "5 4 * * *" } } } } } } }, "tags": [ "Function schedules" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "schedules = client.functions.schedules.list()\n\nfunc = client.functions.retrieve(id=1)\nschedules = func.list_schedules(limit=None)\n" } ] } }, "/functions/schedules/{scheduleId}": { "parameters": [ { "$ref": "#/components/parameters/scheduleId" } ], "get": { "operationId": "getFunctionSchedule", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve a function schedule by its id.", "tags": [ "Function schedules" ], "x-capability": [ "functionsAcl:READ" ], "summary": "Retrieve a function schedule by its id", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionSchedule" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/functions/schedules/byids": { "post": { "summary": "Retrieve schedules", "requestBody": { "description": "List of IDs of schedules to retrieve. Must be up to a maximum of 10000 items and all of them must be unique.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/FunctionScheduleIds" }, { "$ref": "#/components/schemas/IgnoreUnknownIdsField" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/FunctionScheduleList" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "byIdsFunctionSchedules", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve function schedules by schedule ids.", "tags": [ "Function schedules" ], "x-capability": [ "functionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.functions.schedules.retrieve(id=1)\n" } ] } }, "/functions/schedules/delete": { "post": { "tags": [ "Function schedules" ], "x-capability": [ "functionsAcl:WRITE" ], "summary": "Delete schedules", "operationId": "deleteFunctionSchedules", "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "\n\n> **Required capabilities:** `functionsAcl:WRITE`\n\nDelete function schedules.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionScheduleIdArray" } } } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.functions.schedules.delete(id = 123)\n" } ] } }, "/functions/schedules/{scheduleId}/input_data": { "parameters": [ { "$ref": "#/components/parameters/scheduleId" } ], "get": { "operationId": "getFunctionScheduleInputData", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve the input data to the associated function.", "summary": "Retrieve function input data", "tags": [ "Function schedules" ], "x-capability": [ "functionsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/FunctionScheduleDataResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.functions.schedules.get_input_data(id=123)\n" } ] } }, "/functions/{functionId}/calls/{callId}/response": { "parameters": [ { "$ref": "#/components/parameters/callId" }, { "$ref": "#/components/parameters/functionId" } ], "get": { "summary": "Retrieve response for function call", "tags": [ "Function calls" ], "responses": { "200": { "$ref": "#/components/responses/FunctionCallResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getFunctionCallResponse", "parameters": [], "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nRetrieve response from a function call.", "x-capability": [ "functionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "response = client.functions.calls.get_response(call_id=2, function_id=1)\n\ncall = client.functions.calls.retrieve(call_id=2, function_id=1)\nresponse = call.get_response()\n" } ] } }, "/functions/{functionId}/calls/list": { "parameters": [ { "$ref": "#/components/parameters/functionId" } ], "post": { "summary": "Filter function calls", "operationId": "listFunctionCalls", "responses": { "200": { "$ref": "#/components/responses/FunctionCallListWithCursor" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "description": "Use advanced filtering options to find function calls.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionCallListScope" }, "examples": { "Filter by status": { "value": { "filter": { "status": "Running", "scheduleId": 123, "startTime": { "min": 1234, "max": 5678 } }, "limit": 10 } } } } } }, "tags": [ "Function calls" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "calls = client.functions.calls.list(function_id=1)\n\nfunc = client.functions.retrieve(id=1)\ncalls = func.list_calls()\n" } ] } }, "/function-apps": { "get": { "tags": [ "Function Apps" ], "summary": "List Function Apps", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nList all functions in the project.", "operationId": "listFunctionApps", "x-capability": [ "functionsAcl:READ" ], "parameters": [ { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Function" } } } } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/function-apps/{functionExternalId}": { "get": { "tags": [ "Function Apps" ], "summary": "Get Function App", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nGet details of a specific Function App.\n\nReturns metadata about the function including name, status,\nruntime, etc.", "operationId": "getFunctionApp", "x-capability": [ "functionsAcl:READ" ], "parameters": [ { "$ref": "#/components/parameters/functionExternalId" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Function" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/function-apps/{functionExternalId}/calls": { "post": { "tags": [ "Function App Calls" ], "summary": "Call Function Endpoint", "description": "\n\n> **Required capabilities:** `functionsAcl:WRITE`\n\nCall a function app endpoint via a request envelope.\n\nThe SDK constructs a `FunctionAppCallRequest` containing the target path,\nHTTP method, request body, and session nonce. The API validates and\nforwards it to the function.\n\n**Response passthrough:** The function's typed response envelope is\nreturned as-is in the HTTP body. The HTTP status code is always `200`\nwhen the function call completes (regardless of the function's own\nstatus code). Non-200 HTTP status indicates an API-level failure.\n\n**Async mode:** Send `Prefer: respond-async` to receive HTTP 202\nwith a `Location` header pointing to the poll URL.\n\n**Example:**\n```json\n{\n \"data\": {\n \"path\": \"/items/123\",\n \"method\": \"GET\",\n \"body\": {}\n },\n \"nonce\": \"session-nonce\"\n}\n```", "operationId": "createFunctionAppCall", "x-capability": [ "functionsAcl:WRITE" ], "parameters": [ { "$ref": "#/components/parameters/functionExternalId" }, { "$ref": "#/components/parameters/preferHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionAppCallRequest" } } } }, "responses": { "200": { "description": "Successful Response\n\nThe response contains the function call result envelope.\n`runtimeStatus` indicates the outcome: `Completed`, `Failed`, or `Timeout`.\nThe `response` field is present only for `Completed` calls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionAppCallRuntimeResponse" }, "example": { "callId": 123456, "functionId": 789, "runtimeStatus": "Completed", "response": { "status_code": 200, "data": { "id": "item-123", "name": "Example item", "created_at": "2026-03-22T12:00:00Z" } } } } } }, "202": { "description": "Accepted (async mode)\n\nReturned when `Prefer: respond-async` is set.\nThe `Location` header points to the poll URL.", "headers": { "Location": { "schema": { "type": "string" }, "description": "URL to poll for the result" } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "429": { "description": "The response for too many requests (concurrency or rate throttling).", "content": { "application/json": { "schema": { "$ref": "#/components/responses/429ErrorResponse/content/application~1json/schema" }, "example": { "error": { "code": 429, "message": "Function {function_id} has reached maximum number of concurrent calls. Limit is 100." } } } } } } }, "get": { "tags": [ "Function App Calls" ], "summary": "List Calls", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nList all calls for a function.", "operationId": "listFunctionAppCalls", "x-capability": [ "functionsAcl:READ" ], "parameters": [ { "$ref": "#/components/parameters/functionExternalId" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FunctionCall" } } } } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/function-apps/{functionExternalId}/calls/{callId}/response": { "get": { "tags": [ "Function App Calls" ], "summary": "Get Call Response", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nGet the response from a completed function call.", "operationId": "getFunctionAppCallResponse", "x-capability": [ "functionsAcl:READ" ], "parameters": [ { "$ref": "#/components/parameters/functionExternalId" }, { "$ref": "#/components/parameters/callId" } ], "responses": { "200": { "$ref": "#/components/responses/FunctionCallResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/function-apps/{functionExternalId}/calls/{callId}/logs": { "get": { "tags": [ "Function App Calls" ], "summary": "Get Call Logs", "description": "\n\n> **Required capabilities:** `functionsAcl:READ`\n\nGet logs from a function call.", "operationId": "getFunctionAppCallLogs", "x-capability": [ "functionsAcl:READ" ], "parameters": [ { "$ref": "#/components/parameters/functionExternalId" }, { "$ref": "#/components/parameters/callId" } ], "responses": { "200": { "$ref": "#/components/responses/FunctionCallLog" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/function-apps/{functionExternalId}/mcp": { "parameters": [ { "$ref": "#/components/parameters/functionExternalId" } ] }, "/3d/files/{threedFileId}": { "get": { "tags": [ "3D Files" ], "summary": "Retrieve a single 3D file", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieve the contents of a 3D file. This applies to the output types 'ciff-processed', 'ciff-partially-processed' and 'node-property-metadata-json'.\n\nThis endpoint supports tag-based caching.\n\nThis endpoint is only compatible with 3D file IDs from the 3D API, and not compatible with\nfile IDs from the Files API.", "operationId": "get3DFile", "parameters": [ { "name": "threedFileId", "in": "path", "description": "The ID of the 3D file to retrieve.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "*/*": { "schema": { "type": "string", "description": "The raw contents of the file.", "format": "binary" } } }, "headers": { "Content-Type": { "schema": { "type": "string" }, "description": "The media type of the file." } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.files3D.retrieve(3744350296805509);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.files.retrieve(1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "client.threeD().files().downloadToPath(1L, Paths.get(\"\")); \n\n" } ] } }, "/3d/files/{threedFileId}/{subPath}": { "get": { "tags": [ "3D Files" ], "summary": "Retrieve a 3D directory file", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieve the contents of a 3D file, for a blobId which is of a directory type.\nThis applies to the output types 'gltf-directory', 'reveal-directory', 'ept-pointcloud', 'tiles-directory', 'model-from-points'.\n\nThe 'subPath' elements, i.e. directory and/or file names, within each directory output type is subject to change and depends on each output type.\n- The 'gltf-directory' output is used by Reveal v3+ for visualizing CAD files and contains a 'scene.json' file, which describes what other files are available within the blobId.\n- The 'reveal-directory' output is used by Reveal v1-2 for visualizing CAD files and contains a 'scene.json' file, which describes what other files are available within the blobId.\n- The 'ept-pointcloud' output is used by Reveal for visualizing point clouds, and contains a 'ept.json' file. The 'ept.json' file contains general information for the point cloud data. The file named 'ept-hierarchy/0-0-0-0.json' for the same blobId lists all the output point files which can be retrieved from a 'ept-data' folder for the same blobId, e.g. 'ept-data/0-0-0-0.bin'. The '.bin' files are in a custom point cloud format following the schema in the 'ept.json' file. Additionally, a 'filterOptions.json' file contains a description of which options were used when processing the point cloud.\n\nExperimental outputs, normally not enabled:\nThe 'tiles-directory' output contains files for classification of the point cloud data. Retrieve the 'tiles.json' file from this output for a overview of the files within this output.\nThe 'model-from-points' output is used for storing a mesh based output file of some parts of the point cloud. This is stored as a 'model.ciff' file, in the Cognite internal file format.\n\nThis endpoint supports tag-based caching.\n\nThis endpoint is only compatible with 3D file IDs from the 3D API, and not compatible with\nfile IDs from the Files API.", "operationId": "get3DDirectoryFile", "parameters": [ { "name": "threedFileId", "in": "path", "description": "The blob ID of the 3D output directory.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "subPath", "in": "path", "description": "The filename for the 3D file to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "*/*": { "schema": { "type": "string", "description": "The raw contents of the file.", "format": "binary" } } }, "headers": { "Content-Type": { "schema": { "type": "string" }, "description": "The media type of the file." } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ] } }, "/3d/models": { "get": { "tags": [ "3D Models" ], "summary": "List 3D models", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieves a list of all models in a project. This operation supports pagination. You can filter out all models without a published revision.", "operationId": "get3DModels", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "includeRevisionInfo", "in": "query", "description": "If true, return latest revision info as part of response", "schema": { "type": "boolean", "default": false } }, { "name": "published", "in": "query", "description": "Filter based on whether or not it has published revisions.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of models.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Model3DWithCursorResponse" }, { "$ref": "#/components/schemas/Model3DWithRevisionInfoAndCursorResponse" } ] } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const models3D = await client.models3D.list({ published: true });" }, { "lang": "Python", "label": "Python SDK", "source": "three_d_model_list = client.three_d.models.list()\n\nfor three_d_model in client.three_d.models:\n three_d_model # do something with the 3d model\n\nfor three_d_model in client.three_d.models(chunk_size=50):\n three_d_model # do something with the 3d model\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listResults = new ArrayList<>(); \n client.threeD().models() \n .list() \n .forEachRemaining(model -> listResults.addAll(model)); \n\n" } ] }, "post": { "tags": [ "3D Models" ], "summary": "Create 3D models", "operationId": "create3DModels", "requestBody": { "description": "The models to create.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateModel3DClassicBody" }, { "$ref": "#/components/schemas/CreateModel3DDmsOnlyBody" } ] } } }, "required": true }, "responses": { "201": { "description": "A list of the created models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:CREATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const modelsToCreate = [\n { name: 'Model 0' },\n { name: 'Model 2' },\n];\nconst models3D = await client.models3D.create(modelsToCreate);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.models.create(name=\"My Model\", data_set_id=1, metadata={\"key1\": \"value1\", \"key2\": \"value2\"})\n\nfrom cognite.client.data_classes import ThreeDModelWrite\nmy_model = ThreeDModelWrite(name=\"My Model\", data_set_id=1, metadata={\"key1\": \"value1\", \"key2\": \"value2\"})\nmy_other_model = ThreeDModelWrite(name=\"My Other Model\", data_set_id=1, metadata={\"key1\": \"value1\", \"key2\": \"value2\"})\nres = client.three_d.models.create([my_model, my_other_model])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertThreeDModelsList = List.of( \n ThreeDModel.newBuilder() \n .setName(\"generated-\") \n .setDataSetId(dataSetId) \n .setCreatedTime(1552566113).build()); \nList listUpsert = \n client.threeD() \n .models() \n .upsert(upsertThreeDModelsList); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:CREATE`\n" } }, "/3d/models/update": { "post": { "tags": [ "3D Models" ], "summary": "Update 3D models", "operationId": "update3DModels", "requestBody": { "description": "List of changes.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateModel3DClassicBody" }, { "$ref": "#/components/schemas/UpdateModel3DDmsOnlyBody" } ] } } }, "required": true }, "responses": { "200": { "description": "Corresponding models after applying the updates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:UPDATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const modelsToUpdate = [\n { id: 3744350296805509, update: { name: { set: 'Model 0 updated' }}},\n { id: 8163365893677939, update: { name: { set: 'Model 2 updated' }}},\n];\nconst models3D = await client.models3D.update(modelsToUpdate);" }, { "lang": "Python", "label": "Python SDK", "source": "three_d_model = client.three_d.models.retrieve(id=1)\nthree_d_model.name = \"New Name\"\nres = client.three_d.models.update(three_d_model)\n\nfrom cognite.client.data_classes import ThreeDModelUpdate\nmy_update = ThreeDModelUpdate(id=1).name.set(\"New Name\")\nres = client.three_d.models.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "ThreeDModel update = upsertThreeDModelsList.get(0).toBuilder() \n .setName(\"Update Test\").build(); \nList listUpsert = \n client.threeD() \n .models() \n .upsert(List.of(update)); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:UPDATE`\n" } }, "/3d/models/delete": { "post": { "tags": [ "3D Models" ], "summary": "Delete 3D models", "operationId": "delete3DModels", "requestBody": { "description": "List of models to delete.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DataIdentifiers" }, { "$ref": "#/components/schemas/OneDataDmsIdentifier" } ] } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:DELETE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.models3D.delete([{ id: 3744350296805509 }, { id: 8163365893677939 }]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.models.delete(id=1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List deleteItemsResultsByExternalIds = \n client.threeD() \n .models() \n .delete(List.of(Item.newBuilder().setExternalId(\"10\").build())); \n\nList deleteItemsResultsByInternalIds = \n client.threeD() \n .models() \n .delete(List.of(Item.newBuilder().setId(10).build())); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:DELETE`\n" } }, "/3d/models/{modelId}": { "get": { "tags": [ "3D Models" ], "summary": "Retrieve a 3D model", "operationId": "get3DModel", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "responses": { "200": { "description": "A model object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model3D" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.models3D.retrieve(3744350296805509);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.models.retrieve(id=1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List retrievedByInternalIds = \n client.threeD() \n .models() \n .retrieve(List.of(Item.newBuilder().setId(10).build())); \n\nList retrievedByExternalIds = \n client.threeD() \n .models() \n .retrieve(List.of(Item.newBuilder().setExternalId(\"10\").build())); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n" } }, "/3d/models/{modelId}/revisions": { "get": { "tags": [ "3D Model Revisions" ], "summary": "List 3D revisions", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieves a list of all revisions of a model. This operation supports pagination. You can also filter revisions if they are marked as published or not by using the query param published.", "operationId": "get3DRevisions", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "published", "in": "query", "description": "Filter based on published status.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of revisions of the model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision3DWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const revisions3D = await client.revisions3D.list(324566546546346);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.list(model_id=1, published=True, limit=100)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listResults = new ArrayList<>(); \nclient.threeD() \n .models() \n .revisions()\n .list(1L) \n .forEachRemaining(model -> listResults.addAll(model)); \n\n" } ] }, "post": { "tags": [ "3D Model Revisions" ], "summary": "Create 3D revisions", "description": "\n\n> **Required capabilities:** `threedAcl:CREATE`\n\nCreates revision(s) and starts processing job(s).\n\nCheck beta API documentation for information about additional options.\n\nHybrid projects: Use the CreateRevision3DClassicAndHybridBody to create revisions.\n\nDataModelOnly: Please use the 3d/jobs endpoint (Beta for now) to create the revision(s) and start jobs. CreateRevision3DDmsOnlyBody will eventually be deprecated.\n", "operationId": "create3DRevisions", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "requestBody": { "description": "The revisions to create.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateRevision3DClassicAndHybridBody" }, { "$ref": "#/components/schemas/CreateRevision3DDmsOnlyBody" } ] } } } }, "responses": { "201": { "description": "A list of created revisions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:CREATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const revisions = await client.revisions3D.create(4234325345643654, [{ fileId: 8252999965991682 }, { fileId: 6305529564379596 }]);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import ThreeDModelRevisionWrite\nmy_revision = ThreeDModelRevisionWrite(file_id=1)\nres = client.three_d.revisions.create(model_id=1, revision=my_revision)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Path fileAOriginal = Paths.get(\"./src/test/resources/csv-data.txt\"); \nList fileContainerInput = new ArrayList<>(); \nFileMetadata fileMetadata = FileMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_file_.test\") \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .build(); \n\n FileContainer fileContainer = FileContainer.newBuilder() \n .setFileMetadata(fileMetadata) \n .setFileBinary(FileBinary.newBuilder() \n .setBinaryUri(fileAOriginal.toUri().toString())) \n .build(); \n fileContainerInput.add(fileContainer); \n\n List uploadFileResult = \n client.files().upload(fileContainerInput); \n\nThreeDModelRevision.Camera camera = ThreeDModelRevision.Camera.newBuilder() \n .addPosition(2.707411050796509).addPosition(-4.514726638793945).addPosition(1.5695604085922241) \n .addTarget(0.0).addTarget(-0.002374999923631549).addTarget(1.5695604085922241) \n.build(); \nThreeDModelRevision revision = ThreeDModelRevision.newBuilder() \n .setFileId(uploadFileResult.get(0).getId()).setCamera(camera).addRotation(new Random().nextInt(100) / 100.0) \n.build(); \nList listUpsert = \n client.threeD() \n .models() \n .revisions() \n .upsert(10L, List.of(revision)); \n\n" } ] } }, "/3d/models/{modelId}/revisions/update": { "post": { "tags": [ "3D Model Revisions" ], "summary": "Update 3D revisions", "operationId": "update3DRevisions", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "requestBody": { "description": "List of changes.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateRevision3DClassicBody" }, { "$ref": "#/components/schemas/UpdateRevision3DDmsOnlyBody" } ] } } } }, "responses": { "200": { "description": "Corresponding revisions after applying the updates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:UPDATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const revisionsToUpdate = [{\n id: 6305529564379596,\n update: {\n rotation: {\n set: [1, 2, 3]\n },\n translation: {\n set: [4, 5, 6]\n },\n scale: {\n set: [0.5, 0.3, 0.2]\n }\n }\n}];\nconst updated = await client.revisions3D.update(8252999965991682, revisionsToUpdate);" }, { "lang": "Python", "label": "Python SDK", "source": "revision = client.three_d.revisions.retrieve(model_id=1, id=1)\nrevision.status = \"New Status\"\nres = client.three_d.revisions.update(model_id=1, item=revision)\n\nfrom cognite.client.data_classes import ThreeDModelRevisionUpdate\nmy_update = ThreeDModelRevisionUpdate(id=1).published.set(False).metadata.add({\"key\": \"value\"})\nres = client.three_d.revisions.update(model_id=1, item=my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "ThreeDModelRevision th = ThreeDModelRevision.newBuilder().setId(10).setRotation(1,10).build(); \nList tdUpdateResults = \nclient.threeD() \n .models() \n .revisions() \n .upsert(10L, List.of(th)); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:UPDATE`\n" } }, "/3d/models/{modelId}/revisions/delete": { "post": { "tags": [ "3D Model Revisions" ], "summary": "Delete 3D revisions", "operationId": "delete3DRevisions", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "requestBody": { "description": "List of revisions ids to delete.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DataIdentifiers" }, { "$ref": "#/components/schemas/OneDataDmsIdentifier" } ] } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:DELETE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.revisions3D.delete(8252999965991682, [{ id: 4190022127342195 }]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.delete(model_id=1, id=1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList deleteItemsResults = client.threeD().models().revisions().delete(20L, byInternalIds); \n\nList byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList deleteItemsResults = client.threeD().models().revisions().delete(20L, byExternalIds); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:DELETE`\n" } }, "/3d/models/{modelId}/revisions/{revisionId}": { "get": { "tags": [ "3D Model Revisions" ], "summary": "Retrieve a 3D revision", "operationId": "get3DRevision", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "responses": { "200": { "description": "A revision object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision3D" } } } } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const revisions3D = await client.revisions3D.retrieve(8252999965991682, 4190022127342195)" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.retrieve(model_id=1, id=1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList resultsByInternalIds = client.threeD().models().revisions().retrieve(10L, byInternalIds); \n\nList byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList resultsByExternalIds = client.threeD().models().revisions().retrieve(10L, byExternalIds); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n" } }, "/3d/models/{modelId}/revisions/{revisionId}/logs": { "get": { "tags": [ "3D Model Revisions" ], "summary": "List 3D revision logs", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nList log entries for the revision", "operationId": "get3DLogs", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" }, { "name": "severity", "in": "query", "schema": { "type": "integer", "format": "int64", "description": "Minimum severity to retrieve (3 = INFO, 5 = WARN, 7 = ERROR).", "default": 5 } } ], "responses": { "200": { "description": "A list of log entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionLog3DResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ] } }, "/3d/models/{modelId}/revisions/{revisionId}/thumbnail": { "post": { "tags": [ "3D Model Revisions" ], "summary": "Update 3D revision thumbnail", "operationId": "updateThumbnail", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "requestBody": { "description": "The request body containing the file ID of the thumbnail image (from Files API).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRevision3DThumbnail" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:UPDATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.revisions3D.updateThumbnail(8252999965991682, 4190022127342195, 3243334242324);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.update_thumbnail(model_id=1, revision_id=1, file_id=1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "FileMetadata fileMetadata = FileMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"CAMARO_THUMBNAIL_TEST_SDK_JAVA.png\") \n .setSource(\"sdk-data-generator\") \n .setUploaded(true) \n .setMimeType(\"image/png\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .putMetadata(\"sdk-data-generator\", \"sdk-data-generator\") \n .build(); \n byte[] fileByteA = bytes of file; \n List list = List.of(FileContainer.newBuilder().setFileMetadata(fileMetadata).setFileBinary(FileBinary.newBuilder() \n .setBinary(ByteString.copyFrom(fileByteA))).build()); \nList uploadFileResult = client.files().upload(list); \n\nBoolean updated = client \n .threeD() \n .models() \n .revisions() \n .updateThumbnail(model.getId(), revision.getId(), uploadFileResult.get(0).getId()); \n\n" } ], "description": "\n\n> **Required capabilities:** `threedAcl:UPDATE`\n" } }, "/3d/models/{modelId}/revisions/{revisionId}/outputs": { "get": { "tags": [ "3D Model Revisions" ], "summary": "List available outputs", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieve a list of available outputs for a processed 3D model. An output can be a format that can be consumed by a viewer (e.g. Reveal) or import in external tools. Each of the outputs will have an associated version which is used to identify the version of output format (not the revision of the processed output). Note that the structure of the outputs will vary and is not covered here.", "operationId": "list3dModelOutputs", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" }, { "name": "format", "in": "query", "description": "Format identifier, e.g. 'ept-pointcloud' (point cloud). Well known formats are:\n'ept-pointcloud' (point cloud data) or 'reveal-directory' (output supported by Reveal).\n'all-outputs' can be used to retrieve all outputs for a 3D revision. Note that some of\nthe outputs are internal, where the format and availability might change without warning.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list of outputs and available versions per output for the given revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model3DOutputResponseList" } } } } }, "x-capability": [ "threedAcl:READ" ] } }, "/3d/models/{modelId}/revisions/{revisionId}/nodes": { "get": { "tags": [ "3D Model Revisions" ], "summary": "List 3D nodes", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieves a list of nodes from the hierarchy in the 3D model. You can also request a specific subtree with the 'nodeId' query parameter and limit the depth of the resulting subtree with the 'depth' query parameter. By default, nodes are returned in order of ascending treeIndex. We suggest trying to set the query parameter `sortByNodeId` to `true` to check whether it makes your use case faster. The `partition` parameter can only be used if `sortByNodeId` is set to `true`. This operation supports pagination. If the model revision is still being processed, you will get a HTTP status 400 when accessing nodes too early. Wait until the retrieve revision response returns \"status\":\"Done\" before calling nodes endpoints.", "operationId": "get3DNodes", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" }, { "$ref": "#/components/parameters/partition" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "depth", "in": "query", "description": "Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nodeId", "in": "query", "description": "ID of a node that are the root of the subtree you request (default is the root node).", "schema": { "type": "integer", "format": "int64" } }, { "name": "sortByNodeId", "in": "query", "description": "Enable sorting by nodeId. When this parameter is `true`, nodes will be listed in order of ascending nodeId. Enabling this option will likely result in faster response for many requests.", "schema": { "type": "boolean", "default": false } }, { "name": "properties", "in": "query", "description": "Example: `{\"category1\":{\"property1\":\"value1\"}}`\n\nFilter for node properties. Only nodes that match all the given properties exactly will be listed.\nThe filter must be a JSON object with the same format as the `properties` field.\n", "schema": { "type": "string", "format": "jsonObject(jsonObject(string))" } } ], "responses": { "200": { "description": "A list of nodes of a revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node3DWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const nodes3d = await client.revisions3D.list3DNodes(8252999965991682, 4190022127342195);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.list_nodes(model_id=1, revision_id=1, limit=10)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listResults = new ArrayList<>(); \nclient.threeD() \n .models() \n .revisions() \n .nodes() \n .list(model.getId(), revision.getId()) \n .forEachRemaining(val -> listResults.addAll(val)); \n\n" } ] } }, "/3d/models/{modelId}/revisions/{revisionId}/nodes/list": { "post": { "tags": [ "3D Model Revisions" ], "summary": "Filter 3D nodes", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nList nodes in a project, filtered by node names or node property values specified by supplied filters. This operation supports pagination and partitions. If the model revision is still being processed, you will get a HTTP status 400 when accessing nodes too early. Wait until the retrieve revision response returns \"status\":\"Done\" before calling nodes endpoints.", "operationId": "filter3DNodes", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Node3DPropertyFilterBody" }, { "$ref": "#/components/schemas/Node3DNameFilterBody" } ] } } }, "required": true }, "responses": { "200": { "description": "A list of nodes satisfying the supplied node property filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node3DWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const query = {\n filter: {\n properties: {\n Items: {\n Type: [\"Cylinder\"]\n }\n }\n },\n partition: \"1/10\"\n};\nconst nodes3d = await client.revisions3D.filter3DNodes(8252999965991682, 4190022127342195, query);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.filter_nodes(model_id=1, revision_id=1, properties={ \"PDMS\": { \"Area\": [\"AB76\", \"AB77\", \"AB78\"], \"Type\": [\"PIPE\", \"BEND\", \"PIPESUP\"] } }, limit=10)\n" }, { "lang": "Java", "label": "Java SDK", "source": "//without parameters \nIterator> itFilter = client.threeD() \n .models() \n .revisions() \n .nodes() \n .filter(model.getId(), revision.getId()); \n List listResults = itFilter.next(); \n\n//with parameters \nRequest request = Request.create() \n .withFilterParameter(\"properties\", createFilterPropertiesWithCategories()); \n\nList listResults = new ArrayList<>(); \nclient.threeD() \n .models() \n .revisions() \n .nodes() \n .filter(model.getId(), revision.getId(), request) \n .forEachRemaining(val -> listResults.addAll(val)); \n\nprivate ThreeDNode.PropertiesFilter createFilterPropertiesWithCategories() { \n ThreeDNode.PropertiesFilter.Categories.CategoriesValues.Builder catValBuilder = \n ThreeDNode.PropertiesFilter.Categories.CategoriesValues.newBuilder(); \n catValBuilder.addValuesString(\"Box\"); \n ThreeDNode.PropertiesFilter.Categories.Builder catBuilder = \n ThreeDNode.PropertiesFilter.Categories.newBuilder(); \n catBuilder.setName(\"Item\"); \n catBuilder.putValues(\"Type\", catValBuilder.build()); \n ThreeDNode.PropertiesFilter.Builder propsBuilder = \n ThreeDNode.PropertiesFilter.newBuilder(); \n propsBuilder.addCategories(catBuilder.build()); \n return propsBuilder.build(); \n } \n\n" } ] } }, "/3d/models/{modelId}/revisions/{revisionId}/nodes/byids": { "post": { "tags": [ "3D Model Revisions" ], "summary": "Get 3D nodes by ID", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieves specific nodes given by a list of IDs.", "operationId": "get3DNodesById", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "requestBody": { "description": "The request body containing the IDs of the nodes to retrieve. Will return error 400 if the revision is still being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node3DIds" } } }, "required": true }, "responses": { "200": { "description": "A list of nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const nodes3d = await client.revisions3D.retrieve3DNodes(8252999965991682, 4190022127342195, [{id: 123}, {id: 456}]);" }, { "lang": "Java", "label": "Java SDK", "source": "List byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList nodesByIds = client.threeD() \n .models() \n .revisions() \n .nodes() \n .retrieve(model.getId(), revision.getId(), byInternalIds); \n\nList byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \n List nodesByIds = client.threeD() \n .models() \n .revisions() \n .nodes() \n .retrieve(model.getId(), revision.getId(), byExternalIds); \n\n" } ] } }, "/3d/models/{modelId}/revisions/{revisionId}/nodes/{nodeId}/ancestors": { "get": { "tags": [ "3D Model Revisions" ], "summary": "List 3D ancestor nodes", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieves a list of ancestor nodes of a given node, including itself, in the hierarchy of the 3D model. This operation supports pagination. Will return error 400 if the revision is still being processed.", "operationId": "get3DNodeAncestors", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "nodeId", "in": "path", "description": "ID of the node to get the ancestors of.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "A list of ancestor nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node3DWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const nodes3d = await client.revisions3D.list3DNodeAncestors(8252999965991682, 4190022127342195, 572413075141081);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.revisions.list_ancestor_nodes(model_id=1, revision_id=1, node_id=5, limit=10)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listResultsAncestorNodes = new ArrayList<>(); \nclient.threeD() \n .models() \n .revisions() \n .nodes() \n .list(model.getId(), revision.getId(), nodeDrawn.getId()) \n .forEachRemaining(val -> listResultsAncestorNodes.addAll(val)); \n\n" } ] } }, "/3d/models/{modelId}/revisions/{revisionId}/mappings": { "get": { "tags": [ "3D Asset Mapping" ], "summary": "List 3D asset mappings", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nLists 3D assets mappings that match the ID for the specified filter query parameter type. Only one type of filter can be specified for each request, either `assetId`, `nodeId` or `intersectsBoundingBox`.\n\nIn Hybrid CDF projects: The nodeId and assetId mappings are returned by default.\nTo instead see any assetInstanceId mappings (for CoreDM based contextualization),\nset the `getDmsInstances` query parameter to `true`.\n\nIn DataModelingOnly CDF projects: This endpoint is not available. Use DMS queries to list CogniteCADNodes.\n\nNote: When filtering for a specific nodeId, only nodeIds that actually exists will be returned.\nWhen filtering for a specific assetId, all mappings will be returned, even if the assetId does not exist.", "operationId": "get3DMappings", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "nodeId", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "assetId", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "intersectsBoundingBox", "in": "query", "description": "Example: `{\"min\":[0.0, 0.0, 0.0], \"max\":[1.0, 1.0, 1.0]}`\n\nIf given, only return asset mappings for assets whose bounding box\nintersects the given bounding box.\n\nMust be a JSON object with `min`, `max` arrays of coordinates.\n", "schema": { "type": "string" } }, { "name": "getDmsInstances", "in": "query", "description": "If true, the response will include any `assetInstanceId` instances for the mappings.\n", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A list of mappings between assets and 3D nodes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMapping3DWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const mappings3D = await client.assetMappings3D.list(3244265346345, 32423454353545);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.three_d.asset_mappings.list(model_id=1, revision_id=1)\n\nfrom cognite.client.data_classes import BoundingBox3D\nbbox = BoundingBox3D(min=[0.0, 0.0, 0.0], max=[1.0, 1.0, 1.0])\nres = client.three_d.asset_mappings.list(\n model_id=1, revision_id=1, intersects_bounding_box=bbox)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Iterator> itFilter = client.threeD() \n .models() \n .revisions() \n .assetMappings() \n .list(model.getId(), revision.getId()); \nList listResultsList = itFilter.next(); \n\n" } ] }, "post": { "tags": [ "3D Asset Mapping" ], "summary": "Create 3D asset mappings", "description": "\n\n> **Required capabilities:** `threedAcl:UPDATE`\n\nCreate asset mappings\n\nAsset mappings allows connections to be made between assets and 3D nodes. This can be used to contextualize 3D models.\n\nIn Hybrid CDF projects: Asset IDs obtained from a mapping may be invalid, and not point to real asset IDs.\nThe assetId existence is not checked by any means by the 3D API.\nThe mappings will be stored until an `assetId` and `nodeId` pair is removed through the mappings delete endpoint.\n\nIn DataModelingOnly CDF projects: When creating asset mappings, the data model based assetInstanceId (with space and externalId),\nand the 3d model revision nodeId, must be accessible, existing and valid.", "operationId": "create3DMappings", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "requestBody": { "description": "The asset mappings to create.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateAssetMapping3DClassicBody" }, { "$ref": "#/components/schemas/CreateAssetMapping3DDmsBody" } ] } } }, "required": true }, "responses": { "201": { "description": "A list of created asset mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMapping3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:UPDATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assetMappingsToCreate = [\n {\n nodeId: 8252999965991682,\n assetId: 4354399876978078\n },\n {\n nodeId: 9034285498543958,\n assetId: 1042345809544395\n }\n];\nconst mappings3D = await client.assetMappings3D.create(\n 25432542356436,\n 33485743958747,\n assetMappingsToCreate\n);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import ThreeDAssetMappingWrite\nmy_mapping = ThreeDAssetMappingWrite(node_id=1, asset_id=1)\nres = client.three_d.asset_mappings.create(model_id=1, revision_id=1, asset_mapping=my_mapping)\n" }, { "lang": "Java", "label": "Java SDK", "source": " List items = List.of(ThreeDAssetMapping.newBuilder() \n .setAssetId(1L) \n .setNodeId(1L) \n .build()); \n\nList listCreated = client.threeD() \n .models() \n .revisions() \n .assetMappings() \n .create(model.getId(), revision.getId(), items); \n\n" } ] } }, "/3d/models/{modelId}/revisions/{revisionId}/mappings/delete": { "post": { "tags": [ "3D Asset Mapping" ], "summary": "Delete 3D asset mappings", "description": "\n\n> **Required capabilities:** `threedAcl:DELETE`\n\nDelete a list of asset mappings.\n\nIn Hybrid CDF projects: The delete request items requires a `nodeId`, and either an `assetId` or an `assetInstanceId`.\n\nIn DataModelingOnly CDF projects: The delete request items requires a `nodeId` and an `assetInstanceId` (with space and externalId).", "operationId": "delete3DMappings", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "requestBody": { "description": "The IDs of the asset mappings to delete.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteAssetMapping3DClassicBody" }, { "$ref": "#/components/schemas/DeleteAssetMapping3DDmsBody" } ] } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:DELETE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const assetMappingsToDelete = [\n {\n nodeId: 8252999965991682,\n assetId: 4354399876978078\n },\n {\n nodeId: 9034285498543958,\n assetId: 1042345809544395\n }\n];\nawait client.assetMappings3D.delete(8252999965991682, 4190022127342195, assetMappingsToDelete);" }, { "lang": "Python", "label": "Python SDK", "source": "mapping_to_delete = client.three_d.asset_mappings.list(model_id=1, revision_id=1)[0]\nres = client.three_d.asset_mappings.delete(model_id=1, revision_id=1, asset_mapping=mapping_to_delete)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listCreated = //list of ThreeDAssetMapping; \nBoolean isDeleted = client.threeD() \n .models() \n .revisions() \n .assetMappings() \n .delete(model.getId(), revision.getId(), listCreated); \n\n" } ] } }, "/3d/models/{modelId}/revisions/{revisionId}/mappings/list": { "post": { "tags": [ "3D Asset Mapping" ], "summary": "Filter 3D asset mappings", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nLists 3D assets mappings that match the specified filter parameter.\nOnly one type of filter can be specified for each request, either `assetIds`, `nodeIds` or `treeIndexes`.\n\nIn Hybrid CDF projects: The nodeId and assetId mappings are returned by default.\nTo instead see only any `assetInstanceId` mappings (for CoreDM based contextualization),\nset the `getDmsInstances` property to `true`, in the request body.\n\nIn DataModelingOnly CDF projects: This endpoint is not available. Use DMS queries to list CogniteCADNodes.", "operationId": "filter3DAssetMappings", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/RevisionId" } ], "requestBody": { "description": "The filter for asset mappings to get.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMapping3DFilterRequest" } } } }, "responses": { "200": { "description": "A list of matching asset mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMapping3DWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const mappings3D = await client.assetMappings3D.filter(3244265346345, 32423454353545, {\n filter: {\n treeIndexes: [1000, 1001, 1002]\n }\n});" }, { "lang": "Java", "label": "Java SDK", "source": " Request request1 = \n Request.create().withFilterParameter(\"assetIds\", List.of(1L, 2L)); \nIterator> itFilter1 = client.threeD() \n .models() \n .revisions() \n .assetMappings() \n .filter(model.getId(), revision.getId(), request1); \n\n" } ] } }, "/3d/mappings/{assetId}/modelnodes": { "get": { "tags": [ "3D Asset Mapping" ], "summary": "List mappings for one assetID across all 3D models", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nRetrieves a list of `node IDs` from the hierarchy of all available 3D models which are mapped to the supplied `asset ID`.\nIf a `nodeId` is mapped to an `assetId` but is invalid or does not exist anymore, it will be omitted from the results.\nAn asset referenced in an asset mapping is not guaranteed to exist.", "parameters": [ { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A list of mappings between assets and 3D valid nodes and revisions in which exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAssetMapping3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ] } }, "/3d/mappings/modelnodes/filter": { "post": { "tags": [ "3D Asset Mapping" ], "summary": "Filter 3D assetInstanceId mappings across all 3D models", "description": "\n\n> **Required capabilities:** `threedAcl:READ`\n\nFilters the mappings for a specific assetInstanceId across all 3D models in the project.", "requestBody": { "description": "The filter for assetInstanceId mappings to get.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetInstanceIdMappingsFilterRequest" } } } }, "responses": { "200": { "description": "A list of mappings between assetInstanceIds and 3D valid nodes and revisions in which exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAssetMapping3DList" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "threedAcl:READ" ] } }, "/3d/nodes/list": { "post": { "tags": [ "3D Asset Mapping" ], "summary": "Filter which nodes are within a boundingbox for a revision.", "description": "This endpoint is only supported in dm-only projects.\nThe nodeIds can be found as part of a CogniteCadNode in the field `cadNodeReference`.\nSimilar functionality is supported in classic through:\n- list 3D asset mappings endpoint + intersectsBoundingBox", "requestBody": { "description": "The Model, Revision, a list of nodes and an area definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterNodesByBoundingBoxRequest" } } } }, "responses": { "200": { "description": "A list containing the nodes that are within the area definition for the given Model Revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterNodesByBoundingBoxResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/jobs": { "post": { "tags": [ "3D Jobs" ], "summary": "Create a job using 3D source data", "description": "\n\n> **Required capabilities:** `datamodels:READ(cdf_cdm, cdf_cdm_3d)` `datamodelinstances:WRITE`\n\nCreates a job to be run using a 3D source. Currently supported in data-modeling projects only.\nThe user defines a dms instance they want the job to run against, and defines it as the source of the job.\nInside the job you define the space a job will exist in, and its external id, this is not populated into dms.\nThe job external id should be created by the client, and be unique.\nIf the job result is stored in dms, it will be stored using the space of the job.\nA session nonce is required by the request.\n\nJob types with supported job sources:\n- Job Type: ImageTextDetection, Job Source type: Cognite360ImageCollection", "requestBody": { "description": "The job with a given source. Currently supports only one job to be created at the time.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateOptimizerJobRequest" }, { "$ref": "#/components/schemas/Create360ContextualizationJobRequest" } ] } } } }, "responses": { "201": { "description": "A list of the created jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "datamodels:READ(cdf_cdm, cdf_cdm_3d)", "datamodelinstances:WRITE" ] } }, "/3d/jobs/list": { "post": { "tags": [ "3D Jobs" ], "summary": "List jobs", "description": "\n\n> **Required capabilities:** `datamodels:READ(cdf_cdm, cdf_cdm_3d)` `datamodelinstances:READ`\n\nList jobs for your project.", "requestBody": { "description": "A cursor for paginating the list of jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsRequest" } } } }, "responses": { "200": { "description": "A flattened list of jobs with their source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "datamodels:READ(cdf_cdm, cdf_cdm_3d)", "datamodelinstances:READ" ] } }, "/3d/jobs/delete": { "post": { "tags": [ "3D Jobs" ], "summary": "Delete jobs", "description": "\n\n> **Required capabilities:** `datamodels:READ(cdf_cdm, cdf_cdm_3d)` `datamodelinstances:WRITE`\n\nDelete jobs in your project. The job instance results won't be deleted by this operation.", "requestBody": { "description": "List of space and externalIds for jobs you want to delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteJobsRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "datamodels:READ(cdf_cdm, cdf_cdm_3d)", "datamodelinstances:WRITE" ] } }, "/3d/job/results/list": { "post": { "tags": [ "3D Jobs" ], "summary": "List Job Results", "description": "List the results of a job", "requestBody": { "description": "The job space and externalId for the job you want results for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobResultsRequest" } } } }, "responses": { "200": { "description": "A list of results for the job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobResultsWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/job/result/rejections": { "post": { "tags": [ "3D Jobs" ], "summary": "Update Job Result Rejections", "description": "Job Instance Results have internal unique keys you can reject\nto allow yourself to filter away job results items you are no longer\ninterested in", "requestBody": { "description": "The Job space and externalId and the ResultInstanceId with the operation you\nwant to perform on the result.\n\nOnly one operation can be done at the time:\n- add\n- remove", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobResultRejectionsRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/job/result/rejections/list": { "post": { "tags": [ "3D Jobs" ], "summary": "List Job Result Rejections", "description": "A list of internal keys that are to be considered rejected", "requestBody": { "description": "The Job space and externalId and the ResultInstanceId which you want the\nrejections from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobResultRejectionsRequest" } } } }, "responses": { "200": { "description": "A List of rejected keys objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobResultRejectionsWithCursorResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/contextualization/cad": { "post": { "tags": [ "3D Contextualization" ], "summary": "Create CAD contextualization", "description": "Create contextualization connections between 3D CAD nodes and CogniteAsset instances.\nThis allows users to navigate between 3D objects in a 3D CAD model and their connected CogniteAsset instances.\n\nThe 3D CAD nodes are defined for a specific 3D model revision.\nThe connections are referencing the space and externalId for CogniteAsset node instances.\n\nNOTE: This endpoint is only available for DataModelOnly projects.", "requestBody": { "description": "The list of asset instanceIds and nodes, and the dmsContextualizationConfig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextualizeCADBody" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/contextualization/cad/delete": { "post": { "tags": [ "3D Contextualization" ], "summary": "Delete CAD contextualization", "description": "Deletes the specified CAD nodes for the referenced 3D model revision.", "requestBody": { "description": "The array of unique CAD node references, and the dmsContextualizationConfig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteContextualizedCADBody" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/contextualization/image360": { "post": { "tags": [ "3D Contextualization" ], "summary": "Create 360 Image contextualization", "description": "Create contextualization connections between a 360 image annotation and a CogniteAsset instance.\nThe relation between CogniteAsset and the 360 image annotations is One CogniteAsset to Many Cognite360ImageAnnotation.\nThis allows users to navigate between 3D objects in a 360 image model and their connected CogniteAsset instances.\n\nThe 360 image annotations are defined for a specific 3D model revision.\nThe connections are referencing the space and externalId for CogniteAsset node instances.\n\nNOTE: This endpoint is only available for DataModelOnly projects.\n\nNOTE: The request body variants without \"RC\" in the name (e.g. `ContextualizeImage360AnnotationBody`) are deprecated and will be removed before this endpoint is released. Use the \"RC\" (Release Candidate) variants instead.", "requestBody": { "description": "The dmsContextualizationConfig and a list of Asset instance and Image360 instance ids with Annotation data.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContextualizeImage360AnnotationBody" }, { "$ref": "#/components/schemas/ContextualizeImage360AnnotationRCBody" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/contextualization/image360/delete": { "post": { "tags": [ "3D Contextualization" ], "summary": "Delete 360 Image contextualization", "description": "Deletes the Image360Annotation for the specified Asset and Image360 pair in the referenced image 360 revision.\n\nNOTE: The request body variants without \"RC\" in the name (e.g. `DeleteContextualizedImage360AnnotationsBody`) are deprecated and will be removed before this endpoint is released. Use the \"RC\" (Release Candidate) variants instead.", "requestBody": { "description": "The dmsContextualizationConfig and a list of Asset instance and Image360 instance ids.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteContextualizedImage360AnnotationsBody" }, { "$ref": "#/components/schemas/DeleteContextualizedImage360AnnotationsRCBody" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/contextualization/pointcloud": { "post": { "tags": [ "3D Contextualization" ], "summary": "Create Point Cloud Volume contextualization", "description": "Create contextualization connections between point cloud volumes and CogniteAsset instances.\nThis allows users to navigate between 3D objects in a Point Cloud 3D model and their connected CogniteAsset instances.\n\nThe point cloud volumes are defined for a specific 3D model revision.\nThe connections are referencing the space and externalId for CogniteAsset node instances.\n\nNOTE: This endpoint is only available for DataModelOnly projects.", "requestBody": { "description": "The assetInstanceId, dmsContextualizationConfig and a list of PointCloud Volume data.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContextualizePointCloudVolumeBody" }, { "$ref": "#/components/schemas/ContextualizePointCloudVolumeRCBody" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/3d/contextualization/pointcloud/delete": { "post": { "tags": [ "3D Contextualization" ], "summary": "Delete Point Cloud Volume contextualization", "description": "Deletes the specified volumeReferences for the referenced point cloud revision.", "requestBody": { "description": "The array of unique volumeReferences, and the dmsContextualizationConfig.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteContextualizedPointCloudVolumesBody" }, { "$ref": "#/components/schemas/DeleteContextualizedPointCloudVolumesRCBody" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/timeseries": { "get": { "tags": [ "Time series" ], "summary": "List time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\nList time series. Use `nextCursor` to paginate through the results.", "operationId": "getTimeSeries", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of results to return. CDF returns a maximum of 1000 results even if you specify a higher limit.", "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "$ref": "#/components/parameters/IncludeMetadata" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/partition" }, { "name": "assetIds", "in": "query", "description": "Gets the time series related to the assets. The format is a list of IDs serialized as a JSON array(int64). Takes [ 1 .. 100 ] unique items.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "name": "rootAssetIds", "in": "query", "description": "Only includes time series that have a related asset in a tree rooted at any of these root `assetIds`.", "example": "[363848954441724, 793045462540095, 1261042166839739]", "schema": { "$ref": "#/components/schemas/JsonArrayInt64" } }, { "in": "query", "name": "externalIdPrefix", "schema": { "$ref": "#/components/schemas/CogniteExternalIdPrefix" } } ], "responses": { "200": { "description": "A list of time series in lexicographic order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataWithCursorGetTimeSeriesMetadataDTO" } } } } }, "x-capability": [ "timeSeriesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const timeseries = await client.timeseries.list({ filter: { assetIds: [1, 2] }});" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.filters import Equals\nis_numeric = Equals(\"is_string\", False)\nres = client.time_series.filter(filter=is_numeric, sort=\"external_id\")\n\nfrom cognite.client.data_classes.filters import Equals\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty\nis_numeric = Equals(TimeSeriesProperty.is_string, False)\nres = client.time_series.filter(filter=is_numeric, sort=SortableTimeSeriesProperty.external_id)\nres = client.time_series.list(limit=5)\n\nfor ts in client.time_series:\n ts # do something with the time series\n\nfor ts_list in client.time_series(chunk_size=2500):\n ts_list # do something with the time series\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.time_series.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty\nin_timezone = filters.Prefix(TimeSeriesProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.time_series.list(\n advanced_filter=in_timezone,\n sort=(SortableTimeSeriesProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.time_series.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" } ] }, "post": { "tags": [ "Time series" ], "summary": "Create time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:WRITE`\n\nCreates one or more time series.", "operationId": "postTimeSeries", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Response with the created time series.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetTimeSeriesMetadataDTO" } } } }, "400": { "$ref": "#/components/responses/MissingField" }, "409": { "description": "Time series with the specified externalIds already exists. Retry request, with the existing externalIds removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsAlreadyExistResponse" } } } }, "422": { "description": "Duplicated externalIds found. Retry request, keeping only one instance of each duplicated externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatedIdsInRequestResponse" } } } } }, "x-capability": [ "timeSeriesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const timeseries = [\n { name: 'Pressure sensor', assetId: 123 },\n { name: 'Temprature sensor', description: 'Pump abc', unit: 'C' },\n];\nconst createdTimeseries = await client.timeseries.create(timeseries);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import TimeSeriesWrite\nts = client.time_series.create(TimeSeriesWrite(name=\"my_ts\", data_set_id=123, external_id=\"foo\"))\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertTimeseriesList = List.of(TimeseriesMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_ts\") \n .setIsString(false) \n .setIsStep(false) \n .setDescription(\"Description\") \n .setUnit(\"TestUnits\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .putMetadata(\"sdk-data-generator\", \"sdk-data-generator\") \n .build()); \n\nclient.timeseries().upsert(upsertTimeseriesList); \n\n" } ] } }, "/timeseries/byids": { "post": { "tags": [ "Time series" ], "summary": "Retrieve time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\nRetrieves one or more time series by ID or external ID. The response returns the time series in the same order as in the request.", "operationId": "getTimeSeriesByIds", "requestBody": { "description": "List of the IDs of the time series to retrieve.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesLookupById" } } }, "required": true }, "responses": { "200": { "description": "Response with a list of time series matching the IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetTimeSeriesMetadataDTO" } } } }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "422": { "description": "Duplicate IDs found. Retry request, keeping only one instance of each duplicated ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatedIdsInRequestResponse" } } } } }, "x-capability": [ "timeSeriesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const timeseries = await client.timeseries.retrieve([\n { id: 123 },\n { externalId: 'abc' }\n]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.time_series.retrieve(id=1)\n\nres = client.time_series.retrieve(external_id=\"1\")\nres = client.time_series.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.time_series.retrieve_multiple(external_ids=[\"abc\", \"def\"])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList retrievedAssets = client.timeseries().retrieve(byExternalIds);// by list of items \nList retrievedAssets = client.timeseries().retrieve(\"10\", \"20\");// by varargs of String \n\nList byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList retrievedAssets = client.timeseries().retrieve(byInternalIds);// by list of items \nList retrievedAssets = client.timeseries().retrieve(10, 20);// by varargs of Long \n\n" } ] } }, "/timeseries/list": { "post": { "tags": [ "Time series" ], "summary": "Filter time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\n
\n\nRetrieves a list of time series that match the given criteria.\n\n\n### Advanced filtering\n\nThe `advancedFilter`\nfield lets you create complex filtering expressions that combine simple operations,\nsuch as `equals`, `prefix`, and `exists`, by using the Boolean operators `and`, `or`, and `not`.\nFiltering applies to basic fields as well as metadata. See the `advancedFilter` syntax in the request example.\n\n\n\n#### Supported leaf filters\n\n| Leaf filter | Supported fields | Description and example |\n|----------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `containsAll` | Array type fields | Only includes results which contain all of the specified values.
`{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values.
`{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value.
`{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has a value).
`{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values.
`{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified text.
`{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range.
`{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}`
Supported operators: `gt`, `lt`, `gte`, `lte` |\n | `search` | `[\"name\"]` and `[\"description\"]` | Introduced to provide functional parity with the /timeseries/search endpoint.
`{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n#### Supported properties\n\n| Property | Type |\n|-----------------------------------|--------------------|\n| `[\"description\"]` | string |\n| `[\"externalId\"]` | string |\n| `[\"metadata\", \"\"]` | string |\n| `[\"name\"]` | string |\n| `[\"unit\"]` | string |\n| `[\"unitExternalId\"]` | string |\n| `[\"unitQuantity\"]` | string |\n| `[\"instanceId\", \"space\"]` | string |\n| `[\"instanceId\", \"externalId\"]` | string |\n| `[\"assetId\"]` | number |\n| `[\"assetRootId\"]` | number |\n| `[\"createdTime\"]` | number |\n| `[\"dataSetId\"]` | number |\n| `[\"id\"]` | number |\n| `[\"lastUpdatedTime\"]` | number |\n| `[\"isStep\"]` | Boolean |\n| `[\"isString\"]` | Boolean |\n| `[\"type\"]` | string |\n| `[\"securityCategories\"]` | array of numbers |\n\n#### Limits\n\n- Filter query max depth: 10.\n- Filter query max number of clauses: 100.\n- `and` and `or` clauses must have at least one element (and at most 99, since each element counts\n towards the total clause limit, and so does the `and`/`or` clause itself).\n- The `property` array of each leaf filter has the following limitations:\n - Number of elements in the array is 1 or 2.\n - Elements must not be null or blank.\n - Each element max length is 256 characters.\n - The `property` array must match one of the existing properties (static top-level property or dynamic metadata property).\n- `containsAll`, `containsAny`, and `in` filter `values` array size must be in the range [1, 100].\n- `containsAll`, `containsAny`, and `in` filter `values` array must contain elements of number or string type (matching the type of the given property).\n- `range` filter must have at lest one of `gt`, `gte`, `lt`, `lte` attributes.\n But `gt` is mutually exclusive to `gte`, while `lt` is mutually exclusive to `lte`.\n- `gt`, `gte`, `lt`, `lte` in the `range` filter must be of number or string type (matching the type of the given property).\n- `search` filter `value` must not be blank, and the length must be in the range [1, 128], and there\n may be at most two `search` filters in the entire filter query.\n- The maximum length of the `value` of a leaf filter that is applied to a string property is 256.\n\n### Sorting\n\nBy default, time series are sorted by their creation time in ascending order.\nSorting by another property or by several other properties can be explicitly requested via the\n`sort` field, which must contain a list\nof one or more sort specifications. Each sort specification indicates the `property` to sort on\nand, optionally, the `order` in which to sort (defaults to `asc`). If multiple sort specifications are\nsupplied, the results are sorted on the first property, and those with the same value for the first\nproperty are sorted on the second property, and so on. \nPartitioning is done independently of sorting; there is no guarantee of sort order between elements from different partitions.\n\n#### Null values\n\nIn case the `nulls` field has the `auto` value, or the field isn't specified, null (missing) values\nare considered bigger than any other values. They are placed last when sorting in the `asc`\norder and first in the `desc` order. Otherwise, missing values are placed according to\nthe `nulls` field (`last` or `first`), and their placement won't depend on the `order`\nfield. Note that the number zero, empty strings, and empty lists are all considered\n_not_ null.\n\n#### Example\n\n```json\n{\n \"sort\": [\n {\n \"property\" : [\"createdTime\"],\n \"order\": \"desc\",\n \"nulls\": \"last\"\n },\n {\n \"property\" : [\"metadata\", \"\"]\n }\n ]\n}\n```\n\n\n#### Properties\n\nYou can sort on the following properties:\n\n| Property |\n|-----------------------------------|\n| `[\"assetId\"]` |\n| `[\"createdTime\"]` |\n| `[\"dataSetId\"]` |\n| `[\"description\"]` |\n| `[\"externalId\"]` |\n| `[\"lastUpdatedTime\"]` |\n| `[\"metadata\", \"\"]` |\n| `[\"name\"]` |\n| `[\"instanceId\", \"space\"]` |\n| `[\"instanceId\", \"externalId\"]` |\n\n#### Limits\n\nThe `sort` array must contain 1 to 2 elements.\n
\n", "operationId": "listTimeSeries", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesListDTO" } } } }, "responses": { "200": { "description": "Response with a list of time series matching the specified criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataWithCursorGetTimeSeriesMetadataDTO" } } } } }, "x-capability": [ "timeSeriesAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.filters import Equals\nis_numeric = Equals(\"is_string\", False)\nres = client.time_series.filter(filter=is_numeric, sort=\"external_id\")\n\nfrom cognite.client.data_classes.filters import Equals\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty\nis_numeric = Equals(TimeSeriesProperty.is_string, False)\nres = client.time_series.filter(filter=is_numeric, sort=SortableTimeSeriesProperty.external_id)\nres = client.time_series.list(limit=5)\n\nfor ts in client.time_series:\n ts # do something with the time series\n\nfor ts_list in client.time_series(chunk_size=2500):\n ts_list # do something with the time series\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.time_series.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty\nin_timezone = filters.Prefix(TimeSeriesProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.time_series.list(\n advanced_filter=in_timezone,\n sort=(SortableTimeSeriesProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.time_series.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listTimeseriesResults = new ArrayList<>(); \nclient.timeseries() \n .list() \n .forEachRemaining(timeseries -> listTimeseriesResults.addAll(timeseries)); \n\nList listTimeseriesResults = new ArrayList<>(); \nclient.timeseries() \n .list(Request.create() \n .withFilterMetadataParameter(\"source\", \"source\")) \n .forEachRemaining(timeseries -> listTimeseriesResults.addAll(timeseries)); \n\n" } ] } }, "/timeseries/aggregate": { "post": { "tags": [ "Time series" ], "summary": "Aggregate time series", "operationId": "aggregateTimeSeries", "x-capability": [ "timeSeriesAcl:READ" ], "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\nThe aggregation API allows you to compute aggregated results from a set of time series, such as\r\ngetting the number of time series in a project or checking what assets the different time series\r\nin your project are associated with (along with the number of time series for each asset).\r\nBy specifying `filter` and/or `advancedFilter`, the aggregation will take place only over those\r\ntime series that match the filters. `filter` and `advancedFilter` behave the same way as in the\r\n`list` endpoint.\r\n\r\n
\r\n\r\nThe default behavior, when the aggregate field is not specified the request body, is to return the\r\nnumber of time series that match the filters (if any), which is the same behavior as when the\r\naggregate field is set to count.\r\n\r\n\r\nThe following requests will both return the total number of\r\ntime series whose `name` begins with `pump`:\r\n\r\n```\r\n{\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nand\r\n\r\n```\r\n{\r\n \"aggregate\": \"count\",\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe response might be:\r\n\r\n```\r\n{\"items\": [{\"count\": 42}]}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to uniqueValues and specifying a property in properties (this field is an array, but currently only supports one property) will\r\nreturn all unique values (up to a maximum of 1000) that are taken on by that property\r\nacross all the time series that match the filters, as well as the number of time series that\r\nhave each of those property values.\r\n\r\n\r\nThis example request finds all the unique asset ids that are\r\nreferenced by the time series in your project whose `name` begins with `pump`:\r\n\r\n```\r\n{\r\n \"aggregate\": \"uniqueValues\",\r\n \"properties\": [{\"property\": [\"assetId\"]}],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe response might be the following, saying that 23 time series are associated with asset 18\r\nand 107 time series are associated with asset 76:\r\n\r\n```\r\n{\r\n \"items\": [\r\n {\"values\": [\"18\"], \"count\": 23},\r\n {\"values\": [\"76\"], \"count\": 107}\r\n ]\r\n}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to cardinalityValues will instead return the approximate number of\r\ndistinct values that are taken on by the given property among the matching time series.\r\n\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n \"aggregate\": \"cardinalityValues\",\r\n \"properties\": [{\"property\": [\"assetId\"]}],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result is likely exact when the set of unique values is small. In this example, there are likely two distinct asset ids among the matching time series:\r\n\r\n```\r\n{\"items\": [{\"count\": 2}]}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to uniqueProperties will return the set of unique properties whose property\r\npath begins with path (which can currently only be [\"metadata\"]) that are contained in the time series that match the filters.\r\n\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n \"aggregate\": \"uniqueProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result contains all the unique metadata keys in the time series whose `name` begins with\r\n`pump`, and the number of time series that contains each metadata key:\r\n\r\n```\r\n{\r\n \"items\": [\r\n {\"values\": [{\"property\": [\"metadata\", \"tag\"]}], \"count\": 43},\r\n {\"values\": [{\"property\": [\"metadata\", \"installationDate\"]}], \"count\": 97}\r\n ]\r\n}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to cardinalityProperties will instead return the approximate number of\r\ndifferent property keys whose path begins with path (which can currently only be [\"metadata\"], meaning that this can only be used to count the approximate number of distinct metadata keys among the matching time series).\r\n\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n \"aggregate\": \"cardinalityProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result is likely exact when the set of unique values is small. In this example, there are likely two distinct metadata keys among the matching time series:\r\n\r\n```\r\n{\"items\": [{\"count\": 2}]}\r\n```\r\n
\r\n\r\nThe `aggregateFilter` field may be specified if `aggregate` is set to `cardinalityProperties` or `uniqueProperties`. The structure of this field is similar to that of `advancedFilter`, except that the set of leaf filters is smaller (`in`, `prefix`, and `range`), and that none of the leaf filters specify a property. Unlike `advancedFilter`, which is applied _before_ the aggregation (in order to restrict the set of time series that the aggregation operation should be applied to), `aggregateFilter` is applied _after_ the initial aggregation has been performed, in order to restrict the set of results.\r\n\r\n
\r\n\r\nClick here for more details about aggregateFilter. \r\n\r\n\r\nWhen `aggregate` is set to `uniqueProperties`, the result set contains a number of _property paths_, each with an associated count that shows how many time series contained that property (among those time series that matched the `filter` and `advancedFilter`, if they were specified) . If `aggregateFilter` is specified, it will restrict the property paths included in the output. Let us add an `aggregateFilter` to the `uniqueProperties` example from above:\r\n\r\n```\r\n{\r\n \"aggregate\": \"uniqueProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}},\r\n \"aggregateFilter\": {\"prefix\": {\"value\": \"t\"}}\r\n}\r\n```\r\n\r\nNow, the result only contains those metadata properties whose key begins with `t` (but it will be the same set of metadata properties that begin with `t` as in the original query without `aggregateFilter`, and the counts will be the same):\r\n\r\n```\r\n{\r\n \"items\": [\r\n {\"values\": [{\"property\": [\"metadata\", \"tag\"]}], \"count\": 43}\r\n ]\r\n}\r\n```\r\n\r\nSimilarly, adding `aggregateFilter` to `cardinalityProperties` will return the approximate number of properties whose property key matches `aggregateFilter` from those time series matching the `filter` and `advancedFilter` (or from all time series if neither `filter` nor `aggregateFilter` are specified):\r\n\r\n```\r\n{\r\n \"aggregate\": \"cardinalityProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}},\r\n \"aggregateFilter\": {\"prefix\": {\"value\": \"t\"}}\r\n}\r\n```\r\n\r\nAs we saw above, only one property matches:\r\n\r\n```\r\n{\"items\": [{\"count\": 1}]}\r\n```\r\n\r\nNote that `aggregateFilter` is also accepted when `aggregate` is set to `cardinalityValues` or `cardinalityProperties`. For those aggregations, the effect of any `aggregateFilter` could also be achieved via a similar `advancedFilter`. However, `aggregateFilter` is not accepted when `aggregate` is omitted or set to `count`.\r\n
\r\n\r\n### Rate and concurrency limits\r\n\r\nRate and concurrency limits apply this endpoint. If a request exceeds one of the limits,\r\nit will be throttled with a `429: Too Many Requests` response. More on limit types\r\nand how to avoid being throttled is described\r\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\r\n\r\n| Limit | Per project | Per user (identity) |\r\n|----------------|-----------------------|-----------------------|\r\n| Rate | 15 requests per second| 10 requests per second|\r\n| Concurrency | 6 concurrent requests | 4 concurrent requests |\r\n", "requestBody": { "description": "Aggregates the time series that match the given criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesAdvancedAggregateDTO" } } } }, "responses": { "200": { "description": "Response with the aggregated time series. The type of the response depends on the value of the `aggregate` parameter in the request.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TimeSeriesCountAggregateResponse" }, { "$ref": "#/components/schemas/TimeSeriesCardinalityValuesAggregateResponse" }, { "$ref": "#/components/schemas/TimeSeriesCardinalityPropertiesAggregateResponse" }, { "$ref": "#/components/schemas/TimeSeriesUniqueValuesAggregateResponse" }, { "$ref": "#/components/schemas/TimeSeriesUniquePropertiesAggregateResponse" } ] } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const aggregates = await client.timeseries.aggregate({ filter: { isString: true } });\nconsole.log('Number of string timeseries: ', aggregates[0].count)" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.time_series.aggregate(filter={\"unit\": \"kpa\"})\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nkey_count = client.time_series.aggregate_cardinality_properties(TimeSeriesProperty.metadata)\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nunit_count = client.time_series.aggregate_cardinality_values(TimeSeriesProperty.unit)\n\nfrom cognite.client.data_classes import filters, aggregations as aggs\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nnot_america = aggs.Not(aggs.Prefix(\"america\"))\nis_critical = filters.Search(TimeSeriesProperty.description, \"critical\")\ntimezone_count = client.time_series.aggregate_cardinality_values(\n TimeSeriesProperty.metadata_key(\"timezone\"),\n advanced_filter=is_critical,\n aggregate_filter=not_america)\ncount = client.time_series.aggregate_count()\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nis_numeric = filters.Equals(TimeSeriesProperty.is_string, False)\ncount = client.time_series.aggregate_count(advanced_filter=is_numeric)\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nresult = client.time_series.aggregate_unique_values(TimeSeriesProperty.metadata)\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nresult = client.time_series.aggregate_unique_values(TimeSeriesProperty.metadata_key(\"timezone\"))\nprint(result.unique)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nfrom cognite.client.utils import timestamp_to_ms\nfrom datetime import datetime\ncreated_after_2020 = filters.Range(TimeSeriesProperty.created_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.time_series.aggregate_unique_values(TimeSeriesProperty.unit, advanced_filter=created_after_2020)\nprint(result.unique)\n\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty\nfrom cognite.client.data_classes import aggregations as aggs, filters\nnot_test = aggs.Not(aggs.Prefix(\"test\"))\ncreated_after_2020 = filters.Range(TimeSeriesProperty.last_updated_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.time_series.aggregate_unique_values(TimeSeriesProperty.unit, advanced_filter=created_after_2020, aggregate_filter=not_test)\nprint(result.unique)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Aggregate aggregateResult = client.timeseries() \n .aggregate(Request.create() \n .withFilterMetadataParameter(\"source\", \"source\"));" } ] } }, "/timeseries/search": { "post": { "tags": [ "Time series" ], "summary": "Search time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\nFulltext search for time series based on result relevance. Primarily meant\nfor human-centric use cases, not for programs, since matching and\norder may change over time. Additional filters can also be\nspecified. This operation does not support pagination.", "operationId": "searchTimeSeries", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesSearchDTO" } } } }, "responses": { "200": { "description": "List of search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetTimeSeriesMetadataDTO" } } } } }, "x-capability": [ "timeSeriesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const timeseries = await client.timeseries.search({\n filter: {\n isString: false,\n },\n search: {\n query: 'Temperature'\n }\n});" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.time_series.search(name=\"some name\")\n\nres = client.time_series.search(filter={\"asset_ids\":[123]})\n" } ] } }, "/timeseries/update": { "post": { "tags": [ "Time series" ], "summary": "Update time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:WRITE`\n\nUpdates one or more time series. Fields outside of the request remain unchanged.\n\nFor primitive fields (those whose type is string, number, or boolean), use `\"set\": value`\nto update the value; use `\"setNull\": true` to set the field to null.\n\nFor JSON array fields (for example `securityCategories`), use `\"set\": [value1, value2]` to\nupdate the value; use `\"add\": [value1, value2]` to add values; use\n`\"remove\": [value1, value2]` to remove values.", "operationId": "alterTimeSeries", "requestBody": { "description": "List of changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Response with the corresponding time series after applying the updates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetTimeSeriesMetadataDTO" } } } }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "409": { "description": "Time series with the specified externalIds already exists. Retry request, with the existing externalIds removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsAlreadyExistResponse" } } } }, "422": { "description": "Duplicate IDs found. Retry request, keeping only one instance of each duplicated ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatedIdsInRequestResponse" } } } } }, "x-capability": [ "timeSeriesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const timeseries = await client.timeseries.update([{\n id: 3785438579439,\n update: {\n name: { set: 'New name' }\n }\n}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.time_series.retrieve(id=1)\nres.description = \"New description\"\nres = client.time_series.update(res)\n\nfrom cognite.client.data_classes import TimeSeriesUpdate\nmy_update = TimeSeriesUpdate(id=1).description.set(\"New description\").metadata.add({\"key\": \"value\"})\nres = client.time_series.update(my_update)\n\nfrom cognite.client.data_classes import TimeSeriesUpdate\nfrom cognite.client.data_classes.data_modeling import NodeId\n\nmy_update = (\n TimeSeriesUpdate(instance_id=NodeId(\"test\", \"hello\"))\n .external_id.set(\"test:hello\")\n .metadata.add({\"test\": \"hello\"})\n)\nclient.time_series.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "client.timeseries().upsert(upsertTimeseriesList); \n\n" } ] } }, "/timeseries/delete": { "post": { "tags": [ "Time series" ], "summary": "Delete time series", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:WRITE`\n\nDeletes the time series with the specified IDs and their data points.", "operationId": "deleteTimeSeries", "requestBody": { "description": "Specify a list of the time series to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesLookupByIdWithoutInstanceId" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponseWithoutInstanceId" } } } }, "422": { "description": "Duplicate IDs found. Retry request, keeping only one instance of each duplicated ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatedIdsInRequestResponse" } } } } }, "x-capability": [ "timeSeriesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.timeseries.delete([\n { id: 123 },\n { externalId: 'abc' }\n]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.time_series.delete(id=[1,2,3], external_id=\"3\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList deletedAssets = client.timeseries().delete(byInternalIds); \n\nList byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList deletedAssets = client.timeseries().delete(byExternalIds); \n\n" } ] } }, "/timeseries/data": { "post": { "tags": [ "Time series" ], "summary": "Insert data points", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:WRITE`\n\nInsert data points into a time series. You can do this for multiple time series.\nIf you insert a data point with a timestamp that already exists, it will be overwritten with the new value.", "operationId": "postMultiTimeSeriesDatapoints", "requestBody": { "description": "The datapoints to insert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatapointsInsertQuery" } }, "application/protobuf": { "schema": { "type": "string", "format": "binary", "description": "Accepts protocol buffer serialized payload, based on the following proto definitions: [Data Point Insertion]() and [Data Points]()", "example": "Definitions: https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_point_insertion_request.proto https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_points.proto" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "422": { "description": "Duplicate IDs found. Retry request, keeping only one instance of each duplicated ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatedIdsInRequestResponse" } } } } }, "x-capability": [ "timeSeriesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.datapoints.insert([{ id: 123, datapoints: [{timestamp: 1557320284000, value: -2}] }]);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes.data_modeling import NodeId\nfrom cognite.client.data_classes import StatusCode\nfrom datetime import datetime, timezone\nto_insert = [\n {\"id\": 1, \"datapoints\": [\n (datetime(2018,1,1, tzinfo=timezone.utc), 1000),\n (datetime(2018,1,2, tzinfo=timezone.utc), 2000, StatusCode.Good)],\n },\n {\"external_id\": \"foo\", \"datapoints\": [\n (datetime(2018,1,3, tzinfo=timezone.utc), 3000),\n (datetime(2018,1,4, tzinfo=timezone.utc), 4000, StatusCode.Uncertain)],\n },\n {\"instance_id\": NodeId(\"my-space\", \"my-ts-xid\"), \"datapoints\": [\n (datetime(2018,1,5, tzinfo=timezone.utc), 5000),\n (datetime(2018,1,6, tzinfo=timezone.utc), None, StatusCode.Bad)],\n }\n]\n\nimport math\nto_insert.append(\n {\"external_id\": \"bar\", \"datapoints\": [\n {\"timestamp\": 170000000, \"value\": 7000},\n {\"timestamp\": 180000000, \"value\": 8000, \"status\": {\"symbol\": \"Uncertain\"}},\n {\"timestamp\": 190000000, \"value\": None, \"status\": {\"code\": StatusCode.Bad}},\n {\"timestamp\": 200000000, \"value\": math.inf, \"status\": {\"code\": StatusCode.Bad, \"symbol\": \"Bad\"}},\n]})\n\ndata_to_clone = client.time_series.data.retrieve(\n external_id=\"bar\", include_status=True, ignore_bad_datapoints=False)\nto_insert.append({\"external_id\": \"bar-clone\", \"datapoints\": data_to_clone})\nclient.time_series.data.insert_multiple(to_insert)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List items = new ArrayList<>(); items.add(TimeseriesPointPost.newBuilder() \n .setExternalId(\"TimeseriesMetadata.id\") \n .setTimestamp(timeStamp.toEpochMilli()) \n .setValueNum(ThreadLocalRandom.current().nextLong(-10, 20)) \n .build()); \nclient.timeseries().dataPoints().upsert(items); \n\n" } ] } }, "/timeseries/data/list": { "post": { "tags": [ "Time series" ], "summary": "Retrieve data points", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\nRetrieves a list of data points from multiple time series in a project.\nThis operation supports aggregation and pagination.\nLearn more about [aggregation]().\n\nNote: when `start` isn't specified in the top level and for an individual item, it will default to epoch 0, which is 1 January, 1970, thus\nexcluding potential existent data points before 1970. `start` needs to be specified as a negative number to get data points before 1970.", "operationId": "getMultiTimeSeriesDatapoints", "requestBody": { "description": "Specify parameters to query for multiple data points. If you omit fields in individual data point query items, the top-level field values are used. For example, you can specify a default limit for all items by setting the top-level limit field. If you request aggregates, only the aggregates are returned. If you don't request any aggregates, all data points are returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatapointsMultiQuery" } } }, "required": true }, "responses": { "200": { "description": "Lists of data points for the specified queries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatapointsOrAggregatesResponse" } }, "application/protobuf": { "schema": { "type": "string", "format": "binary", "description": "Returns protocol buffer serialized payload, based on the following proto definitions: [Data Points List]() and [Data Points]()", "example": "Definitions: https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_point_list_response.proto https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_points.proto" } } } }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "x-capability": [ "timeSeriesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const data = await client.datapoints.retrieve({ items: [{ id: 123 }] });" }, { "lang": "Python", "label": "Python SDK", "source": "dps = client.time_series.data.retrieve(id=42, start=\"2w-ago\")\nfrom cognite.client.data_classes.data_modeling import NodeId\ndps = client.time_series.data.retrieve(instance_id=NodeId(\"ts-space\", \"foo\"))\n\ndps_lst = client.time_series.data.retrieve(\n external_id=[\"foo\", \"bar\"],\n start=1514764800000,\n end=1546300800000,\n aggregates=[\"max\", \"average\"],\n granularity=\"1d\")\n\nraw_data = dps.value\nfirst_dps = dps_lst[0] # optionally: `dps_lst.get(external_id=\"foo\")`\navg_data = first_dps.average\nmax_data = first_dps.max\n\ndps_slice = dps[-10:] # Last ten values\ndp = dps[3] # The third value\nfor dp in dps_slice:\n pass # do something!\n\nfrom cognite.client.data_classes import DatapointsQuery\ndps_lst = client.time_series.data.retrieve(\n id=[\n DatapointsQuery(id=42, end=\"1d-ago\", aggregates=\"average\"),\n DatapointsQuery(id=69, end=\"2d-ago\", aggregates=[\"average\"]),\n DatapointsQuery(id=96, end=\"3d-ago\", aggregates=[\"min\", \"max\", \"count\"]),\n ],\n external_id=DatapointsQuery(external_id=\"foo\", aggregates=\"max\"),\n start=\"5d-ago\",\n granularity=\"1h\")\n\ndps = client.time_series.data.retrieve(\n id=123,\n aggregates=\"sum\",\n granularity=\"1month\",\n timezone=\"Europe/Oslo\")\n\nfrom datetime import datetime, timezone\nutc = timezone.utc\ndps_lst = client.time_series.data.retrieve(\n start=datetime(1907, 10, 14, tzinfo=utc),\n end=datetime(1907, 11, 6, tzinfo=utc),\n id=[42, 43, 44, ..., 499, 500],\n)\nts_350 = dps_lst.get(id=350) # ``Datapoints`` object\n\nperiods = client.events.list(type=\"alarm\", subtype=\"pressure\")\nsensor_xid = \"foo-pressure-bar\"\ndps_lst = client.time_series.data.retrieve(\n id=[42, 43, 44],\n external_id=[\n DatapointsQuery(external_id=sensor_xid, start=ev.start_time, end=ev.end_time)\n for ev in periods\n ])\nts_44 = dps_lst.get(id=44) # Single ``Datapoints`` object\nts_lst = dps_lst.get(external_id=sensor_xid) # List of ``len(periods)`` ``Datapoints`` objects\n\nimport itertools\nmonth_starts = [\n datetime(year, month, 1, tzinfo=utc)\n for year, month in itertools.product(range(2000, 2011), range(1, 13))]\ndps_lst = client.time_series.data.retrieve(\n external_id=[DatapointsQuery(external_id=\"foo\", start=start) for start in month_starts],\n limit=1)\n\nfrom cognite.client.utils import MIN_TIMESTAMP_MS, MAX_TIMESTAMP_MS\ndps_backup = client.time_series.data.retrieve(\n id=123,\n start=MIN_TIMESTAMP_MS,\n end=MAX_TIMESTAMP_MS + 1) # end is exclusive\n\nclient.time_series.data.retrieve(\n id=42, start=\"2w-ago\", target_unit=\"temperature:deg_f\")\n\nclient.time_series.data.retrieve(\n id=42, start=\"2w-ago\", target_unit_system=\"Imperial\")\n\ndps = client.time_series.data.retrieve(\n id=42, include_status=True, ignore_bad_datapoints=False)\ndps.status_code # list of integer codes, e.g.: [0, 1073741824, 2147483648]\ndps.status_symbol # list of symbolic representations, e.g. [Good, Uncertain, Bad]\nfrom datetime import datetime, timezone\ndps = client.time_series.data.retrieve_arrays(\n id=42,\n start=datetime(2020, 1, 1, tzinfo=timezone.utc),\n aggregates=[\"min\", \"max\"],\n granularity=\"7d\")\nweekly_range = dps.max - dps.min\n\nimport numpy as np\ndps = client.time_series.data.retrieve_arrays(\n external_id=\"ts-noisy\",\n start=\"2d-ago\",\n limit=2_000_000)\nsmooth = np.convolve(dps.value, np.ones(5) / 5) # doctest: +SKIP\nsmoother = np.convolve(dps.value, np.ones(20) / 20) # doctest: +SKIP\n\nid_lst = [42, 43, 44]\ndps_lst = client.time_series.data.retrieve_arrays(\n id=id_lst,\n start=\"2h-ago\",\n include_outside_points=True,\n ignore_unknown_ids=True)\nlargest_gaps = [np.max(np.diff(dps.timestamp)) for dps in dps_lst]\n\nimport pandas as pd\ndps = client.time_series.data.retrieve_arrays(external_id=\"bar\", start=\"10w-ago\")\nseries = pd.Series(dps.value, index=dps.timestamp)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List results = new ArrayList<>(); \n\nList byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nclient.timeseries().dataPoints()\n .retrieveComplete(byExternalIds) \n .forEachRemaining(result -> results.addAll(result));//by list of items \nclient.timeseries().dataPoints()\n .retrieveComplete(\"10\", \"20\") \n .forEachRemaining(result -> results.addAll(result));//by varargs of String \n\nList byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nclient.timeseries().dataPoints()\n .retrieveComplete(byInternalIds) \n .forEachRemaining(result -> results.addAll(result));//by list of items \nclient.timeseries().dataPoints() \n .retrieveComplete(10, 20) \n .forEachRemaining(result -> results.addAll(result));//by varargs of Long \n\n//with filter\nclient.timeseries().dataPoints() \n .retrieve(Request.create().withRootParameter(\"includeOutsidePoints\", true)) \n .forEachRemaining(items-> results.addAll(items)); \n\n" } ] } }, "/timeseries/data/latest": { "post": { "tags": [ "Time series" ], "summary": "Retrieve latest data point", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:READ`\n\nRetrieves the latest data point in one or more time series. Note that the latest data point\nin a time series is the one with the highest timestamp, which is not necessarily the one\nthat was ingested most recently.\n", "operationId": "getLatest", "requestBody": { "description": "The list of the queries to perform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatapointsLatestQuery" } } }, "required": true }, "responses": { "200": { "description": "A list of responses. Each response contains a list with the most recent data point or an empty list if no data points are found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatapointsResponse" } } } }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "x-capability": [ "timeSeriesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const datapoints = await client.datapoints.retrieveLatest([\n {\n before: 'now',\n id: 123\n },\n {\n externalId: 'abc',\n before: new Date('21 jan 2018'),\n }\n]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.time_series.data.retrieve_latest(id=1)[0]\n\nres = client.time_series.data.retrieve_latest(id=1, before=\"2d-ago\")[0]\n\nres = client.time_series.data.retrieve_latest(id=1, target_unit=\"temperature:deg_f\")[0]\nres = client.time_series.data.retrieve_latest(id=1, target_unit_system=\"Imperial\")[0]\n\nfrom cognite.client.data_classes import LatestDatapointQuery\nres = client.time_series.data.retrieve_latest(id=LatestDatapointQuery(id=1, before=60_000))[0]\n\nres = client.time_series.data.retrieve_latest(external_id=[\"abc\", \"def\"])\nlatest_abc = res[0][0]\nlatest_def = res[1][0]\n\nfrom datetime import datetime, timezone\nid_queries = [\n 123,\n LatestDatapointQuery(id=456, before=\"1w-ago\"),\n LatestDatapointQuery(id=789, before=datetime(2018,1,1, tzinfo=timezone.utc)),\n LatestDatapointQuery(id=987, target_unit=\"temperature:deg_f\")]\next_id_queries = [\n \"foo\",\n LatestDatapointQuery(external_id=\"abc\", before=\"3h-ago\", target_unit_system=\"Imperial\"),\n LatestDatapointQuery(external_id=\"def\", include_status=True),\n LatestDatapointQuery(external_id=\"ghi\", treat_uncertain_as_bad=False),\n LatestDatapointQuery(external_id=\"jkl\", include_status=True, ignore_bad_datapoints=False)]\nres = client.time_series.data.retrieve_latest(\n id=id_queries, external_id=ext_id_queries)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList result = \n client.timeseries().dataPoints() \n .retrieveLatest(byExternalIds);//by list of items \nList result = \n client.timeseries().dataPoints() \n .retrieveLatest(\"10\", \"20\");//by varargs of String \n\nList byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList result = \n client.timeseries().dataPoints() \n .retrieveLatest(byInternalIds);//by list of items \nList result = \n client.timeseries().dataPoints() \n .retrieveLatest(10, 20);//by varargs of Long \n\n" } ] } }, "/timeseries/data/delete": { "post": { "tags": [ "Time series" ], "summary": "Delete data points", "description": "\n\n> **Required capabilities:** `timeSeriesAcl:WRITE`\n\nDelete data points from time series.", "operationId": "deleteDatapoints", "requestBody": { "description": "The list of delete requests to perform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatapointsDeleteQuery" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "x-capability": [ "timeSeriesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.datapoints.delete([{id: 123, inclusiveBegin: new Date('1 jan 2019')}]);" }, { "lang": "Python", "label": "Python SDK", "source": "ranges = [{\"id\": 1, \"start\": \"2d-ago\", \"end\": \"now\"},\n {\"external_id\": \"abc\", \"start\": \"2d-ago\", \"end\": \"now\"}]\nclient.time_series.data.delete_ranges(ranges)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList deletedItems = \n client.timeseries().dataPoints().delete(byExternalIds); \n\nList byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \n List deletedItems = \n client.timeseries().dataPoints().delete(byInternalIds); \n\n" } ] } }, "/timeseries/subscriptions": { "post": { "tags": [ "Data point subscriptions" ], "summary": "Create subscriptions", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:WRITE`\n\nCreate one or more subscriptions that can be used to listen for changes in data points for a set of time series.", "operationId": "postSubscriptions", "requestBody": { "description": "The subscriptions to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "A list of subscriptions that were created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionDTO" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:WRITE" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import DataPointSubscriptionWrite\nsub = DataPointSubscriptionWrite(\n external_id=\"my_subscription\",\n name=\"My subscription\",\n partition_count=1,\n time_series_ids=[\"myFistTimeSeries\", \"mySecondTimeSeries\"])\ncreated = client.time_series.subscriptions.create(sub)\n\nfrom cognite.client.data_classes import DataPointSubscriptionWrite\nfrom cognite.client.data_classes.data_modeling import NodeId\nsub = DataPointSubscriptionWrite(\n external_id=\"my_subscription\",\n name=\"My subscription with Data Model Ids\",\n partition_count=1,\n instance_ids=[NodeId(\"my_space\", \"myFistTimeSeries\"), NodeId(\"my_space\", \"mySecondTimeSeries\")])\ncreated = client.time_series.subscriptions.create(sub)\n\nfrom cognite.client.data_classes import DataPointSubscriptionWrite\nfrom cognite.client.data_classes import filters as flt\nfrom cognite.client.data_classes.datapoints_subscriptions import DatapointSubscriptionProperty\nis_numeric_stepwise = flt.And(\n flt.Equals(DatapointSubscriptionProperty.is_string, False),\n flt.Equals(DatapointSubscriptionProperty.is_step, True))\nsub = DataPointSubscriptionWrite(\n external_id=\"my_subscription\",\n name=\"My subscription for numeric, stepwise time series\",\n partition_count=1,\n filter=is_numeric_stepwise)\ncreated = client.time_series.subscriptions.create(sub)\n" } ] }, "get": { "tags": [ "Data point subscriptions" ], "summary": "List subscriptions", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:READ`\n\nList all subscriptions for the tenant. Use nextCursor to paginate through the results.", "operationId": "listSubscriptions", "parameters": [ { "name": "limit", "in": "query", "description": "Limit on the number of results to return.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A complete list of subscriptions in the tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionDTOWithCursor" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "subscriptions = client.time_series.subscriptions.list(limit=5)\n" } ] } }, "/timeseries/subscriptions/members": { "get": { "tags": [ "Data point subscriptions" ], "summary": "List subscription members", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:READ`\n\nList all member time series for a subscription.\n\nFor non-filter subscriptions, either `externalId` or `instanceId` will be set. This is to be\nable to see if each time series was added by external id or instance id. If a time series\nhas been added to a subscription both by external id and by instance id, it will be listed\ntwice in the output. If a time series that belonged to the subscription has been deleted,\n`id` will not be set.\n\nUse `nextCursor` to paginate through the results.", "operationId": "listSubscriptionMembers", "parameters": [ { "name": "limit", "in": "query", "description": "Limit on the number of results to return.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "externalId", "description": "External id of the subscription.", "in": "query", "schema": { "$ref": "#/components/schemas/CogniteExternalId" } } ], "responses": { "200": { "description": "A complete list of member time series in the subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionMemberDTOWithCursor" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import DataPointSubscriptionUpdate\nmembers = client.time_series.subscriptions.list_member_time_series(\"my_subscription\")\ntimeseries_external_ids = members.as_external_ids()\n" } ] } }, "/timeseries/subscriptions/byids": { "post": { "tags": [ "Data point subscriptions" ], "summary": "Retrieve subscriptions", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:READ`\n\nRetrieve one or more subscriptions by external ID.", "operationId": "getSubscriptionsByIds", "requestBody": { "description": "Specify a list of the subscriptions to retrieve.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsByIdsRequest" } } }, "required": true }, "responses": { "200": { "description": "The retrieved subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionDTO" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.time_series.subscriptions.retrieve(\"my_subscription\")\n" } ] } }, "/timeseries/subscriptions/update": { "post": { "tags": [ "Data point subscriptions" ], "summary": "Update subscriptions", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:WRITE`\n\nUpdates one or more subscriptions. Fields that are not included in the request, are not changed.\n\nIf both `instanceIds` and `timeSeriesIds` are set, they must either both be add/remove or\nboth be set operations.", "operationId": "updateSubscriptions", "requestBody": { "description": "The subscriptions to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "A list of subscriptions updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionDTO" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:WRITE" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import DataPointSubscriptionUpdate\nupdate = DataPointSubscriptionUpdate(\"my_subscription\").name.set(\"My New Name\")\nupdated = client.time_series.subscriptions.update(update)\n\nfrom cognite.client.data_classes import DataPointSubscriptionUpdate\nupdate = DataPointSubscriptionUpdate(\"my_subscription\").time_series_ids.add([\"MyNewTimeSeriesExternalId\"])\nupdated = client.time_series.subscriptions.update(update)\n" } ] } }, "/timeseries/subscriptions/delete": { "post": { "tags": [ "Data point subscriptions" ], "summary": "Delete subscriptions", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:WRITE`\n\nDelete subscription(s). This operation cannot be undone", "operationId": "deleteSubscriptions", "requestBody": { "description": "Specify a list of the subscriptions to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsDeleteRequest" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "description": "IDs not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:WRITE" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "client.time_series.subscriptions.delete(\"my_subscription\")\n" } ] } }, "/timeseries/subscriptions/data/list": { "post": { "tags": [ "Data point subscriptions" ], "summary": "List subscription data", "description": "\n\n> **Required capabilities:** `timeSeriesSubscriptionsAcl:READ`\n\nFetch the next batch of data from a given subscription and partition(s).\nData can be ingested datapoints and time ranges where data is deleted.\nThis endpoint will also return changes to the subscription itself, that is, if time series\nare added or removed from the subscription.\n\nThe data can be returned multiple times, there is no mechanism to acknowledge or delete data.\nUse cursors to paginate through the results.", "operationId": "listSubscriptionData", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsListDataRequest" } } } }, "responses": { "200": { "description": "A batch of data from the subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsListDataResponse" } } } } }, "x-capability": [ "timeSeriesSubscriptionsAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "for batch in client.time_series.subscriptions.iterate_data(\"my_subscription\"):\n # Changes to the subscription itself:\n print(f\"Added {len(batch.subscription_changes.added)} timeseries\")\n print(f\"Removed {len(batch.subscription_changes.removed)} timeseries\")\n print(f\"Changed timeseries data in {len(batch.updates)} updates\")\n # Changes to datapoints for time series in the subscription:\n for update in batch.updates:\n upserts.time_series # The time series the update belongs to\n upserts.upserts # The upserted datapoints, if any\n upserts.deletes # Ranges of deleted periods, if any\n if not batch.has_next:\n break\n\nfor batch in client.time_series.subscriptions.iterate_data(\"my_subscription\", \"3d-ago\"):\n pass # do something\n" } ] } }, "/timeseries/synthetic/query": { "post": { "tags": [ "Synthetic Time Series" ], "summary": "Synthetic query", "description": "Execute an on-the-fly synthetic query", "operationId": "querySyntheticTimeseries", "requestBody": { "description": "The list of queries to perform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticMultiQuery" } } }, "required": true }, "responses": { "200": { "description": "List of datapoints for the specified queries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticQueryResponses" } } } }, "400": { "description": "Query error" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.timeseries.syntheticQuery([\n {\n expression: \"24 * TS{externalId='production/hour', aggregate='average', granularity='1d'}\",\n start: '48h-ago',\n end: 'now',\n limit: 100\n }\n]);" }, { "lang": "Python", "label": "Python SDK", "source": "expression = '''\n 123\n + ts{id:123}\n + ts{externalId:'abc'}\n + ts{space:'my-space',externalId:'my-ts-xid'}\n'''\ndps = client.time_series.data.synthetic.query(\n expressions=expression,\n start=\"2w-ago\",\n end=\"now\")\n\nfrom cognite.client.data_classes.data_modeling.ids import NodeId\nts = client.time_series.retrieve(id=123)\nvariables = {\n \"A\": ts,\n \"B\": \"my_ts_external_id\",\n \"C\": NodeId(\"my-space\", \"my-ts-xid\"),\n}\ndps = client.time_series.data.synthetic.query(\n expressions=\"A+B+C\", start=\"2w-ago\", end=\"now\", variables=variables)\n\nfrom sympy import symbols, cos, sin\nx, y = symbols(\"x y\")\ndps = client.time_series.data.synthetic.query(\n [sin(x), y*cos(x)],\n start=\"2w-ago\",\n end=\"now\",\n variables={x: \"foo\", y: \"bar\"},\n aggregate=\"interpolation\",\n granularity=\"15m\",\n target_unit=\"temperature:deg_c\")\n" } ] } }, "/raw/dbs": { "get": { "tags": [ "Raw" ], "summary": "List databases", "operationId": "getDBs", "parameters": [ { "name": "limit", "in": "query", "description": "Limit on the number of databases to be returned.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 25 } }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of databases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataWithCursorRawDB" } } } } }, "x-capability": [ "rawAcl:LIST" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const databases = await client.raw.listDatabases();" }, { "lang": "Python", "label": "Python SDK", "source": "db_list = client.raw.databases.list(limit=5)\n\nfor db in client.raw.databases:\n db # do something with the db\n\nfor db_list in client.raw.databases(chunk_size=2500):\n db_list # do something with the dbs\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listDatabaseResults = new ArrayList<>(); \nclient.raw() \n .databases() \n .list() \n .forEachRemaining(listDatabaseResults::addAll); \n\n" } ], "description": "\n\n> **Required capabilities:** `rawAcl:LIST`\n" }, "post": { "tags": [ "Raw" ], "summary": "Create databases", "description": "\n\n> **Required capabilities:** `rawAcl:WRITE`\n\nCreate databases in a project. It is possible to post a maximum of 1000 databases per request.", "operationId": "createDBs", "requestBody": { "description": "List of names of databases to be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDB" } } }, "required": true }, "responses": { "201": { "description": "The created databases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDB" } } } } }, "x-capability": [ "rawAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const databases = await client.raw.createDatabases([{ name: 'My company' }]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.raw.databases.create(\"db1\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List createDatabasesList = \n List.of(StringValue.of(\"dbName\").getValue()); \nclient.raw().databases().create(createDatabasesList);" } ] } }, "/raw/dbs/delete": { "post": { "tags": [ "Raw" ], "summary": "Delete databases", "description": "\n\n> **Required capabilities:** `rawAcl:WRITE`\n\nIt deletes a database, but fails if the database is not empty and recursive is set to false (default).", "operationId": "deleteDBs", "requestBody": { "description": "List of names of the databases to be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRawDB" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" } }, "x-capability": [ "rawAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.raw.deleteDatabases([{ name: 'My company' }]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.raw.databases.delete([\"db1\", \"db2\"])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List createDatabasesList = \n List.of(StringValue.of(\"dbName\").getValue()); \nList deleteItemsResults = \n client.raw().databases().delete(createDatabasesList); \n\n //Allows to recursively \nclient.raw().databases().delete(createDatabasesList, true); \n\n" } ] } }, "/raw/dbs/{dbName}/tables": { "get": { "tags": [ "Raw" ], "summary": "List tables in a database", "operationId": "getTables", "parameters": [ { "name": "dbName", "in": "path", "description": "The name of a database to retrieve tables from.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limit on the number of tables to be returned.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 25 } }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of tables in the database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataWithCursorRawDBTable" } } } } }, "x-capability": [ "rawAcl:LIST" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const tables = await client.raw.listTables('My company');" }, { "lang": "Python", "label": "Python SDK", "source": "table_list = client.raw.tables.list(\"db1\", limit=5)\n\nfor table in client.raw.tables(db_name=\"db1\"):\n table # do something with the table\n\nfor table_list in client.raw.tables(db_name=\"db1\", chunk_size=2500):\n table_list # do something with the tables\n" }, { "lang": "Java", "label": "Java SDK", "source": "List tablesResults = new ArrayList<>(); \nclient.raw().tables() \n .list(\"dbName\") \n .forEachRemaining(tablesResults::addAll); \n\n" } ], "description": "\n\n> **Required capabilities:** `rawAcl:LIST`\n" }, "post": { "tags": [ "Raw" ], "summary": "Create tables in a database", "description": "\n\n> **Required capabilities:** `rawAcl:WRITE`\n\nCreate tables in a database. It is possible to post a maximum of 1000 tables per request.", "operationId": "createTables", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database to create tables in.", "required": true, "schema": { "type": "string" } }, { "name": "ensureParent", "in": "query", "description": "Create database if it doesn't exist already", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "description": "List of tables to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDBTable" } } }, "required": true }, "responses": { "201": { "description": "The created tables.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDBTable" } } } }, "400": { "$ref": "#/components/responses/MissingField" } }, "x-capability": [ "rawAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const tables = await client.raw.createTables('My company', [{ name: 'Customers' }]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.raw.tables.create(\"db1\", \"table1\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List createTablesLists = \n List.of(StringValue.of(\"tableName\").getValue()); \nclient.raw().tables().create(\"dbName\", createTablesLists, false); \n\n" } ] } }, "/raw/dbs/{dbName}/tables/delete": { "post": { "tags": [ "Raw" ], "summary": "Delete tables in a database", "operationId": "deleteTables", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database to delete tables in.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "List of tables to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDBTable" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/MissingField" } }, "x-capability": [ "rawAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.raw.deleteTables('My company', [{ name: 'Customers' }]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.raw.tables.delete(\"db1\", [\"table1\", \"table2\"])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listDeleted = \n client.raw().tables().delete(\"dbName\", List.of(\"TablesName\")); \n\n" } ], "description": "\n\n> **Required capabilities:** `rawAcl:WRITE`\n" } }, "/raw/dbs/{dbName}/tables/{tableName}/cursors": { "get": { "tags": [ "Raw" ], "summary": "Retrieve cursors for parallel reads", "description": "\n\n> **Required capabilities:** `rawAcl:READ`\n\nRetrieve cursors based on the last updated time range. Normally this endpoint is used for reading in parallel.\n\nEach cursor should be supplied as the 'cursor' query parameter on GET requests to [Read Rows](#operation/getRows).\n**Note** that the 'minLastUpdatedTime' and the 'maxLastUpdatedTime' query parameter on [Read Rows](#operation/getRows) are ignored when a cursor is specified.\n", "operationId": "getCursors", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database.", "required": true, "schema": { "type": "string" } }, { "name": "tableName", "in": "path", "description": "Name of the table.", "required": true, "schema": { "type": "string" } }, { "name": "minLastUpdatedTime", "in": "query", "description": "An exclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "name": "maxLastUpdatedTime", "in": "query", "description": "An inclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "name": "numberOfCursors", "in": "query", "description": "The number of cursors to return, by default it's 10.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 10000 } } ], "responses": { "200": { "description": "Response with cursors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDBTableCursors" } } } } }, "x-capability": [ "rawAcl:READ" ] } }, "/raw/dbs/{dbName}/tables/{tableName}/rows": { "get": { "tags": [ "Raw" ], "summary": "Retrieve rows from a table", "operationId": "getRows", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database.", "required": true, "schema": { "type": "string" } }, { "name": "tableName", "in": "path", "description": "Name of the table.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limit the number of results. The API may return fewer than the specified limit.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 10000, "default": 25 } }, { "name": "columns", "in": "query", "description": "Ordered list of column keys, separated by commas. Leave empty for all, use single comma to retrieve only row keys.", "schema": { "type": "string", "example": "column1,column2" } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "minLastUpdatedTime", "in": "query", "description": "An exclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } }, { "name": "maxLastUpdatedTime", "in": "query", "description": "An inclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.", "schema": { "$ref": "#/components/schemas/EpochTimestamp" } } ], "responses": { "200": { "description": "Rows returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataWithCursorRawDBRow" } }, "text/csv": { "schema": { "$ref": "#/components/schemas/RawRowCSV" } } } } }, "x-capability": [ "rawAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.raw.listRows('My company', 'Employees', { columns: ['last_name'] });" }, { "lang": "Python", "label": "Python SDK", "source": "row_list = client.raw.rows.list(\"db1\", \"tbl1\", limit=5)\n\nrow_list = client.raw.rows.list(\"db1\", \"tbl1\", limit=None)\n\nfor row in client.raw.rows(\"db1\", \"t1\", columns=[\"col1\",\"col2\"]):\n val1 = row[\"col1\"] # You may access the data directly\n val2 = row.get(\"col2\") # ...or use '.get' when keys can be missing\n\nfor row_list in client.raw.rows(\"db1\", \"t1\", chunk_size=2500):\n row_list # Do something with the rows\n\nrows_iterator = client.raw.rows(\n db_name=\"db1\", table_name=\"t1\", partitions=5, chunk_size=5000, limit=1_000_000\n)\nfor row_list in rows_iterator:\n row_list # Do something with the rows\ndf = client.raw.rows.retrieve_dataframe(\"db1\", \"t1\", limit=5)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listRowsResults = new ArrayList<>(); \nclient.raw().rows().list(\"dbName\", \"TablesName\") \n .forEachRemaining(listRowsResults::addAll); \n\n" } ], "description": "\n\n> **Required capabilities:** `rawAcl:READ`\n" }, "post": { "tags": [ "Raw" ], "summary": "Insert rows into a table", "description": "\n\n> **Required capabilities:** `rawAcl:WRITE`\n\nInsert rows into a table. It is possible to post a maximum of 10000 rows per request.\nIt will replace the columns of an existing row if the rowKey already exists.\n\nThe rowKey is limited to 1024 characters which also includes Unicode characters.\nThe maximum size of columns are 5 MiB, however the maximum size of one column name and value is 2621440 characters each.\nIf you want to store huge amount of data per row or column we recommend using the Files API to upload blobs, then reference it from the Raw row.\n\nThe columns object is a key value object, where the key corresponds to the column name while the value is the column value.\nIt supports all the valid types of values in JSON, so number, string, array, and even nested JSON structure (see payload example to the right).\n\nIf an error occurs during the write, partial data may be written as there is no rollback. However, it's safe to retry the request, since this endpoint supports both update and insert (upsert).\n\nA row's last updated timestamp will only be updated if the new column contents are considered different to the old one. An identical JSON string should always be counted as the same contents.\n", "operationId": "postRows", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 32 } }, { "name": "tableName", "in": "path", "description": "Name of the table.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "ensureParent", "in": "query", "description": "Create database/table if it doesn't exist already", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "description": "List of rows to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDBRow" }, "example": { "items": [ { "key": "some rowKey", "columns": { "some int-col": 10, "some string-col": "string example", "some json-col": { "test": { "foo": "nested" } }, "some array-col": [ 0, 1, 3, 4 ] } } ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "object" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/MissingField" } }, "x-capability": [ "rawAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.raw.insertRows('My company', 'Customers', [{ key: 'customer1', columns: { 'First name': 'Steve', 'Last name': 'Jobs' } }]);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import RowWrite\nrows = [RowWrite(key=\"r1\", columns={\"col1\": \"val1\", \"col2\": \"val1\"}),\n RowWrite(key=\"r2\", columns={\"col1\": \"val2\", \"col2\": \"val2\"})]\nclient.raw.rows.insert(\"db1\", \"table1\", rows)\n\nrows = {\n \"key-1\": {\"col1\": 1, \"col2\": 2},\n \"key-2\": {\"col1\": 3, \"col2\": 4, \"col3\": \"high five\"},\n}\nclient.raw.rows.insert(\"db1\", \"table1\", rows)\nimport pandas as pd\ndf = pd.DataFrame(\n {\"col-a\": [1, 3, None], \"col-b\": [2, -1, 9]},\n index=[\"r1\", \"r2\", \"r3\"])\nres = client.raw.rows.insert_dataframe(\n \"db1\", \"table1\", df, dropna=True)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List createRowsList = List.of(RawRow.newBuilder() \n .setDbName(\"dbName\") \n .setTableName(\"tableName\") \n .setKey(\"key\") \n .setColumns(Struct.newBuilder() \n .putFields(\"string\", Values.of(\"VAL\")) \n .putFields(\"numeric\", Values.of(\"VAL\")) \n .putFields(\"bool\", Values.of(ThreadLocalRandom.current().nextBoolean())) \n .putFields(\"null_value\", Values.ofNull()) \n .putFields(\"array\", Values.of(ListValue.newBuilder() \n .addValues(Values.of(ThreadLocalRandom.current().nextDouble(10000d))) \n .build())) \n .putFields(\"struct\", Values.of(Structs.of(\"nestedString\", Values.of(\"myTrickyStringValue\") \n ))) \n ).build()); \n\nList createRowsResults = client.raw().rows().upsert(createRowsList, false); \n\n" } ] } }, "/raw/dbs/{dbName}/tables/{tableName}/rows/{rowKey}": { "get": { "tags": [ "Raw" ], "summary": "Retrieve row by key", "operationId": "getRow", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database to retrieve the row from.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 32 } }, { "name": "tableName", "in": "path", "description": "Name of the table to retrieve the row from.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "rowKey", "in": "path", "description": "Row key of the row to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Single row from the raw database table with the specified rowKey.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawDBRow" } } } } }, "x-capability": [ "rawAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.raw.retrieveRow('My company', 'Customers', 'customer1');" }, { "lang": "Python", "label": "Python SDK", "source": "row = client.raw.rows.retrieve(\"db1\", \"t1\", \"k1\")\n\nval1 = row[\"col1\"]\nval2 = row.get(\"col2\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List rowsToRetrieve = createRowsList.stream() \n .filter(row -> ThreadLocalRandom.current().nextBoolean()) \n .map(row -> row.getKey()) \n .collect(Collectors.toList()); \n\nList rowsRetrieved = \n client.raw().rows().retrieve(\"dbName\", \"tableName\", rowsToRetrieve); \n\n" } ], "description": "\n\n> **Required capabilities:** `rawAcl:READ`\n" } }, "/raw/dbs/{dbName}/tables/{tableName}/rows/delete": { "post": { "tags": [ "Raw" ], "summary": "Delete rows in a table", "operationId": "deleteRows", "parameters": [ { "name": "dbName", "in": "path", "description": "Name of the database containing the rows.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 32 } }, { "name": "tableName", "in": "path", "description": "Name of the table containing the rows.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "description": "Keys to the rows to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRawDBRowKey" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" } }, "x-capability": [ "rawAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.raw.deleteRows('My company', 'Customers', [{key: 'customer1'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "keys_to_delete = [\"k1\", \"k2\", \"k3\"]\nclient.raw.rows.delete(\"db1\", \"table1\", keys_to_delete)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List rowsToDelete = //list of RawRow; \nList deleteRowResults = client.raw().rows().delete(rowsToDelete); \n\n" } ], "description": "\n\n> **Required capabilities:** `rawAcl:WRITE`\n" } }, "/groups": { "get": { "tags": [ "Groups" ], "summary": "List groups", "description": "\n\n> **Required capabilities:** `groupsAcl:LIST`\n\nRetrieves a list of groups the asking principal a member of. Principals with groups:list capability can optionally ask for all groups in a project.", "operationId": "getGroups", "parameters": [ { "name": "all", "in": "query", "description": "Whether to get all groups, only available with the groups:list acl.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A list of groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGroup" } } } } }, "x-capability": [ "groupsAcl:LIST" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const groups = await client.groups.list({ all: true });" }, { "lang": "Python", "label": "Python SDK", "source": "my_groups = client.iam.groups.list()\n\nall_groups = client.iam.groups.list(all=True)\n" } ] }, "post": { "tags": [ "Groups" ], "summary": "Create groups", "description": "\n\n> **Required capabilities:** `groupsAcl:CREATE`\n\nCreates one or more named groups, each with a set of capabilities. All users with any group membership in a CDF project automatically get the `userProfilesAcl:READ` capability and can search for other users. If not assigned automatically, user profiles must be enabled for the project. To enable user profiles, contact [support](https://support.cognite.com/).", "operationId": "createGroups", "requestBody": { "description": "List of groups to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGroupSpec" } } }, "required": true }, "responses": { "201": { "description": "A list of the created groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGroup" } } } }, "400": { "$ref": "#/components/responses/MissingField" } }, "x-capability": [ "groupsAcl:CREATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const createdGroups = await client.groups.create([{\n name: 'Developers',\n capabilities: [{\n assetsAcl: {\n actions: ['READ'],\n scope: { all: {}}\n }\n }],\n}]);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import GroupWrite\nfrom cognite.client.data_classes.capabilities import AssetsAcl, EventsAcl\nmy_capabilities = [\n AssetsAcl([AssetsAcl.Action.Read], AssetsAcl.Scope.All()),\n EventsAcl([EventsAcl.Action.Write], EventsAcl.Scope.DataSet([123, 456]))]\nmy_group = GroupWrite(name=\"My Group\", capabilities=my_capabilities)\nres = client.iam.groups.create(my_group)\n\ngrp = GroupWrite(\n name=\"Externally managed group\",\n capabilities=my_capabilities,\n source_id=\"b7c9a5a4...\")\nres = client.iam.groups.create(grp)\n\nfrom cognite.client.data_classes import ALL_USER_ACCOUNTS\nall_group = GroupWrite(\n name=\"Everyone is welcome!\",\n capabilities=my_capabilities,\n members=ALL_USER_ACCOUNTS,\n)\nuser_list_group = GroupWrite(\n name=\"Specfic users only\",\n capabilities=my_capabilities,\n members=[\"XRsSD1k3mTIKG\", \"M0SxY6bM9Jl\"])\nres = client.iam.groups.create([user_list_group, all_group])\n\nfrom cognite.client.data_classes.capabilities import Capability\nunparsed_capabilities = [\n {'assetsAcl': {'actions': ['READ', 'WRITE'], 'scope': {'all': {}}}},\n {'eventsAcl': {'actions': ['WRITE'], 'scope': {'datasetScope': {'ids': [123]}}}},\n]\nacls = [Capability.load(cap) for cap in unparsed_capabilities]\ngroup = GroupWrite(name=\"Another group\", capabilities=acls)\n" } ] } }, "/groups/delete": { "post": { "tags": [ "Groups" ], "summary": "Delete groups", "description": "\n\n> **Required capabilities:** `groupsAcl:DELETE`\n\nDeletes the groups with the given IDs.", "operationId": "deleteGroups", "requestBody": { "description": "List of group IDs to delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataLong" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" } }, "x-capability": [ "groupsAcl:DELETE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.groups.delete([921923342342323, 871621872721323]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.iam.groups.delete(1)\n" } ] } }, "/projects": {}, "/projects/{project}": { "parameters": [ { "$ref": "#/components/parameters/project" } ] }, "/update": {}, "/securitycategories": { "get": { "tags": [ "Security categories" ], "summary": "List security categories", "description": "\n\n> **Required capabilities:** `securityCategoriesAcl:LIST`\n\nRetrieves a list of all security categories for a project.", "operationId": "getSecurityCategories", "parameters": [ { "name": "sort", "in": "query", "description": "Sort descending or ascending.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } }, { "name": "cursor", "in": "query", "description": "Cursor to use for paging through results.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Return up to this many results. Maximum is 1000. Default is 25.", "schema": { "maximum": 1000, "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "description": "A list of security categories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityCategoryWithCursorResponse" } } } } }, "x-capability": [ "securityCategoriesAcl:LIST" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const securityCategories = await client.securityCategories.list({ sort: 'ASC' });" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.iam.security_categories.list()\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listSecurityCategoriesResults = new ArrayList<>(); \nclient.securityCategories(). \n list(Request.create()) \n .forEachRemaining(labels -> listSecurityCategoriesResults.addAll(labels)); \n\n " } ] }, "post": { "tags": [ "Security categories" ], "summary": "Create security categories", "description": "\n\n> **Required capabilities:** `securityCategoriesAcl:CREATE`\n\nCreates security categories with the given names. Duplicate names in the request are ignored.\nIf a security category with one of the provided names exists already, then the request will fail and no security categories are created.\n", "operationId": "createSecurityCategories", "requestBody": { "description": "List of categories to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSecurityCategorySpecDTO" } } }, "required": true }, "responses": { "201": { "description": "A list of security categories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityCategoryResponse" } } } } }, "x-capability": [ "securityCategoriesAcl:CREATE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const securityCategories = [\n { name: 'Admins' },\n { name: 'Developers' },\n];\nconst createdSecurityCategories = await client.securityCategories.create(securityCategories);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import SecurityCategoryWrite\nmy_category = SecurityCategoryWrite(name=\"My Category\")\nres = client.iam.security_categories.create(my_category)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List createSecurityCategoriesList = \n List.of(SecurityCategory.newBuilder().setName(\"Name\").build()); \nclient.securityCategories().create(createSecurityCategoriesList); \n\n " } ] } }, "/securitycategories/delete": { "post": { "tags": [ "Security categories" ], "summary": "Delete security categories", "description": "\n\n> **Required capabilities:** `securityCategoriesAcl:DELETE`\n\nDeletes the security categories that match the provided IDs.\nIf any of the provided IDs does not belong to an existing security category, then the request will fail and no security categories are deleted.\n", "operationId": "deleteSecurityCategories", "requestBody": { "description": "List of security category IDs to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataLong" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "securityCategoriesAcl:DELETE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.securityCategories.delete([123, 456]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.iam.security_categories.delete(1)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List deleteItemsResults = \n client.securityCategories() \n .delete(listSecurityCategoriesResults); \n\n " } ] } }, "/datasets": { "post": { "tags": [ "Data sets" ], "summary": "Create data sets", "description": "\n\n> **Required capabilities:** `datasetsAcl:WRITE`\n\nYou can create a maximum of 10 data sets per request.", "operationId": "createDataSets", "requestBody": { "description": "List of the data sets to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSetSpecList" } } }, "required": true }, "x-capability": [ "datasetsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/DataSetListResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const datasets = [\n { externalId: 'sensitiveData' },\n { writeProtected: true }\n];\nconst createdDatasets = await client.datasets.create(datasets);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import DataSetWrite\ndata_sets = [DataSetWrite(name=\"1st level\"), DataSetWrite(name=\"2nd level\")]\nres = client.data_sets.create(data_sets)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertDataSetList = List.of(DataSet.newBuilder() \n .setExternalId(\"10\") \n .setName(\"generated-\") \n .setDescription(\"Generated description\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .putMetadata(\"source\", \"sdk-data-generator\") \n .build()); \n\nList upsertDataSetsResults = \n client.datasets().upsert(upsertDataSetList); \n\n" } ] } }, "/datasets/list": { "post": { "tags": [ "Data sets" ], "summary": "Filter data sets", "description": "\n\n> **Required capabilities:** `datasetsAcl:READ`\n\nUse advanced filtering options to find data sets.", "operationId": "listDataSets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSetFilterRequest" } } } }, "x-capability": [ "datasetsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/DataSetFilterResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const dataSets = await client.datasets.list({ filter: { createdTime: { min: new Date('1 jan 2018'), max: new Date('1 jan 2019') }}});" }, { "lang": "Python", "label": "Python SDK", "source": "data_sets_list = client.data_sets.list(limit=5, write_protected=False)\n\nfor data_set in client.data_sets:\n data_set # do something with the data_set\n\nfor data_set_list in client.data_sets(chunk_size=2500):\n data_set_list # do something with the list\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listDataSetsResults = new ArrayList<>(); \nclient.datasets() \n .list(Request.create()) \n .forEachRemaining(batch -> listDataSetsResults.addAll(batch)); \n\n" } ] } }, "/datasets/aggregate": { "post": { "tags": [ "Data sets" ], "summary": "Aggregate data sets", "description": "\n\n> **Required capabilities:** `datasetsAcl:READ`\n\nAggregate data sets in the same project. Criteria can be applied to select a subset of data sets.", "operationId": "aggregateDataSets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSetAggregateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DataSetAggregateResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "datasetsAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const aggregates = await client.datasets.aggregate({ filter: { writeProtected: true } });\nconsole.log('Number of write protected datasets: ', aggregates[0].count)" }, { "lang": "Python", "label": "Python SDK", "source": "aggregate_protected = client.data_sets.aggregate(filter={\"write_protected\": True})\n" }, { "lang": "Java", "label": "Java SDK", "source": "Aggregate aggregate = client \n .datasets() \n .aggregate(Request.create() \n .withFilterParameter(\"source\",\"sdk-data-generator\")); \n\n" } ] } }, "/datasets/byids": { "post": { "tags": [ "Data sets" ], "summary": "Retrieve data sets", "description": "\n\n> **Required capabilities:** `datasetsAcl:READ`\n\nRetrieve data sets by IDs or external IDs.", "operationId": "getDataSets", "requestBody": { "description": "List of the IDs of the data sets to retrieve. You can retrieve a maximum of 1000 data sets per request. All IDs must be unique.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSetIdEitherList" } } } }, "x-capability": [ "datasetsAcl:READ" ], "responses": { "200": { "$ref": "#/components/responses/DataSetListResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const dataSets = await client.datasets.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.data_sets.retrieve(id=1)\n\nres = client.data_sets.retrieve(external_id=\"1\")\nres = client.data_sets.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.data_sets.retrieve_multiple(external_ids=[\"abc\", \"def\"], ignore_unknown_ids=True)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List retrieveByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList retrieveDataSetResults = client.datasets() \n .retrieve(retrieveByExternalIds);//by list of items \nList retrieveDataSetResults = client.datasets() \n .retrieve(\"10\", \"20\");//by varargs of String \n\nList retrieveByInternalIds = List.of(Item.newBuilder() \n .setId(10) \n .build()); \nList retrieveDataSetResults = client.datasets() \n .retrieve(retrieveByInternalIds);//by list of items \nList retrieveDataSetResults = client.datasets() \n .retrieve(10, 20);//by varargs of Long \n\n" } ] } }, "/datasets/update": { "post": { "tags": [ "Data sets" ], "summary": "Update data sets.", "operationId": "updateDataSets", "requestBody": { "description": "All provided IDs and external IDs must be unique. Fields that are not included in the request, are not changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSetUpdateList" } } }, "required": true }, "x-capability": [ "datasetsAcl:WRITE" ], "responses": { "200": { "$ref": "#/components/responses/DataSetListResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const dataSets = await client.datasets.update([{id: 123, update: {description: {set: 'New description'}}}]);" }, { "lang": "Python", "label": "Python SDK", "source": "data_set = client.data_sets.retrieve(id=1)\ndata_set.description = \"New description\"\nres = client.data_sets.update(data_set)\n\nfrom cognite.client.data_classes import DataSetUpdate\nmy_update = DataSetUpdate(id=1).description.set(\"New description\").metadata.remove([\"key\"])\nres = client.data_sets.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertDataSetList = //list of DataSet; \nList upsertDataSetsResults = \n client.datasets().upsert(upsertDataSetList); \n\n" } ], "description": "\n\n> **Required capabilities:** `datasetsAcl:WRITE`\n" } }, "/sequences": { "get": { "tags": [ "Sequences" ], "summary": "List sequences", "operationId": "listSequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nList sequences. Use `nextCursor` to paginate through the results.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/partition" }, { "in": "query", "name": "limit", "description": "Limits the number of results to be returned. The server returns a maximum of 1000 results even if you specify a higher limit.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Paged response with a list of sequences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceWithCursorResponse" } } } } }, "x-capability": [ "sequencesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const sequences = await client.sequences.list({ filter: { name: 'sequence_name' } });" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import filters\nasset_filter = filters.Equals(\"asset_id\", 123)\nis_efficiency = filters.Equals([\"metadata\", \"type\"], \"efficiency\")\nres = client.sequences.filter(filter=filters.And(asset_filter, is_efficiency), sort=\"created_time\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nasset_filter = filters.Equals(SequenceProperty.asset_id, 123)\nis_efficiency = filters.Equals(SequenceProperty.metadata_key(\"type\"), \"efficiency\")\nres = client.sequences.filter(\n filter=filters.And(asset_filter, is_efficiency),\n sort=SortableSequenceProperty.created_time)\nres = client.sequences.list(limit=5)\n\nfor seq in client.sequences:\n seq # do something with the sequence\n\nfor seq_list in client.sequences(chunk_size=2500):\n seq_list # do something with the sequences\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.sequences.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nin_timezone = filters.Prefix(SequenceProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.sequences.list(\n advanced_filter=in_timezone,\n sort=(SortableSequenceProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.sequences.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" } ] }, "post": { "tags": [ "Sequences" ], "summary": "Create sequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:WRITE`\n\nCreate one or more sequences.", "operationId": "createSequence", "requestBody": { "description": "Sequence to be stored.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataPostSequence" } } } }, "responses": { "201": { "description": "Response with the created sequence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetSequence" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "sequencesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const sequences = [\n {\n externalId: 'sequence_name',\n columns: [\n {\n externalId: 'one',\n valueType: SequenceValueType.LONG,\n },\n {\n externalId: 'two',\n },\n {\n externalId: 'three',\n valueType: SequenceValueType.STRING,\n }\n ]\n }\n];\nconst [sequence] = await client.sequences.create(sequences);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import SequenceWrite, SequenceColumnWrite\ncolumn_def = [\n SequenceColumnWrite(value_type=\"String\", external_id=\"user\", description=\"some description\"),\n SequenceColumnWrite(value_type=\"Double\", external_id=\"amount\")\n]\nseq = client.sequences.create(SequenceWrite(external_id=\"my_sequence\", columns=column_def))\n\nseq2 = client.sequences.create(SequenceWrite(external_id=\"my_copied_sequence\", columns=column_def))\n" }, { "lang": "Java", "label": "Java SDK", "source": "List columns = List.of(SequenceColumn.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_column_\") \n .setDescription(\"Description\") \n .setValueTypeValue(SequenceColumn.ValueType.STRING_VALUE) \n .build()); \n\n List upsertSequencesList = List.of( SequenceMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_sequence_\") \n .setDescription(\"Description\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .addAllColumns(columns) \n .build()); \n\n client.sequences().upsert(upsertSequencesList); \n\n" } ] } }, "/sequences/list": { "post": { "tags": [ "Sequences" ], "summary": "Filter sequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\n
\n\nRetrieves a list of sequences that match the given criteria.\n\n\n### Advanced filtering\n\nThe `advancedFilter`\nfield lets you create complex filtering expressions that combine simple operations,\nsuch as `equals`, `prefix`, and `exists`, by using the Boolean operators `and`, `or`, and `not`.\nFiltering applies to basic fields as well as metadata. See the `advancedFilter` syntax in the request example.\n\n\n\n#### Supported leaf filters\n\n| Leaf filter | Supported fields | Description and example |\n|----------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `containsAll` | Array type fields | Only includes results which contain all of the specified values.
`{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values.
`{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value.
`{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has a value).
`{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values.
`{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified text.
`{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range.
`{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}`
Supported operators: `gt`, `lt`, `gte`, `lte` |\n | `search` | `[\"name\"]` and `[\"description\"]` | Introduced to provide functional parity with the /sequences/search endpoint.
`{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n#### Supported properties\n\n| Property | Type |\n|-----------------------------------|--------------------|\n| `[\"description\"]` | string |\n| `[\"externalId\"]` | string |\n| `[\"metadata\", \"\"]` | string |\n| `[\"name\"]` | string |\n| `[\"assetId\"]` | number |\n| `[\"assetRootId\"]` | number |\n| `[\"createdTime\"]` | number |\n| `[\"dataSetId\"]` | number |\n| `[\"id\"]` | number |\n| `[\"lastUpdatedTime\"]` | number |\n\n#### Limits\n\n- Filter query max depth: 10.\n- Filter query max number of clauses: 100.\n- `and` and `or` clauses must have at least one element (and at most 99, since each element counts\n towards the total clause limit, and so does the `and`/`or` clause itself).\n- The `property` array of each leaf filter has the following limitations:\n - Number of elements in the array is 1 or 2.\n - Elements must not be null or blank.\n - Each element max length is 256 characters.\n - The `property` array must match one of the existing properties (static top-level property or dynamic metadata property).\n- `containsAll`, `containsAny`, and `in` filter `values` array size must be in the range [1, 100].\n- `containsAll`, `containsAny`, and `in` filter `values` array must contain elements of number or string type (matching the type of the given property).\n- `range` filter must have at lest one of `gt`, `gte`, `lt`, `lte` attributes.\n But `gt` is mutually exclusive to `gte`, while `lt` is mutually exclusive to `lte`.\n- `gt`, `gte`, `lt`, `lte` in the `range` filter must be of number or string type (matching the type of the given property).\n- `search` filter `value` must not be blank, and the length must be in the range [1, 128], and there\n may be at most two `search` filters in the entire filter query.\n- The maximum length of the `value` of a leaf filter that is applied to a string property is 256.\n\n### Sorting\n\nBy default, sequences are sorted by their creation time in ascending order.\nSorting by another property or by several other properties can be explicitly requested via the\n`sort` field, which must contain a list\nof one or more sort specifications. Each sort specification indicates the `property` to sort on\nand, optionally, the `order` in which to sort (defaults to `asc`). If multiple sort specifications are\nsupplied, the results are sorted on the first property, and those with the same value for the first\nproperty are sorted on the second property, and so on. \nPartitioning is done independently of sorting; there is no guarantee of sort order between elements from different partitions.\n\n#### Null values\n\nIn case the `nulls` field has the `auto` value, or the field isn't specified, null (missing) values\nare considered bigger than any other values. They are placed last when sorting in the `asc`\norder and first in the `desc` order. Otherwise, missing values are placed according to\nthe `nulls` field (`last` or `first`), and their placement won't depend on the `order`\nfield. Note that the number zero, empty strings, and empty lists are all considered\n_not_ null.\n\n#### Example\n\n```json\n{\n \"sort\": [\n {\n \"property\" : [\"createdTime\"],\n \"order\": \"desc\",\n \"nulls\": \"last\"\n },\n {\n \"property\" : [\"metadata\", \"\"]\n }\n ]\n}\n```\n\n\n#### Properties\n\nYou can sort on the following properties:\n\n| Property |\n|-----------------------------------|\n| `[\"assetId\"]` |\n| `[\"createdTime\"]` |\n| `[\"dataSetId\"]` |\n| `[\"description\"]` |\n| `[\"externalId\"]` |\n| `[\"lastUpdatedTime\"]` |\n| `[\"metadata\", \"\"]` |\n| `[\"name\"]` |\n\n#### Limits\n\nThe `sort` array must contain 1 to 2 elements.\n
\n", "operationId": "advancedListSequences", "requestBody": { "description": "Retrieves a list of sequences matching the given criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequencesAdvancedListDTO" } } } }, "responses": { "200": { "description": "Response with a list of sequences matching the given criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceWithCursorResponse" } } } } }, "x-capability": [ "sequencesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const sequences = await client.sequences.list({ filter: { name: 'sequence_name' } });" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import filters\nasset_filter = filters.Equals(\"asset_id\", 123)\nis_efficiency = filters.Equals([\"metadata\", \"type\"], \"efficiency\")\nres = client.sequences.filter(filter=filters.And(asset_filter, is_efficiency), sort=\"created_time\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nasset_filter = filters.Equals(SequenceProperty.asset_id, 123)\nis_efficiency = filters.Equals(SequenceProperty.metadata_key(\"type\"), \"efficiency\")\nres = client.sequences.filter(\n filter=filters.And(asset_filter, is_efficiency),\n sort=SortableSequenceProperty.created_time)\nres = client.sequences.list(limit=5)\n\nfor seq in client.sequences:\n seq # do something with the sequence\n\nfor seq_list in client.sequences(chunk_size=2500):\n seq_list # do something with the sequences\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.sequences.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nin_timezone = filters.Prefix(SequenceProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.sequences.list(\n advanced_filter=in_timezone,\n sort=(SortableSequenceProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.sequences.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List listSequencesResults = new ArrayList<>(); \n client.sequences() \n .list() \n .forEachRemaining(sequences -> listSequencesResults.addAll(sequences)); \n\n client.sequences() \n .list(Request.create() \n .withFilterMetadataParameter(\"source\", \"sdk-data-generator\")) \n .forEachRemaining(sequences -> listSequencesResults.addAll(sequences)); \n\n" } ] } }, "/sequences/aggregate": { "post": { "tags": [ "Sequences" ], "summary": "Aggregate sequences", "operationId": "aggregateSequences", "x-capability": [ "sequencesAcl:READ" ], "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nThe aggregation API allows you to compute aggregated results from a set of sequences, such as\r\ngetting the number of sequences in a project or checking what assets the different sequences\r\nin your project are associated with (along with the number of sequences for each asset).\r\nBy specifying `filter` and/or `advancedFilter`, the aggregation will take place only over those\r\nsequences that match the filters. `filter` and `advancedFilter` behave the same way as in the\r\n`list` endpoint.\r\n\r\n
\r\n\r\nThe default behavior, when the aggregate field is not specified the request body, is to return the\r\nnumber of sequences that match the filters (if any), which is the same behavior as when the\r\naggregate field is set to count.\r\n\r\n\r\nThe following requests will both return the total number of\r\nsequences whose `name` begins with `pump`:\r\n\r\n```\r\n{\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nand\r\n\r\n```\r\n{\r\n \"aggregate\": \"count\",\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe response might be:\r\n\r\n```\r\n{\"items\": [{\"count\": 42}]}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to uniqueValues and specifying a property in properties (this field is an array, but currently only supports one property) will\r\nreturn all unique values (up to a maximum of 1000) that are taken on by that property\r\nacross all the sequences that match the filters, as well as the number of sequences that\r\nhave each of those property values.\r\n\r\n\r\nThis example request finds all the unique asset ids that are\r\nreferenced by the sequences in your project whose `name` begins with `pump`:\r\n\r\n```\r\n{\r\n \"aggregate\": \"uniqueValues\",\r\n \"properties\": [{\"property\": [\"assetId\"]}],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe response might be the following, saying that 23 sequences are associated with asset 18\r\nand 107 sequences are associated with asset 76:\r\n\r\n```\r\n{\r\n \"items\": [\r\n {\"values\": [\"18\"], \"count\": 23},\r\n {\"values\": [\"76\"], \"count\": 107}\r\n ]\r\n}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to cardinalityValues will instead return the approximate number of\r\ndistinct values that are taken on by the given property among the matching sequences.\r\n\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n \"aggregate\": \"cardinalityValues\",\r\n \"properties\": [{\"property\": [\"assetId\"]}],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result is likely exact when the set of unique values is small. In this example, there are likely two distinct asset ids among the matching sequences:\r\n\r\n```\r\n{\"items\": [{\"count\": 2}]}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to uniqueProperties will return the set of unique properties whose property\r\npath begins with path (which can currently only be [\"metadata\"]) that are contained in the sequences that match the filters.\r\n\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n \"aggregate\": \"uniqueProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result contains all the unique metadata keys in the sequences whose `name` begins with\r\n`pump`, and the number of sequences that contains each metadata key:\r\n\r\n```\r\n{\r\n \"items\": [\r\n {\"values\": [{\"property\": [\"metadata\", \"tag\"]}], \"count\": 43},\r\n {\"values\": [{\"property\": [\"metadata\", \"installationDate\"]}], \"count\": 97}\r\n ]\r\n}\r\n```\r\n
\r\n\r\n
\r\n\r\nSetting aggregate to cardinalityProperties will instead return the approximate number of\r\ndifferent property keys whose path begins with path (which can currently only be [\"metadata\"], meaning that this can only be used to count the approximate number of distinct metadata keys among the matching sequences).\r\n\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n \"aggregate\": \"cardinalityProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result is likely exact when the set of unique values is small. In this example, there are likely two distinct metadata keys among the matching sequences:\r\n\r\n```\r\n{\"items\": [{\"count\": 2}]}\r\n```\r\n
\r\n\r\nThe `aggregateFilter` field may be specified if `aggregate` is set to `cardinalityProperties` or `uniqueProperties`. The structure of this field is similar to that of `advancedFilter`, except that the set of leaf filters is smaller (`in`, `prefix`, and `range`), and that none of the leaf filters specify a property. Unlike `advancedFilter`, which is applied _before_ the aggregation (in order to restrict the set of sequences that the aggregation operation should be applied to), `aggregateFilter` is applied _after_ the initial aggregation has been performed, in order to restrict the set of results.\r\n\r\n
\r\n\r\nClick here for more details about aggregateFilter. \r\n\r\n\r\nWhen `aggregate` is set to `uniqueProperties`, the result set contains a number of _property paths_, each with an associated count that shows how many sequences contained that property (among those sequences that matched the `filter` and `advancedFilter`, if they were specified) . If `aggregateFilter` is specified, it will restrict the property paths included in the output. Let us add an `aggregateFilter` to the `uniqueProperties` example from above:\r\n\r\n```\r\n{\r\n \"aggregate\": \"uniqueProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}},\r\n \"aggregateFilter\": {\"prefix\": {\"value\": \"t\"}}\r\n}\r\n```\r\n\r\nNow, the result only contains those metadata properties whose key begins with `t` (but it will be the same set of metadata properties that begin with `t` as in the original query without `aggregateFilter`, and the counts will be the same):\r\n\r\n```\r\n{\r\n \"items\": [\r\n {\"values\": [{\"property\": [\"metadata\", \"tag\"]}], \"count\": 43}\r\n ]\r\n}\r\n```\r\n\r\nSimilarly, adding `aggregateFilter` to `cardinalityProperties` will return the approximate number of properties whose property key matches `aggregateFilter` from those sequences matching the `filter` and `advancedFilter` (or from all sequences if neither `filter` nor `aggregateFilter` are specified):\r\n\r\n```\r\n{\r\n \"aggregate\": \"cardinalityProperties\",\r\n \"path\": [\"metadata\"],\r\n \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}},\r\n \"aggregateFilter\": {\"prefix\": {\"value\": \"t\"}}\r\n}\r\n```\r\n\r\nAs we saw above, only one property matches:\r\n\r\n```\r\n{\"items\": [{\"count\": 1}]}\r\n```\r\n\r\nNote that `aggregateFilter` is also accepted when `aggregate` is set to `cardinalityValues` or `cardinalityProperties`. For those aggregations, the effect of any `aggregateFilter` could also be achieved via a similar `advancedFilter`. However, `aggregateFilter` is not accepted when `aggregate` is omitted or set to `count`.\r\n
\r\n\r\n### Rate and concurrency limits\r\n\r\nRate and concurrency limits apply this endpoint. If a request exceeds one of the limits,\r\nit will be throttled with a `429: Too Many Requests` response. More on limit types\r\nand how to avoid being throttled is described\r\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\r\n\r\n| Limit | Per project | Per user (identity) |\r\n|----------------|-----------------------|-----------------------|\r\n| Rate | 15 requests per second| 10 requests per second|\r\n| Concurrency | 6 concurrent requests | 4 concurrent requests |\r\n", "requestBody": { "description": "Aggregates the sequences that match the given criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequencesAdvancedAggregateDTO" } } } }, "responses": { "200": { "description": "Response with the aggregated sequences. The type of the response depends on the value of the `aggregate` parameter in the request.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SequencesCountAggregateResponse" }, { "$ref": "#/components/schemas/SequencesCardinalityValuesAggregateResponse" }, { "$ref": "#/components/schemas/SequencesCardinalityPropertiesAggregateResponse" }, { "$ref": "#/components/schemas/SequencesUniqueValuesAggregateResponse" }, { "$ref": "#/components/schemas/SequencesUniquePropertiesAggregateResponse" } ] } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const aggregates = await client.sequences.aggregate({ filter: { name: \"Well\" } });\nconsole.log('Number of sequences named Well: ', aggregates[0].count)" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.sequences.aggregate(filter={\"external_id_prefix\": \"prefix\"})\nfrom cognite.client.data_classes.sequences import SequenceProperty\ncount = client.sequences.aggregate_cardinality_values(SequenceProperty.metadata)\nfrom cognite.client.data_classes.sequences import SequenceProperty\ncount = client.sequences.aggregate_cardinality_values(SequenceProperty.metadata_key(\"efficiency\"))\n\nfrom cognite.client.data_classes import filters, aggregations as aggs\nfrom cognite.client.data_classes.sequences import SequenceProperty\nnot_america = aggs.Not(aggs.Prefix(\"america\"))\nis_critical = filters.Search(SequenceProperty.description, \"critical\")\ntimezone_count = client.sequences.aggregate_cardinality_values(\n SequenceProperty.metadata_key(\"timezone\"),\n advanced_filter=is_critical,\n aggregate_filter=not_america)\ncount = client.sequences.aggregate_count()\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty\nis_mapping = filters.Prefix(SequenceProperty.external_id, \"mapping:\")\ncount = client.sequences.aggregate_count(advanced_filter=is_mapping)\nfrom cognite.client.data_classes.sequences import SequenceProperty\nresult = client.sequences.aggregate_unique_properties(SequenceProperty.metadata)\nfrom cognite.client.data_classes.sequences import SequenceProperty\nresult = client.sequences.aggregate_unique_values(SequenceProperty.metadata_key(\"timezone\"))\nprint(result.unique)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty\nfrom cognite.client.utils import timestamp_to_ms\nfrom datetime import datetime\ncreated_after_2020 = filters.Range(SequenceProperty.created_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.sequences.aggregate_unique_values(SequenceProperty.metadata, advanced_filter=created_after_2020)\nprint(result.unique)\n\nfrom cognite.client.data_classes.sequences import SequenceProperty\nfrom cognite.client.data_classes import aggregations as aggs, filters\nnot_test = aggs.Not(aggs.Prefix(\"test\"))\ncreated_after_2020 = filters.Range(SequenceProperty.last_updated_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))\nresult = client.sequences.aggregate_unique_values(SequenceProperty.metadata, advanced_filter=created_after_2020, aggregate_filter=not_test)\nprint(result.unique)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Aggregate aggregateResult = \n client.sequences().aggregate(Request.create().withFilterMetadataParameter(\"source\", \"source\")); \n\n" } ] } }, "/sequences/byids": { "post": { "tags": [ "Sequences" ], "summary": "Retrieve sequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nRetrieves one or more sequences by ID or external ID. The response returns the sequences in the same order as in the request.", "operationId": "getSequenceById", "requestBody": { "description": "Ids of the sequences", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResourceIdsWithIgnoreUnknownIds" } } } }, "responses": { "200": { "description": "Response with the requested sequences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetSequence" } } } } }, "x-capability": [ "sequencesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const [sequence1, sequence2] = await client.sequences.retrieve([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.sequences.retrieve(id=1)\n\nres = client.sequences.retrieve()\nres = client.sequences.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.sequences.retrieve_multiple(external_ids=[\"abc\", \"def\"])\n" }, { "lang": "Java", "label": "Java SDK", "source": "List retrievedByExternalIds = client.sequences().retrieve(\"10\");//by varargs of String \nList listItemsExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList retrievedSequencesExternalIds = client.sequences().retrieve(listItemsExternalIds);//by list of items \n\nList retrievedByInternalIds = client.sequences().retrieve(10, 20);//by varargs of Long \nList listItemsInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList retrievedSequencesInternalIds = client.sequences().retrieve(listItemsInternalIds); \n\n" } ] } }, "/sequences/search": { "post": { "tags": [ "Sequences" ], "summary": "Search sequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nRetrieves a list of sequences matching the given criteria. This operation doesn't support pagination.", "operationId": "searchSequences", "requestBody": { "description": "Retrieves a list of sequences matching the given criteria. This operation doesn't support pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequencesSearchDTO" } } } }, "responses": { "200": { "description": "Response with a list of sequences matching the given criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetSequence" } } } } }, "x-capability": [ "sequencesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const sequences = await client.sequences.search({\n filter: {\n assetIds: [1, 2]\n },\n search: {\n query: 'n*m* desc*ion'\n }\n});" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.sequences.search(name=\"some name\")\n" } ] } }, "/sequences/update": { "post": { "tags": [ "Sequences" ], "summary": "Update sequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:WRITE`\n\nUpdates one or more sequences. Fields outside of the request remain unchanged.", "operationId": "updateSequences", "requestBody": { "description": "Patch definition", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSequenceChange" } } } }, "responses": { "200": { "description": "Response with the updated sequences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGetSequence" } } } } }, "x-capability": [ "sequencesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const [updatedSequence] = await client.sequences.update([{id: 123, update: {name: {set: 'New name'}}}]);" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.sequences.retrieve(id=1)\nres.description = \"New description\"\nres = client.sequences.update(res)\n\nfrom cognite.client.data_classes import SequenceUpdate\nmy_update = SequenceUpdate(id=1).description.set(\"New description\").metadata.add({\"key\": \"value\"})\nres = client.sequences.update(my_update)\n\nfrom cognite.client.data_classes import SequenceUpdate, SequenceColumn\nmy_update = SequenceUpdate(id=1).columns.add(SequenceColumn(value_type =\"String\",external_id=\"user\", description =\"some description\"))\nres = client.sequences.update(my_update)\n\nfrom cognite.client.data_classes import SequenceUpdate, SequenceColumn\ncolumn_def = [\n SequenceColumn(value_type =\"String\",external_id=\"user\", description =\"some description\"),\n SequenceColumn(value_type=\"Double\", external_id=\"amount\")]\nmy_update = SequenceUpdate(id=1).columns.add(column_def)\nres = client.sequences.update(my_update)\n\nfrom cognite.client.data_classes import SequenceUpdate\nmy_update = SequenceUpdate(id=1).columns.remove(\"col_external_id1\")\nres = client.sequences.update(my_update)\n\nfrom cognite.client.data_classes import SequenceUpdate\nmy_update = SequenceUpdate(id=1).columns.remove([\"col_external_id1\",\"col_external_id2\"])\nres = client.sequences.update(my_update)\n\nfrom cognite.client.data_classes import SequenceUpdate, SequenceColumnUpdate\ncolumn_updates = [\n SequenceColumnUpdate(external_id=\"col_external_id_1\").external_id.set(\"new_col_external_id\"),\n SequenceColumnUpdate(external_id=\"col_external_id_2\").description.set(\"my new description\"),\n]\nmy_update = SequenceUpdate(id=1).columns.modify(column_updates)\nres = client.sequences.update(my_update)\n" }, { "lang": "Java", "label": "Java SDK", "source": "\n client.sequences().upsert(upsertSequencesList); \n\n" } ] } }, "/sequences/delete": { "post": { "tags": [ "Sequences" ], "summary": "Delete sequences", "description": "\n\n> **Required capabilities:** `sequencesAcl:WRITE`\n\nDeletes the sequences with the specified IDs. If one or more of the sequences do not exist, the `ignoreUnknownIds` parameter controls what will happen: if it is `true`, the sequences that do exist will be deleted, and the request succeeds; if it is `false` or absent, nothing will be deleted, and the request fails.", "operationId": "deleteSequences", "requestBody": { "description": "Ids of the sequences to delete.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResourceIdsWithIgnoreUnknownIds" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" } }, "x-capability": [ "sequencesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.sequences.delete([{id: 123}, {externalId: 'abc'}]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.sequences.delete(id=[1,2,3], external_id=\"3\")\n" }, { "lang": "Java", "label": "Java SDK", "source": "List deleteItemsSequencesByExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList externalIdsResults = client.sequences().delete(deleteItemsSequencesByExternalIds); \n\nList deleteItemsSequencesByInternalIds = List.of(Item.newBuilder().setId(10).build()); \n List InternalIdsResults = client.sequences().delete(deleteItemsSequencesByInternalIds); \n\n" } ] } }, "/sequences/data": { "post": { "tags": [ "Sequences" ], "summary": "Insert rows", "description": "\n\n> **Required capabilities:** `sequencesAcl:WRITE`\n\nInserts rows into a sequence. This overwrites data in rows and columns that exist.", "operationId": "postSequenceData", "requestBody": { "description": "Data posted.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSequencePostData" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" } }, "x-capability": [ "sequencesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const rows = [\n { rowNumber: 0, values: [1, 2.2, 'three'] },\n { rowNumber: 1, values: [4, 5, 'six'] }\n];\nawait client.sequences.insertRows([{ id: 123, rows, columns: ['one', 'two', 'three'] }]);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import Sequence, SequenceColumn\nseq = client.sequences.create(Sequence(columns=[SequenceColumn(value_type=\"String\", external_id=\"col_a\"),\n SequenceColumn(value_type=\"Double\", external_id =\"col_b\")]))\ndata = [(1, ['pi',3.14]), (2, ['e',2.72]) ]\nclient.sequences.data.insert(columns=[\"col_a\",\"col_b\"], rows=data, id=1)\n\ndata = [{\"rowNumber\": 123, \"values\": ['str',3]}, {\"rowNumber\": 456, \"values\": [\"bar\",42]} ]\nclient.sequences.data.insert(data, id=1, columns=[\"col_a\",\"col_b\"]) # implicit columns are retrieved from metadata\n\ndata = {123 : ['str',3], 456 : ['bar',42] }\nclient.sequences.data.insert(columns=['stringColumn','intColumn'], rows=data, id=1)\n\ndata = client.sequences.data.retrieve(id=2,start=0,end=10)\nclient.sequences.data.insert(rows=data, id=1,columns=None)\nimport pandas as pd\ndf = pd.DataFrame({'col_a': [1, 2, 3], 'col_b': [4, 5, 6]}, index=[1, 2, 3])\nclient.sequences.data.insert_dataframe(df, id=123)\nfrom cognite.client.data_classes import Sequence, SequenceColumn\nseq = client.sequences.create(Sequence(columns=[SequenceColumn(value_type=\"String\", external_id=\"col_a\"),\n SequenceColumn(value_type=\"Double\", external_id =\"col_b\")]))\ndata = [(1, ['pi',3.14]), (2, ['e',2.72]) ]\nclient.sequences.data.insert(columns=[\"col_a\",\"col_b\"], rows=data, id=1)\n\ndata = [{\"rowNumber\": 123, \"values\": ['str',3]}, {\"rowNumber\": 456, \"values\": [\"bar\",42]} ]\nclient.sequences.data.insert(data, id=1, columns=[\"col_a\",\"col_b\"]) # implicit columns are retrieved from metadata\n\ndata = {123 : ['str',3], 456 : ['bar',42] }\nclient.sequences.data.insert(columns=['stringColumn','intColumn'], rows=data, id=1)\n\ndata = client.sequences.data.retrieve(id=2,start=0,end=10)\nclient.sequences.data.insert(rows=data, id=1,columns=None)\nimport pandas as pd\ndf = pd.DataFrame({'col_a': [1, 2, 3], 'col_b': [4, 5, 6]}, index=[1, 2, 3])\nclient.sequences.data.insert_dataframe(df, id=123)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List upsertSequencesList = DataGenerator.generateSequenceMetadata(); \nclient.sequences().upsert(upsertSequencesList); \n\n SequenceBody body = SequenceBody.newBuilder() \n .setExternalId(upsertSequencesList.get(1).getExternalId()) \n .addAllColumns(List.of(SequenceColumn.newBuilder().setExternalId(\"10\").build())) \n .addAllRows(List.of(SequenceRow.newBuilder().setRowNumber(1).addAllValues(List.of(Value.newBuilder().setNumberValue(10).build())).build())) \n .build(); \n List upsertSequenceBodyResponse = client.sequences().rows().upsert(List.of(body)); \n\n" } ] } }, "/sequences/data/list": { "post": { "tags": [ "Sequences" ], "summary": "Retrieve rows", "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nProcesses data requests and returns the result. Note that this operation uses a dynamic limit on the number of rows returned based on the number and type of columns; use the provided cursor to paginate and retrieve all data.", "operationId": "getSequenceData", "requestBody": { "description": "Description of data requested.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDataRequest" } } } }, "responses": { "200": { "description": "Response with the sequence data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceGetDataWithCursor" } } } } }, "x-capability": [ "sequencesAcl:READ" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const rows = await client.sequences.retrieveRows({ externalId: 'sequence1' }).autoPagingToArray({ limit: 100 });" }, { "lang": "Python", "label": "Python SDK", "source": "res = client.sequences.data.retrieve(id=1)\ntuples = [(r,v) for r,v in res.items()] # You can use this iterator in for loops and list comprehensions,\nsingle_value = res[23] # ... get the values at a single row number,\ncol = res.get_column(external_id='columnExtId') # ... get the array of values for a specific column,\ndf = res.to_pandas() # ... or convert the result to a dataframe\ndf = client.sequences.data.retrieve_dataframe(id=1, start=0, end=None)\nres = client.sequences.data.retrieve(id=1)\ntuples = [(r,v) for r,v in res.items()] # You can use this iterator in for loops and list comprehensions,\nsingle_value = res[23] # ... get the values at a single row number,\ncol = res.get_column(external_id='columnExtId') # ... get the array of values for a specific column,\ndf = res.to_pandas() # ... or convert the result to a dataframe\ndf = client.sequences.data.retrieve_dataframe(id=1, start=0, end=None)\n" }, { "lang": "Java", "label": "Java SDK", "source": "Iterator> listRetrieved = client.sequences().rows().retrieve(Request.create()); \n\nIterator> list = client.sequences().rows().retrieveComplete(List.of(Item.newBuilder().setId(10).build()));//by list of items \nIterator> list = client.sequences().rows().retrieveComplete(10);//by varargs of Long \n\nIterator> list = client.sequences().rows().retrieveComplete(List.of(Item.newBuilder().setExternalId(\"10\").build()));//by list of items \nIterator> list = client.sequences().rows().retrieveComplete(\"10\");//by varargs of String \n\n" } ] } }, "/sequences/data/latest": { "post": { "tags": [ "Sequences" ], "summary": "Retrieve last row", "description": "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nRetrieves the last row in one or more sequences. Note that the last row in a sequence is the\none with the highest row number, which is not necessarily the one that was ingested most\nrecently.\n", "operationId": "getLatestSequenceRow", "requestBody": { "description": "Description of data requested.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceLatestDataRequest" } } } }, "responses": { "200": { "description": "Response with the sequence data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceGetData" } } } } }, "x-capability": [ "sequencesAcl:READ" ], "x-code-samples": [ { "lang": "Python", "label": "Python SDK", "source": "res = client.sequences.data.retrieve_last_row(id=1, before=1000)\nres = client.sequences.data.retrieve_last_row(id=1, before=1000)\n" } ] } }, "/sequences/data/delete": { "post": { "tags": [ "Sequences" ], "summary": "Delete rows", "description": "\n\n> **Required capabilities:** `sequencesAcl:WRITE`\n\nDeletes the given rows of the sequence. All columns are affected.", "operationId": "deleteSequenceData", "requestBody": { "description": "Indicate the sequences and the rows where data should be deleted.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSequenceDataDeleteRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" } }, "x-capability": [ "sequencesAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "await client.sequences.deleteRows([{ id: 32423849, rows: [1,2,3] }]);" }, { "lang": "Python", "label": "Python SDK", "source": "client.sequences.data.delete(id=1, rows=[1,2,42])\nclient.sequences.data.delete_range(id=1, start=0, end=None)\nclient.sequences.data.delete(id=1, rows=[1,2,42])\nclient.sequences.data.delete_range(id=1, start=0, end=None)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List deleteRowsInput = listSequencesRowsResults; \nList deleteRowsResults = client.sequences().rows().delete(deleteRowsInput);" } ] } }, "/labels": { "post": { "tags": [ "Labels" ], "summary": "Create label definitions.", "description": "\n\n> **Required capabilities:** `labelsAcl:WRITE`\n\nCreates label definitions that can be used across different resource types. The label definitions are uniquely identified by their external id.", "operationId": "createLabelDefinitions", "requestBody": { "description": "List of label definitions to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalLabelDefinitionList" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/LabelDefinitionCreateResponse" }, "400": { "$ref": "#/components/responses/ErrorResponse" } }, "x-capability": [ "labelsAcl:WRITE" ], "x-code-samples": [ { "lang": "JavaScript", "label": "JavaScript SDK", "source": "const labels = [\n { externalId: 'PUMP', name: \"Pump\" },\n { externalId: 'ROTATING_EQUIPMENT', name: 'Rotating equipment', description: 'Asset with rotating parts' }\n];\nconst createdLabels = await client.labels.create(labels);" }, { "lang": "Python", "label": "Python SDK", "source": "from cognite.client.data_classes import LabelDefinitionWrite\nlabels = [LabelDefinitionWrite(external_id=\"ROTATING_EQUIPMENT\", name=\"Rotating equipment\"), LabelDefinitionWrite(external_id=\"PUMP\", name=\"pump\")]\nres = client.labels.create(labels)\n" }, { "lang": "Java", "label": "Java SDK", "source": "List