Skip to content

Instantly share code, notes, and snippets.

@ks93

ks93/7effa191-334c-436d-89e4-897849db34db

Created December 11, 2023 16:53
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save ks93/42a95daefa1f3ae5050dbf5541f5dea6 to your computer and use it in GitHub Desktop.
Save ks93/42a95daefa1f3ae5050dbf5541f5dea6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
7effa191-334c-436d-89e4-897849db34db
This file has been truncated, but you can view the full file.
{
"openapi": "3.0.2",
"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://developer.cognite.com/dev/concepts/request_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}",
"variables": {
"cluster": {
"description": "The CDF cluster to connect to",
"enum": [
"api",
"az-tyo-gp-001",
"az-eastus-1",
"az-power-no-northeurope",
"westeurope-1",
"asia-northeast1-1",
"gc-dsm-gp-001"
],
"default": "api"
},
"project": {
"description": "The CDF project name.",
"default": "publicdata"
}
}
}
],
"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<!--\nGroup changes by release (and date), API area, and these types of changes:\n\n - **Added** for new features.\n - **Changed** for changes in existing functionality.\n - **Deprecated** for soon-to-be removed features.\n - **Removed** for now removed features.\n - **Fixed** for any bug fixes.\n - **Security** in case of vulnerabilities.-\n\nUse[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) for dates: 2019-06-20\n\nAdd entries for new features on top of this page. Newest release goes on top.\nChanges only for API v1 series\n\nTemplate:\n\n## <YYYY-MM-DD>\n\n### <Core resource name>\n\n#### <Group name -- see top of the page>\n\n - <my change>\n - <my change>\n\n#### <Group name -- see top of the page>\n\n - <my change>\n - <my change>\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` <sup>\\*</sup>\n\n<sup>\\*</sup>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\nRate and concurrency limits apply to some of the 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://developer.cognite.com/dev/concepts/request_throttling/).\n\nFollowing limits apply to the [List assets](operation/getAssets), [Filter assets](operation/listAssets), \n[Aggregate assets](operation/aggregateAssets) and [Search assets](operation/searchAssets) endpoints.\nThese limits apply to all endpoints simultaneously, \ni.e. requests made to different endpoints are counted together. Please note the additional conditions\nthat apply to the [Aggregate assets](operation/aggregateAssets) endpoint, as this endpoint provides\nthe most resource-consuming operations.\n\n| Limit | Per project | Per user (identity) |\n|----------------|-----------------------------------------------------------------------|----------------------------------------------------------------------|\n| Rate | 30 rps total <br /> out of which no more than 15 rps to Aggregate | 20 rps <br /> out of which no more than 10 rps to Aggregate |\n| Concurrency | 15 parallel requests <br /> out of which no more than 6 to Aggregate | 10 parallel requests <br /> out of which no more than 4 to Aggregate |"
},
{
"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"
},
{
"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 Modelling 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**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://developer.cognite.com/dev/concepts/request_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<img src=\"https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/api-docs/EventsLimitsNov23.png\" alt=\" \" width=\"80%\"/>\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."
},
{
"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": "3D",
"description": "We organize 3D data into models and revisions. A model is just a placeholder for a set of revisions. Revisions contains the actual 3D data. For example you can have a model named Compressor and you can upload a revision under that model. When you create a revision you need to attach a 3D file. For every new version of the 3D model you upload a new revision under the placeholder model. You can then easily track the history of a model by browsing the different revisions.\n\nWhen you upload a new revision Cognite need to process the 3D data to optimize it for rendering. This can take some time and we therefore give you a status string back in the revision object. You can then follow the process while you wait.\n\nA 3D model is typically built up by a hierarchical structure. This looks very similar to how we organize our internal asset hierarchy. We support endpoints to extract the 3D node hierarchy and endpoints to make mappings from the 3D nodes to nodes in Cognite's asset hierarchy. We assign a random ID, nodeId, to each node in the 3D hierarchy. This is the ID representing the object in the viewer. When a user click on a object in the viewer it returns the ID for the object that was clicked. You can then use that ID to look up which node in the hierarchy the user clicked on.\n\nWe also deliver a [web based 3D viewer](https://www.npmjs.com/package/@cognite/3d-viewer) to embed the 3D model in your own web page."
},
{
"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": "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'}`.\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\nTo learn more about synthetic time series please follow [our guide](https://developer.cognite.com/dev/concepts/resource_types/synthetic_timeseries.html)."
},
{
"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://developer.cognite.com/dev/concepts/request_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 |"
},
{
"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"
},
{
"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://developer.cognite.com/dev/guides/iam/authorization.html#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://developer.cognite.com/dev/concepts/resource_types/sequences.html).\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": "Vision",
"description": "The Vision contextualization endpoints enable extraction of information from imagery data based on their visual content. For example, you can detect external ID or name of assets, detect and read value of gauges or identify common industrial objects in images. \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."
},
{
"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#### assetIds\nThis `assetIds` field contains a combination of asset ids that are directly assigned\nto the file in the Files API, and additional assets whose names are mentioned in the\nfile itself.\n\nIf you want only the asset ids that are explicitly assigned to the file, you can use\nthe `sourceFile.assetIds` property instead.\n\n#### labels\nIf there are labels assigned to the file in the Files API, this field will contain the\nsame set of labels.\n\nFor files without explicitly assigned labels, it is possible to train an AI classifier\nto automatically assign labels. This can be used for instance to classify documents\ninto different categories.\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": "Transformations",
"description": "Transformations enable users to use Spark SQL queries to transform data from the CDF staging area, RAW, into the CDF data model."
},
{
"name": "Transformation Jobs",
"description": "Transformation jobs let you execute transformations asynchronously."
},
{
"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": "Seismic",
"description": "A seismic object is a no-copy view into seismic stores. Once you have defined the object, either via a polygon to \"cut out\" from the origin seismic store or via an explicit trace-by-trace mapping, you cannot modify it. You can assign seismic objects to partitions and restrict user access to each partition. That way, seismic objects are the most granular unit of access control. Each seismic object has one corresponding partition. If a user is restricted to a specific partition, they will only be able to view the seismic objects that have been assigned to that partition."
},
{
"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 that the user profile data is mutable, and any updates in the external identity \nprovider may also cause updates in this API. Therefore, you cannot use profile data, \nfor example a user's email, to uniquely identify a principal. The exception is the \n`userIdentifier` property which is _guaranteed_ to be immutable.\n"
},
{
"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.\nThis API is in beta. The endpoints listed here are available only when the `cdf-version` header with the value `beta` is provided."
},
{
"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).\nThis API is in beta. The endpoints listed here are available only when the `cdf-version` header with the value `beta` is provided."
},
{
"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.\nThis API is in beta. The endpoints listed here are available only when the `cdf-version` header with the value `beta` is provided."
},
{
"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).\nThis API is in beta. The endpoints listed here are available only when the `cdf-version` header with the value `beta` is provided."
},
{
"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."
}
],
"paths": {
"/token/inspect": {
"get": {
"servers": [
{
"url": "https://{cluster}.cognitedata.com/api/v1",
"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": "Inspect 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": "List 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\nf = filters\nin_timezone = f.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.filter(filter=in_timezone,\n sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nf = filters\nin_timezone = f.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.filter(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"
}
]
},
"post": {
"tags": [
"Assets"
],
"summary": "Create assets",
"description": "You can create a maximum of 1000 assets per request.",
"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 Asset\nassets = [Asset(name=\"asset1\"), Asset(name=\"asset2\")]\nres = client.assets.create(assets)\n\nfrom cognite.client.data_classes import Asset, Label\nasset = Asset(name=\"my_pump\", labels=[Label(external_id=\"PUMP\")])\nres = client.assets.create(asset)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Asset> 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<Asset> upsertedAssets = client.assets().upsert(upsertAssetsList); \n\n"
}
]
}
},
"/assets/{id}": {
"get": {
"tags": [
"Assets"
],
"summary": "Retrieve an asset by its ID",
"description": "Retrieve an asset by its ID. If you want to retrieve assets by externalIds, use Retrieve assets instead.",
"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": "Retrieve 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. <br /> `{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values. <br /> `{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value. <br /> `{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has value). <br /> `{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values. <br /> `{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified value. <br /> `{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range. <br /> `{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}` <br /> Supported operators: `gt`, `lt`, `gte`, `lte` |\n| `search` | `[\"name\"]`, `[\"description\"]` | Introduced to provide functional parity with /assets/search endpoint. <br /> `{\"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\nf = filters\nin_timezone = f.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.filter(filter=in_timezone,\n sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nf = filters\nin_timezone = f.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.filter(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"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Asset> 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": "The 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 import filters\nfrom cognite.client.data_classes.assets import AssetProperty\nis_critical = filters.Search(AssetProperty.description, \"critical\")\ncritical_assets = client.assets.aggregate_cardinality_values(AssetProperty.metadata_key(\"timezone\"), advanced_filter=is_critical)\ncount = client.assets.aggregate_count()\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty\nhas_timezone = filters.ContainsAny(AssetProperty.metadata, \"timezone\")\nasset_count = client.assets.aggregate_count(advanced_filter=has_timezone)\naggregate_by_prefix = client.assets.aggregate_metadata_keys(filter={\"external_id_prefix\": \"prefix\"})\naggregate_by_prefix = client.assets.aggregate_metadata_values(\n keys=[\"someKey\"],\n filter={\"external_id_prefix\": \"prefix\"}\n)\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 as aggs, filters\nnot_test = aggs.Not(aggs.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": "Retrieve assets by IDs or external IDs. If you specify to get aggregates, then be aware that the aggregates are eventually consistent.\n",
"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<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<Asset> retrievedAssets = client.assets().retrieve(byExternalIds);// by list of items \nList<Asset> retrievedAssets = client.assets().retrieve(\"10\", \"20\");// by varargs of String \n\nList<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<Asset> retrievedAssets = client.assets().retrieve(byInternalIds);// by list of items \nList<Asset> retrievedAssets = client.assets().retrieve(10, 20);// by varargs of Long \n\n"
}
]
}
},
"/assets/update": {
"post": {
"tags": [
"Assets"
],
"summary": "Update assets",
"description": "Update the attributes of assets.",
"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<Asset> upsertedAssets = client.assets().upsert(upsertAssetsList); \n\n"
}
]
}
},
"/assets/search": {
"post": {
"tags": [
"Assets"
],
"summary": "Search assets",
"description": "Fulltext 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": "Delete assets. By default, `recursive=false` and the request would fail if attempting to delete assets that are referenced as parent by other assets. To delete such assets and all its descendants, set recursive to true. The limit of the request does not include the number of descendants that are deleted.",
"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<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<Item> deletedAssets = client.assets().delete(byInternalIds); \n\nList<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<Item> deletedAssets = client.assets().delete(byExternalIds); \n\n"
}
]
}
},
"/models/spaces": {
"post": {
"tags": [
"Spaces"
],
"summary": "Create or update spaces",
"description": "Add 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": [
"DataModelsAdminAcl: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": "List spaces defined in the current project.",
"operationId": "listSpacesV3",
"parameters": [
{
"$ref": "#/components/parameters/ReducedLimit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"$ref": "#/components/parameters/IncludeGlobal"
}
],
"x-capability": [
"DataModelsAclAdmin: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": "Retrieve 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": [
"DataModelsAdminAcl: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(space='mySpace')\n\nres = client.data_modeling.spaces.retrieve(spaces=[\"MySpace\", \"MyAwesomeSpace\", \"MyOtherSpace\"])\n"
}
]
}
},
"/models/spaces/delete": {
"post": {
"tags": [
"Spaces"
],
"summary": "Delete spaces",
"description": "Delete one or more spaces. Currently limited to 100 spaces at a time.\n\n\nIf an existing data model references a space, you cannot delete that space. Nodes, edges and other data types that are part of a space will no longer be available. ",
"operationId": "deleteSpacesV3",
"requestBody": {
"description": "List of space-ids for spaces to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOfSpaceIdsRequest"
}
}
},
"required": true
},
"x-capability": [
"DataModelsAclAdmin: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(space=[\"mySpace\", \"myOtherSpace\"])\n"
}
]
}
},
"/models/datamodels": {
"post": {
"tags": [
"Data models"
],
"summary": "Create or update data models",
"description": "Add 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": [
"DataModelsAclAdmin: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 = [DataModelApply(space=\"mySpace\",external_id=\"myDataModel\",version=\"v1\"),\nDataModelApply(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": "List 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": "Retrieve 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": {
"$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": "Delete 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": [
"DataModelsAclAdmin: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": "Add 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": [
"DataModelsAdminAcl: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\nviews = [ViewApply(space=\"mySpace\",external_id=\"myView\",version=\"v1\"),\nViewApply(space=\"mySpace\",external_id=\"myOtherView\",version=\"v1\")]\nres = client.data_modeling.views.apply(views)\n"
}
]
},
"get": {
"tags": [
"Views"
],
"summary": "List views defined in the project",
"description": "List 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": "Retrieve 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": {
"$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": "Delete one or more views. Currently limited to 100 views at a time. The service cannot delete a view referenced by a data model.",
"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": [
"DataModelsAclAdmin: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": "Add 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": [
"DataModelsAdminAcl: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"
}
]
},
"get": {
"tags": [
"Containers"
],
"summary": "List containers defined in the project",
"description": "List 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"
}
],
"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": "Retrieve 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": "Delete one or more containers. Currently limited to 100 containers at a time. You cannot delete a container when one or more data model(s) or view(s) references it.",
"operationId": "deleteContainers",
"requestBody": {
"description": "List of the spaces and external-ids for the containers you want to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOfSpaceExternalIdsRequest"
}
}
},
"required": true
},
"x-capability": [
"DataModelsAclAdmin: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": "Delete one or more container indexes. Currently limited to 10 indexes at a time.",
"operationId": "deleteContainerIndexes",
"requestBody": {
"description": "List of the references to indexes you want to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest"
}
}
},
"required": true
},
"x-capability": [
"DataModelsAclAdmin: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/constraints/delete": {
"post": {
"tags": [
"Containers"
],
"summary": "Delete constraints from containers",
"description": "Delete one or more container constraints. Currently limited to 10 constraints at a time.",
"operationId": "deleteContainerConstraints",
"requestBody": {
"description": "List of the references to constraints you want to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOfContainerSubObjectIdentifierRequest"
}
}
},
"required": true
},
"x-capability": [
"DataModelsAclAdmin: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/instances": {
"post": {
"tags": [
"Instances"
],
"summary": "Create or update nodes/edges",
"description": "Create 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\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\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",
"operationId": "applyNodeAndEdges",
"requestBody": {
"description": "Nodes/edges to add or update.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeAndEdgeCreateCollection"
}
}
},
"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\nnodes = [NodeApply(\"mySpace\", \"myNodeId\")]\nres = client.data_modeling.instances.apply(nodes)\n\nfrom cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply, ViewId\nperson = NodeApply(\"mySpace\", \"person:arnold_schwarzenegger\", sources=[\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n {\"name\": \"Arnold Schwarzenegger\", \"birthYear\": 1947})\n])\nactor = NodeApply(\"mySpace\", \"actor:arnold_schwarzenegger\", sources=[\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"ActorView\", \"v1\"),\n {\"wonOscar\": False,\n # This is a one-to-one edge from actor to person\n \"person\": {\"space\": \"mySpace\", \"externalId\": \"person:arnold_schwarzenegger\"}})\n])\nperson_to_actor = EdgeApply(space=\"mySpace\",\n external_id=\"relation:arnold_schwarzenegger:actor\",\n type=(\"Person\", \"roles\"),\n start_node=(\"person\", \"arnold_schwarzenegger\"),\n end_node=(\"actor\", \"arnold_schwarzenegger\"),\n)\nres = client.data_modeling.instances.apply([person, actor], [person_to_actor])\n\nfrom cognite.client.data_classes.data_modeling import EdgeApply\nedge = EdgeApply(space=\"mySpace\",\n external_id=\"relation:sylvester_stallone:actor\",\n type=(\"Person\", \"roles\"),\n start_node=(\"person\", \"sylvester_stallone\"),\n end_node=(\"actor\", \"sylvester_stallone\"),\n)\nres = client.data_modeling.instances.apply(edges=edge, auto_create_start_nodes=True, auto_create_end_nodes=True)\n"
}
]
}
},
"/models/instances/list": {
"post": {
"tags": [
"Instances"
],
"summary": "Filter nodes/edges",
"description": "Filter 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\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": "Retrieve 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/NodeAndEdgeCollectionResponseV3"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.data_modeling.instances.retrieve(nodes=(\"mySpace\", \"myNodeExternalId\"),\n edges=(\"mySpace\", \"myEdgeExternalId\"),\n sources=(\"mySpace\", \"myViewExternalId\", \"myViewVersion\")\n )\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId, ViewId\nres = client.data_modeling.instances.retrieve(NodeId(\"mySpace\", \"myNode\"),\n EdgeId(\"mySpace\", \"myEdge\"),\n ViewId(\"mySpace\", \"myViewExternalId\", \"myViewVersion\")\n )\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId\nres = client.data_modeling.instances.retrieve(NodeId(\"mySpace\", \"myNode\"),\n EdgeId(\"mySpace\", \"myEdge\"),\n sources=(\"myspace\", \"myView\")\n )\n"
}
]
}
},
"/models/instances/search": {
"post": {
"tags": [
"Instances"
],
"summary": "Search for nodes/edges",
"description": "Search 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/NodeAndEdgeCollectionResponseV3"
},
"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(ViewId(\"mySpace\", \"PersonView\", \"v1\"), query=\"Arnold\", properties=[\"name\"])\n\nfrom cognite.client.data_classes.data_modeling import ViewId\nimport cognite.client.data_classes.filters as filters\nborn_after_1970 = filters.Range([\"mySpace\", \"PersonView/v1\", \"birthYear\"], gt=1970)\nres = client.data_modeling.instances.search(ViewId(\"mySpace\", \"PersonView\", \"v1\"),\nquery=\"Quentin\", properties=[\"name\"], filter=born_after_1970)\n"
}
]
}
},
"/models/instances/aggregate": {
"post": {
"tags": [
"Instances"
],
"summary": "Aggregate data across nodes/edges",
"description": "Aggregate 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": "Delete 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. ",
"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": "Specification 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"
}
]
}
},
"/models/instances/sync": {
"post": {
"tags": [
"Instances"
],
"summary": "Sync nodes/edges",
"description": "Subscribe 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"
}
]
}
},
"/events": {
"post": {
"tags": [
"Events"
],
"summary": "Create events",
"description": "Creates 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 Event\nevents = [Event(start_time=0, end_time=1), Event(start_time=2, end_time=3)]\nres = client.events.create(events)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Event> 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": "List 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: `[\"<fieldname>:asc|desc\"]`. Default sort order is `asc` with short syntax: `[\"<fieldname>\"]`.\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\nf = filters\nis_workorder = f.Prefix(\"external_id\", \"workorder\")\nhas_failure = f.Search(\"description\", \"failure\")\nres = client.events.filter(filter=f.And(is_workorder, has_failure),\n sort=(\"start_time\", \"desc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nf = filters\nis_workorder = f.Prefix(EventProperty.external_id, \"workorder\")\nhas_failure = f.Search(EventProperty.description, \"failure\")\nres = client.events.filter(filter=f.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"
}
]
}
},
"/events/{id}": {
"get": {
"tags": [
"Events"
],
"summary": "Receive an event by its ID",
"description": "Retrieves 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": "Retrieve 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. <br /> `{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values. <br /> `{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value. <br /> `{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has value). <br /> `{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values. <br /> `{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified value. <br /> `{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range. <br /> `{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}` <br /> Supported operators: `gt`, `lt`, `gte`, `lte` |\n| `search` | `[\"description\"]` | Introduced to provide functional parity with /events/search endpoint. <br /> `{\"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- `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\nf = filters\nis_workorder = f.Prefix(\"external_id\", \"workorder\")\nhas_failure = f.Search(\"description\", \"failure\")\nres = client.events.filter(filter=f.And(is_workorder, has_failure),\n sort=(\"start_time\", \"desc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nf = filters\nis_workorder = f.Prefix(EventProperty.external_id, \"workorder\")\nhas_failure = f.Search(EventProperty.description, \"failure\")\nres = client.events.filter(filter=f.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"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Event> 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": "The 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(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": "Retrieves information about events in the same project. Events are returned in the same order as the ids listed in the query.\nA maximum of 1000 event IDs may be listed per request and all of them must be unique.\n### Request throttling This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please 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<Item> byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList<Event> resultByExternalIds = \n client.events().retrieve(byExternalIds);//by list of items \nList<Event> resultByExternalIds = \n client.events().retrieve(\"10\", \"20\");//by varargs of String \n\n List<Item> byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList<Event> resultByInternalIds = \n client.events().retrieve(byInternalIds);//by list of items \nList<Event> resultByInternalIds = \n client.events().retrieve(10, 20);//by varargs of Long \n\n"
}
]
}
},
"/events/update": {
"post": {
"tags": [
"Events"
],
"summary": "Update events",
"description": "Updates events in the same project. This operation supports partial updates; Fields omitted from queries will remain unchanged on objects.\nFor primitive fields (String, Long, Int), use 'set': 'value' to update value; use 'setNull': true to set that field to null.\nFor the Json Array field (e.g. assetIds), use 'set': [value1, value2] to update value; use 'add': [v1, v2] to add values to current list of values; use 'remove': [v1, v2] to remove these values from current list of values if exists.\nA maximum of 1000 events can be updated per request, and all of the event IDs must be unique.\n### Request throttling This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please 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": "Fulltext 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": "Deletes events with the given ids. A maximum of 1000 events can be deleted per request.\n### Request throttling This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please 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<Item> byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList<Item> resultByExternalIds = \n client.events().delete(byExternalIds); \n\nList<Item> byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList<Item> resultByInternalIds = \n client.events().delete(byInternalIds); \n\n"
}
]
}
},
"/files": {
"post": {
"tags": [
"Files"
],
"summary": "Upload file",
"description": "Create 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 uploadUrl from initFileUpload supports files smaller than 5 GiB.\n\nThe initMultiPartUpload and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1 TiB 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.",
"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<FileContainer> 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<FileMetadata> uploadFileResult = \n client.files().upload(fileContainerInput); \n\n"
}
]
}
},
"/files/initmultipartupload": {
"post": {
"tags": [
"Files"
],
"summary": "Upload multipart file",
"description": "Multipart file upload enables upload of files larger than 5 GiB, using a uniform API on all cloud environments for CDF.\n\nEach file part must be larger than 5 MiB, and smaller than 5 GiB. The file part for the last uploadURL can be smaller than 5 MiB.\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.",
"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": 200
},
"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"
]
},
"get": {
"tags": [
"Files"
],
"summary": "List files",
"description": "The 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.",
"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/{id}": {
"get": {
"tags": [
"Files"
],
"summary": "Retrieve a file by its ID",
"description": "Returns file info for the file ID",
"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-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": "Retrieves a list of all files in a project. Criteria can be supplied to select a subset of files. This operation supports pagination with cursors.",
"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<FileMetadata> 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": "Retrieves 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.",
"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-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<FileMetadata> retrievedFilesByExternalIds = client.files().retrieve(\"10\");//by varargs of String \nList<Item> itemsExternalId = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<FileMetadata> resultsExternal = client.files().retrieve(itemsExternalId);//by list of items \n\nList<FileMetadata> retrievedFilesByInternalIds = client.files().retrieve(10, 20);//by varargs of Long \nList<Item> itemsInternalId = List.of(Item.newBuilder().setId(10).build()); \nList<FileMetadata> resultsInternal = client.files().retrieve(itemsInternalId);//by list of items \n\n"
}
]
}
},
"/files/search": {
"post": {
"tags": [
"Files"
],
"summary": "Search files",
"description": "Search for files based on relevance. You can also supply a strict match filter as in Filter files, and search in the results from the filter. Returns first 1000 results based on relevance. This operation does not support pagination.",
"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": "Deletes the files with the given ids.\n\nA maximum of 1000 files can be deleted per request.",
"operationId": "deleteFiles",
"requestBody": {
"description": "List of IDs of files to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileDataIds"
}
}
},
"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<Item> deleteByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList<Item> deleteItemsResults = client.files().delete(deleteByExternalIds); \n\nList<Item> deleteByInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList<Item> deleteItemsResults = client.files().delete(deleteByInternalIds); \n\n"
}
]
}
},
"/files/downloadlink": {
"post": {
"tags": [
"Files"
],
"summary": "Download files",
"description": "Retrieves a list of download URLs for the specified list of file IDs. After getting the download links, the client has to issue a GET request to the returned URLs, which will respond with the contents of the file. The links will by default expire after 30 seconds. If providing the query parameter extendedExpiration the links will expire after 1 hour.",
"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-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<Item> downloadByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList<FileContainer> downloadFilesResults = \n client.files().downloadToPath(downloadByExternalIds, Paths.get(\"\")); \n\nList<Item> downloadByInternallIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList<FileContainer> downloadFilesResults = \n client.files().downloadToPath(downloadByInternallIds, Paths.get(\"\")); \n\n"
}
]
}
},
"/files/icon": {
"get": {
"tags": [
"Files"
],
"summary": "Get icon",
"description": "The 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.",
"operationId": "getIcon",
"parameters": [
{
"in": "query",
"name": "id",
"schema": {
"$ref": "#/components/schemas/CogniteInternalId"
}
},
{
"in": "query",
"name": "externalId",
"schema": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
],
"responses": {
"200": {
"description": "Thumbnail image (JPEG)",
"content": {
"image/jpeg": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
]
}
},
"/files/update": {
"post": {
"tags": [
"Files"
],
"summary": "Update files",
"description": "Updates 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```",
"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<FileMetadata> editFilesInput = listFilesResults.stream() \n .map(fileMetadata -> fileMetadata.toBuilder() \n .putMetadata(\"addedField\", \"new field value\") \n .build()) \n .collect(Collectors.toList()); \n\n List<FileMetadata> editFilesResult = \n client.files().upsert(editFilesInput); \n\n"
}
]
}
},
"/files/aggregate": {
"post": {
"tags": [
"Files"
],
"summary": "Aggregate files",
"description": "Calculate aggregates for files, based on optional filter specification. Returns the following aggregates: `count`",
"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": "Completes a multipart file upload. This endpoint must be called by the client when an 'initMultiPartUpload' operation (POST /files/initmultipartupload) was called, and all file content parts have been successfully uploaded using PUT for all upload URLs. Either `id` or `externalId` must be specified in the request body, but not both. The `uploadId` is also required. The values for these properties can be retrieved from the response of the initMultiPartUpload operation.",
"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"
]
}
},
"/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": "List functions.",
"x-capability": [
"functionsAcl:READ"
]
},
"post": {
"summary": "Create functions",
"operationId": "postFunctions",
"responses": {
"201": {
"$ref": "#/components/responses/FunctionList"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"description": "You 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": "py38",
"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 ...\nfunction = client.functions.create(name=\"myfunction\", function_handle=handle)\n"
}
]
}
},
"/functions/limits": {
"get": {
"tags": [
"Functions"
],
"summary": "Functions limits",
"description": "Service 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": "Delete 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:WRITE"
],
"summary": "Call a function asynchronously",
"operationId": "postFunctionsCall",
"responses": {
"201": {
"$ref": "#/components/responses/FunctionCalled"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"description": "Perform 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": "List 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": "Retrieve 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": "Retrieve 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": "Get logs from a function call."
}
},
"/functions/{functionId}": {
"parameters": [
{
"$ref": "#/components/parameters/functionId"
}
],
"get": {
"operationId": "getFunction",
"description": "Retrieve 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": "Retrieve 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": "Activate 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": "Get 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": "List 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": "Create 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": "Retrieve 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": "Retrieve 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": "Delete 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": "Retrieve 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": "Retrieve 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"
}
]
}
},
"/3d/files/{threedFileId}": {
"get": {
"tags": [
"3D Files"
],
"summary": "Retrieve a single 3D file",
"description": "Retrieve 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": "Retrieve 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": "Retrieves 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": "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": {
"$ref": "#/components/schemas/Model3DWithCursorResponse"
}
}
}
},
"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<ThreeDModel> 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": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/CreateModel3D"
}
}
}
}
}
},
"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\")\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<ThreeDModel> upsertThreeDModelsList = List.of( \n ThreeDModel.newBuilder() \n .setName(\"generated-\") \n .setDataSetId(dataSetId) \n .setCreatedTime(1552566113).build()); \nList<ThreeDModel> listUpsert = \n client.threeD() \n .models() \n .upsert(upsertThreeDModelsList); \n\n"
}
]
}
},
"/3d/models/update": {
"post": {
"tags": [
"3D Models"
],
"summary": "Update 3D models",
"operationId": "update3DModels",
"requestBody": {
"description": "List of changes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/UpdateModel3D"
}
}
}
}
}
},
"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<ThreeDModel> listUpsert = \n client.threeD() \n .models() \n .upsert(List.of(update)); \n\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": {
"$ref": "#/components/schemas/DataIdentifiers"
}
}
},
"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<Item> deleteItemsResultsByExternalIds = \n client.threeD() \n .models() \n .delete(List.of(Item.newBuilder().setExternalId(\"10\").build())); \n\nList<Item> deleteItemsResultsByInternalIds = \n client.threeD() \n .models() \n .delete(List.of(Item.newBuilder().setId(10).build())); \n\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<ThreeDModel> retrievedByInternalIds = \n client.threeD() \n .models() \n .retrieve(List.of(Item.newBuilder().setId(10).build())); \n\nList<ThreeDModel> retrievedByExternalIds = \n client.threeD() \n .models() \n .retrieve(List.of(Item.newBuilder().setExternalId(\"10\").build())); \n\n"
}
]
}
},
"/3d/models/{modelId}/revisions": {
"get": {
"tags": [
"3D Model Revisions"
],
"summary": "List 3D revisions",
"description": "Retrieves a list of all revisions of a model. This operation supports pagination. You can also filter revisions if they are marked as published or not by using the query param published.",
"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<ThreeDModelRevision> 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",
"operationId": "create3DRevisions",
"parameters": [
{
"$ref": "#/components/parameters/ModelId"
}
],
"requestBody": {
"description": "The revisions to create.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/CreateRevision3D"
}
}
}
}
}
}
},
"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 ThreeDModelRevision\nmy_revision = ThreeDModelRevision(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<FileContainer> 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<FileMetadata> 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<ThreeDModelRevision> 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": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/UpdateRevision3D"
}
}
}
}
}
}
},
"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<ThreeDModelRevision> tdUpdateResults = \nclient.threeD() \n .models() \n .revisions() \n .upsert(10L, List.of(th)); \n\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": {
"$ref": "#/components/schemas/DataIdentifiers"
}
}
},
"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<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<Item> deleteItemsResults = client.threeD().models().revisions().delete(20L, byInternalIds); \n\nList<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<Item> deleteItemsResults = client.threeD().models().revisions().delete(20L, byExternalIds); \n\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<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<ThreeDModelRevision> resultsByInternalIds = client.threeD().models().revisions().retrieve(10L, byInternalIds); \n\nList<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<ThreeDModelRevision> resultsByExternalIds = client.threeD().models().revisions().retrieve(10L, byExternalIds); \n\n"
}
]
}
},
"/3d/models/{modelId}/revisions/{revisionId}/logs": {
"get": {
"tags": [
"3D Model Revisions"
],
"summary": "List 3D revision logs",
"description": "List 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<FileContainer> list = List.of(FileContainer.newBuilder().setFileMetadata(fileMetadata).setFileBinary(FileBinary.newBuilder() \n .setBinary(ByteString.copyFrom(fileByteA))).build()); \nList<FileMetadata> 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"
}
]
}
},
"/3d/models/{modelId}/revisions/{revisionId}/outputs": {
"get": {
"tags": [
"3D Model Revisions"
],
"summary": "List available outputs",
"description": "Retrieve a list of available outputs for a processed 3D model. An output can be a format that can be consumed by a viewer (e.g. Reveal) or import in external tools. Each of the outputs will have an associated version which is used to identify the version of output format (not the revision of the processed output). Note that the structure of the outputs will vary and is not covered here.",
"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": "Retrieves a list of nodes from the hierarchy in the 3D model. You can also request a specific subtree with the 'nodeId' query parameter and limit the depth of the resulting subtree with the 'depth' query parameter. By default, nodes are returned in order of ascending treeIndex. We suggest trying to set the query parameter `sortByNodeId` to `true` to check whether it makes your use case faster. The `partition` parameter can only be used if `sortByNodeId` is set to `true`. This operation supports pagination. 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<ThreeDModelRevision> 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": "List 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<List<ThreeDNode>> itFilter = client.threeD() \n .models() \n .revisions() \n .nodes() \n .filter(model.getId(), revision.getId()); \n List<ThreeDNode> listResults = itFilter.next(); \n\n//with parameters \nRequest request = Request.create() \n .withFilterParameter(\"properties\", createFilterPropertiesWithCategories()); \n\nList<ThreeDNode> 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": "Retrieves 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<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<ThreeDNode> nodesByIds = client.threeD() \n .models() \n .revisions() \n .nodes() \n .retrieve(model.getId(), revision.getId(), byInternalIds); \n\nList<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \n List<ThreeDNode> 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": "Retrieves 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<ThreeDNode> 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": "List all asset mappings\n\n\nAsset references obtained from a mapping - through asset ids - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are NOT maintained by any means from CDF, meaning they will be stored until the\nreference is removed through the delete endpoint of 3d asset mappings.",
"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"
}
}
],
"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"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Iterator<List<ThreeDAssetMapping>> itFilter = client.threeD() \n .models() \n .revisions() \n .assetMappings() \n .list(model.getId(), revision.getId()); \nList<ThreeDAssetMapping> listResultsList = itFilter.next(); \n\n"
}
]
},
"post": {
"tags": [
"3D Asset Mapping"
],
"summary": "Create 3D asset mappings",
"description": "Create asset mappings\n\n\nAsset references when creating a mapping - through asset ids - are allowed to be\ninvalid.\nThey are NOT maintained by any means from CDF, meaning they will be stored until the\nreference is removed through the delete endpoint of 3d asset mappings.",
"operationId": "create3DMappings",
"parameters": [
{
"$ref": "#/components/parameters/ModelId"
},
{
"$ref": "#/components/parameters/RevisionId"
}
],
"requestBody": {
"description": "The asset mappings to create.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/CreateAssetMapping3D"
}
}
}
}
}
},
"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 ThreeDAssetMapping\nmy_mapping = ThreeDAssetMapping(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<ThreeDAssetMapping> items = List.of(ThreeDAssetMapping.newBuilder() \n .setAssetId(1L) \n .setNodeId(1L) \n .build()); \n\nList<ThreeDAssetMapping> 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": "Delete a list of asset mappings",
"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": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/DeleteAssetMapping3D"
}
}
}
}
}
},
"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<ThreeDAssetMapping> 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": "Lists 3D assets mappings that match the specified filter parameter. Only\none type of filter can be specified for each request, either `assetIds`, `nodeIds` or `treeIndexes`.\n\n\nAsset references obtained from a mapping - through asset ids - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are NOT maintained by any means from CDF, meaning they will be stored until the\nreference is removed through the delete endpoint of 3d asset mappings.",
"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<List<ThreeDAssetMapping>> 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": "Retrieves a list of `node IDs` from the hierarchy of all available 3D models which are mapped to the supplied `asset ID`. If a `node ID` is mapped to the `asset ID` but is invalid or does not exist anymore, it will be omitted from the results.\n\n\nAsset references obtained from a mapping - through asset id - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are NOT maintained by any means from CDF, meaning they will be stored until the\nreference is removed through the delete endpoint of 3d asset mappings.",
"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"
]
}
},
"/timeseries": {
"get": {
"tags": [
"Time series"
],
"summary": "List time series",
"description": "List 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 import filters\nf = filters\nis_numeric = f.Equals(\"is_string\", False)\nres = client.time_series.filter(filter=is_numeric, sort=\"external_id\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty\nf = filters\nis_numeric = f.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"
}
]
},
"post": {
"tags": [
"Time series"
],
"summary": "Create time series",
"description": "Creates 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 TimeSeries\nts = client.time_series.create(TimeSeries(name=\"my ts\"))\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<TimeseriesMetadata> 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": "Retrieves 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<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<TimeseriesMetadata> retrievedAssets = client.timeseries().retrieve(byExternalIds);// by list of items \nList<TimeseriesMetadata> retrievedAssets = client.timeseries().retrieve(\"10\", \"20\");// by varargs of String \n\nList<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<TimeseriesMetadata> retrievedAssets = client.timeseries().retrieve(byInternalIds);// by list of items \nList<TimeseriesMetadata> retrievedAssets = client.timeseries().retrieve(10, 20);// by varargs of Long \n\n"
}
]
}
},
"/timeseries/list": {
"post": {
"tags": [
"Time series"
],
"summary": "Filter time series",
"description": "<details>\n<summary>\nRetrieves a list of time series that match the given criteria.\n</summary>\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. <br /> `{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values. <br /> `{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value. <br /> `{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has a value). <br /> `{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values. <br /> `{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified text. <br /> `{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range. <br /> `{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}` <br /> Supported operators: `gt`, `lt`, `gte`, `lte` |\n | `search` | `[\"name\"]` and `[\"description\"]` | Introduced to provide functional parity with the /timeseries/search endpoint. <br /> `{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n#### Supported properties\n\n| Property | Type |\n|-----------------------------------|--------------------|\n| `[\"description\"]` | string |\n| `[\"externalId\"]` | string |\n| `[\"metadata\", \"<someCustomKey>\"]` | string |\n| `[\"name\"]` | string |\n| `[\"unit\"]` | string |\n| `[\"unitExternalId\"]` | string |\n| `[\"unitQuantity\"]` | 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| `[\"accessCategories\"]` | array of strings |\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\", \"<someCustomKey>\"]\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\", \"<someCustomKey>\"]` |\n| `[\"name\"]` |\n\n\n#### Limits\n\nThe `sort` array must contain 1 to 2 elements.\n</details>",
"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 import filters\nf = filters\nis_numeric = f.Equals(\"is_string\", False)\nres = client.time_series.filter(filter=is_numeric, sort=\"external_id\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty\nf = filters\nis_numeric = f.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"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<TimeseriesMetadata> listTimeseriesResults = new ArrayList<>(); \nclient.timeseries() \n .list() \n .forEachRemaining(timeseries -> listTimeseriesResults.addAll(timeseries)); \n\nList<TimeseriesMetadata> 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": "The 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<details>\r\n<summary>\r\nThe default behavior, when the <code>aggregate</code> 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\n<code>aggregate</code> field is set to <code>count</code>.\r\n</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>uniqueValues</code> and specifying a property in <code>properties</code> (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</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>cardinalityValues</code> 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</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>uniqueProperties</code> will return the set of unique properties whose property\r\npath begins with <code>path</code> (which can currently only be <code>[\"metadata\"]</code>) that are contained in the time series that match the filters.\r\n</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>cardinalityProperties</code> will instead return the approximate number of\r\ndifferent property keys whose path begins with <code>path</code> (which can currently only be <code>[\"metadata\"]</code>, meaning that this can only be used to count the approximate number of distinct metadata keys among the matching time series).\r\n</summary>\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</details>\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<details>\r\n<summary>\r\nClick here for more details about <code>aggregateFilter</code>. \r\n</summary>\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</details>\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://developer.cognite.com/dev/concepts/request_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": "Fulltext 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": "Updates 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"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "client.timeseries().upsert(upsertTimeseriesList); \n\n"
}
]
}
},
"/timeseries/delete": {
"post": {
"tags": [
"Time series"
],
"summary": "Delete time series",
"description": "Deletes 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/TimeSeriesLookupById"
}
}
},
"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.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<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<Item> deletedAssets = client.timeseries().delete(byInternalIds); \n\nList<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<Item> deletedAssets = client.timeseries().delete(byExternalIds); \n\n"
}
]
}
},
"/timeseries/data": {
"post": {
"tags": [
"Time series"
],
"summary": "Insert data points",
"description": "Insert 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](<https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_point_insertion_request.proto>) and [Data Points](<https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_points.proto>)",
"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 or external 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 datetime import datetime, timezone\n\ndatapoints = []\ndatapoints.append(\n {\"id\": 1, \"datapoints\": [\n (datetime(2018,1,1,tzinfo=timezone.utc), 1000),\n (datetime(2018,1,2,tzinfo=timezone.utc), 2000),\n]})\n\ndatapoints.append({\"external_id\": \"foo\", \"datapoints\": [(150000000000, 1000), (160000000000, 2000)]})\n\ndata_to_clone = client.time_series.data.retrieve(external_id=\"bar\")\ndatapoints.append({\"external_id\": \"bar-clone\", \"datapoints\": data_to_clone})\nclient.time_series.data.insert_multiple(datapoints)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<TimeseriesPointPost> 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": "Retrieves a list of data points from multiple time series in a project.\nThis operation supports aggregation and pagination.\nLearn more about [aggregation](<https://docs.cognite.com/dev/concepts/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](<https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_point_list_response.proto>) and [Data Points](<https://raw.githubusercontent.com/cognitedata/protobuf-files/master/v1/timeseries/data_points.proto>)",
"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\")\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\ndps_lst = client.time_series.data.retrieve(\n id=[\n {\"id\": 42, \"end\": \"1d-ago\", \"aggregates\": \"average\"},\n {\"id\": 69, \"end\": \"2d-ago\", \"aggregates\": [\"average\"]},\n {\"id\": 96, \"end\": \"3d-ago\", \"aggregates\": [\"min\", \"max\", \"count\"]},\n ],\n external_id={\"external_id\": \"foo\", \"aggregates\": \"max\"},\n start=\"5d-ago\",\n granularity=\"1h\")\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 {\"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=[{\"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\nts1 = 1337\nts2 = {\n \"id\": 42,\n \"start\": -12345, # Overrides `start` arg. below\n \"end\": \"1h-ago\",\n \"limit\": 1000, # Overrides `limit` arg. below\n \"include_outside_points\": True,\n}\nts3 = {\n \"id\": 11,\n \"end\": \"1h-ago\",\n \"aggregates\": [\"max\"],\n \"granularity\": \"42h\",\n \"include_outside_points\": False,\n \"ignore_unknown_ids\": True, # Overrides `ignore_unknown_ids` arg. below\n}\ndps_lst = client.time_series.data.retrieve(\n id=[ts1, ts2, ts3], start=\"2w-ago\", limit=None, ignore_unknown_ids=False)\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<TimeseriesPoint> results = new ArrayList<>(); \n\nList<Item> 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<Item> 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": "Retrieves 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": "The time series doesn't exist.",
"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\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))]\nres = client.time_series.data.retrieve_latest(\n id=id_queries,\n external_id=LatestDatapointQuery(external_id=\"abc\", before=\"3h-ago\"))\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList<TimeseriesPoint> result = \n client.timeseries().dataPoints() \n .retrieveLatest(byExternalIds);//by list of items \nList<TimeseriesPoint> result = \n client.timeseries().dataPoints() \n .retrieveLatest(\"10\", \"20\");//by varargs of String \n\nList<Item> byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \nList<TimeseriesPoint> result = \n client.timeseries().dataPoints() \n .retrieveLatest(byInternalIds);//by list of items \nList<TimeseriesPoint> 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": "Delete 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<Item> byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\").build()); \nList<Item> deletedItems = \n client.timeseries().dataPoints().delete(byExternalIds); \n\nList<Item> byInternalIds = List.of(Item.newBuilder() \n .setId(10).build()); \n List<Item> deletedItems = \n client.timeseries().dataPoints().delete(byInternalIds); \n\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": "dps = client.time_series.data.synthetic.query(expressions=\"TS{id:123} + TS{externalId:'abc'}\", start=\"2w-ago\", end=\"now\")\n\nvars = {\"A\": \"my_ts_external_id\", \"B\": client.time_series.retrieve(id=1)}\ndps = client.time_series.data.synthetic.query(expressions=\"A+B\", start=\"2w-ago\", end=\"now\", variables=vars)\n\nfrom sympy import symbols, cos, sin\na = symbols('a')\ndps = client.time_series.data.synthetic.query([sin(a), cos(a)], start=\"2w-ago\", end=\"now\", variables={\"a\": \"my_ts_external_id\"}, aggregate='interpolation', granularity='1m')\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<String> listDatabaseResults = new ArrayList<>(); \nclient.raw() \n .databases() \n .list() \n .forEachRemaining(listDatabaseResults::addAll); \n\n"
}
]
},
"post": {
"tags": [
"Raw"
],
"summary": "Create databases",
"description": "Create 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<String> createDatabasesList = \n List.of(StringValue.of(\"dbName\").getValue()); \nclient.raw().databases().create(createDatabasesList);"
}
]
}
},
"/raw/dbs/delete": {
"post": {
"tags": [
"Raw"
],
"summary": "Delete databases",
"description": "It 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<String> createDatabasesList = \n List.of(StringValue.of(\"dbName\").getValue()); \nList<String> 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<String> tablesResults = new ArrayList<>(); \nclient.raw().tables() \n .list(\"dbName\") \n .forEachRemaining(tablesResults::addAll); \n\n"
}
]
},
"post": {
"tags": [
"Raw"
],
"summary": "Create tables in a database",
"description": "Create 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<String> 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<String> listDeleted = \n client.raw().tables().delete(\"dbName\", List.of(\"TablesName\")); \n\n"
}
]
}
},
"/raw/dbs/{dbName}/tables/{tableName}/cursors": {
"get": {
"tags": [
"Raw"
],
"summary": "Retrieve cursors for parallel reads",
"description": "Retrieve 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\", \"t1\", limit=5)\n\nfor row in client.raw.rows(db_name=\"db1\", table_name=\"t1\", columns=[\"col1\",\"col2\"]):\n row # do something with the row\n\nfor row_list in client.raw.rows(db_name=\"db1\", table_name=\"t1\", chunk_size=2500):\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<RawRow> listRowsResults = new ArrayList<>(); \nclient.raw().rows().list(\"dbName\", \"TablesName\") \n .forEachRemaining(listRowsResults::addAll); \n\n"
}
]
},
"post": {
"tags": [
"Raw"
],
"summary": "Insert rows into a table",
"description": "Insert 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": "rows = {\"r1\": {\"col1\": \"val1\", \"col2\": \"val1\"}, \"r2\": {\"col1\": \"val2\", \"col2\": \"val2\"}}\nclient.raw.rows.insert(\"db1\", \"table1\", rows)\nimport pandas as pd\ndf = pd.DataFrame(data={\"a\": 1, \"b\": 2}, index=[\"r1\", \"r2\", \"r3\"])\nres = client.raw.rows.insert_dataframe(\"db1\", \"table1\", df)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<RawRow> 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<RawRow> 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"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<String> rowsToRetrieve = createRowsList.stream() \n .filter(row -> ThreadLocalRandom.current().nextBoolean()) \n .map(row -> row.getKey()) \n .collect(Collectors.toList()); \n\nList<RawRow> rowsRetrieved = \n client.raw().rows().retrieve(\"dbName\", \"tableName\", rowsToRetrieve); \n\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<RawRow> rowsToDelete = //list of RawRow; \nList<RawRow> deleteRowResults = client.raw().rows().delete(rowsToDelete); \n\n"
}
]
}
},
"/groups": {
"get": {
"tags": [
"Groups"
],
"summary": "List groups",
"description": "Retrieves 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": "res = client.iam.groups.list()\n"
}
]
},
"post": {
"tags": [
"Groups"
],
"summary": "Create groups",
"description": "Creates one or more named groups, each with a set of capabilities.",
"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 Group\nmy_capabilities = [{\"groupsAcl\": {\"actions\": [\"LIST\"],\"scope\": {\"all\": { }}}}]\nmy_group = Group(name=\"My Group\", capabilities=my_capabilities)\nres = client.iam.groups.create(my_group)\n"
}
]
}
},
"/groups/delete": {
"post": {
"tags": [
"Groups"
],
"summary": "Delete groups",
"description": "Deletes 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": {
"get": {
"servers": [
{
"url": "https://{cluster}.cognitedata.com/api/v1",
"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"
]
}
}
}
],
"tags": [
"Projects"
],
"summary": "List projects",
"description": "The list of all projects that the user has the 'list projects' capability in.\nThe user may not have access to any resources in the listed projects, even if they have access to list the project itself.\n",
"operationId": "listProjects",
"parameters": [],
"responses": {
"200": {
"$ref": "#/components/responses/ProjectListResponse"
}
}
},
"post": {
"tags": [
"Projects"
],
"summary": "Create a project",
"description": "Creates new projects given project details.\nThis functionality is currently only available for Cognite and re-sellers of Cognite Data Fusion. Please contact Cognite Support for more information.\n",
"operationId": "createProject",
"requestBody": {
"description": "List of new project specifications",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataProjectSpec"
}
}
},
"required": true
},
"responses": {
"201": {
"$ref": "#/components/responses/ProjectCreationResponse"
}
},
"x-capability": [
"projectsAcl:CREATE"
]
}
},
"/projects/{project}": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"get": {
"servers": [
{
"url": "https://{cluster}.cognitedata.com/api/v1",
"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"
]
}
}
}
],
"tags": [
"Projects"
],
"summary": "Retrieve a project",
"description": "Retrieves information about a project given the project URL name.",
"operationId": "getProject",
"responses": {
"200": {
"$ref": "#/components/responses/ProjectResponse"
}
},
"x-capability": [
"projectsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const projectInfo = await client.projects.retrieve('publicdata');"
}
]
}
},
"/update": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"post": {
"tags": [
"Projects"
],
"summary": "Update a project",
"description": "Updates the project configuration.\n\n**Warning**: Updating a project will invalidate active [sessions](tag/Sessions) within that project.\n",
"operationId": "updateProject",
"requestBody": {
"description": "Object with updated project configuration.",
"content": {
"application/json": {
"schema": {
"description": "Project Update Object",
"title": "ProjectUpdateDTO",
"type": "object",
"properties": {
"update": {
"$ref": "#/components/schemas/ProjectUpdateObjectDTO"
}
},
"required": [
"update"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/ProjectResponse"
}
},
"x-capability": [
"projectsAcl:UPDATE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.projects.updateProject('new-project-name', {\n update: {\n name: {\n set: 'New project display name',\n }\n }\n})"
}
]
}
},
"/securitycategories": {
"get": {
"tags": [
"Security categories"
],
"summary": "List security categories",
"description": "Retrieves 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<SecurityCategory> 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": "Creates 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 SecurityCategory\nmy_category = SecurityCategory(name=\"My Category\")\nres = client.iam.security_categories.create(my_category)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<SecurityCategory> 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": "Deletes 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<SecurityCategory> deleteItemsResults = \n client.securityCategories() \n .delete(listSecurityCategoriesResults); \n\n "
}
]
}
},
"/datasets": {
"post": {
"tags": [
"Data sets"
],
"summary": "Create data sets",
"description": "You 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 DataSet\ndata_sets = [DataSet(name=\"1st level\"), DataSet(name=\"2nd level\")]\nres = client.data_sets.create(data_sets)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<DataSet> 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<DataSet> upsertDataSetsResults = \n client.datasets().upsert(upsertDataSetList); \n\n"
}
]
}
},
"/datasets/list": {
"post": {
"tags": [
"Data sets"
],
"summary": "Filter data sets",
"description": "Use advanced filtering options to find data sets.",
"operationId": "listDataSets",
"requestBody": {
"description": "List of IDs of the data sets to retrieve. You can retrieve a maximum of 1000 data sets per request. All IDs must be unique.",
"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<DataSet> 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": "Aggregate 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": "Retrieve 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<Item> retrieveByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList<DataSet> retrieveDataSetResults = client.datasets() \n .retrieve(retrieveByExternalIds);//by list of items \nList<DataSet> retrieveDataSetResults = client.datasets() \n .retrieve(\"10\", \"20\");//by varargs of String \n\nList<Item> retrieveByInternalIds = List.of(Item.newBuilder() \n .setId(10) \n .build()); \nList<DataSet> retrieveDataSetResults = client.datasets() \n .retrieve(retrieveByInternalIds);//by list of items \nList<DataSet> 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<DataSet> upsertDataSetList = //list of DataSet; \nList<DataSet> upsertDataSetsResults = \n client.datasets().upsert(upsertDataSetList); \n\n"
}
]
}
},
"/sequences": {
"get": {
"tags": [
"Sequences"
],
"summary": "List sequences",
"operationId": "listSequences",
"description": "List 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\nf = filters\nis_asset = f.Equals(\"asset_id\", 123)\nis_efficiency = f.Equals([\"metadata\", \"type\"], \"efficiency\")\nres = client.time_series.filter(filter=f.And(is_asset, is_efficiency), sort=\"created_time\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nf = filters\nis_asset = f.Equals(SequenceProperty.asset_id, 123)\nis_efficiency = f.Equals(SequenceProperty.metadata_key(\"type\"), \"efficiency\")\nres = client.time_series.filter(filter=f.And(is_asset, 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 sequences\n\nfor seq_list in client.sequences(chunk_size=2500):\n seq_list # do something with the sequences\n"
}
]
},
"post": {
"tags": [
"Sequences"
],
"summary": "Create sequences",
"description": "Create 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 Sequence\ncolumn_def = [\n {\"valueType\": \"STRING\", \"externalId\": \"user\", \"description\": \"some description\"},\n {\"valueType\": \"DOUBLE\", \"externalId\": \"amount\"}]\nseq = client.sequences.create(Sequence(external_id=\"my_sequence\", columns=column_def))\n\nseq2 = client.sequences.create(Sequence(external_id=\"my_copied_sequence\", columns=seq.columns))\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<SequenceColumn> 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<SequenceMetadata> 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": "<details>\n<summary>\nRetrieves a list of sequences that match the given criteria.\n</summary>\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. <br /> `{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values. <br /> `{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value. <br /> `{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has a value). <br /> `{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values. <br /> `{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified text. <br /> `{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range. <br /> `{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}` <br /> Supported operators: `gt`, `lt`, `gte`, `lte` |\n | `search` | `[\"name\"]` and `[\"description\"]` | Introduced to provide functional parity with the /sequences/search endpoint. <br /> `{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n#### Supported properties\n\n| Property | Type |\n|-----------------------------------|--------------------|\n| `[\"description\"]` | string |\n| `[\"externalId\"]` | string |\n| `[\"metadata\", \"<someCustomKey>\"]` | string |\n| `[\"name\"]` | string |\n| `[\"assetId\"]` | number |\n| `[\"assetRootId\"]` | number |\n| `[\"createdTime\"]` | number |\n| `[\"dataSetId\"]` | number |\n| `[\"id\"]` | number |\n| `[\"lastUpdatedTime\"]` | number |\n| `[\"accessCategories\"]` | array of strings |\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\", \"<someCustomKey>\"]\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\", \"<someCustomKey>\"]` |\n| `[\"name\"]` |\n\n\n#### Limits\n\nThe `sort` array must contain 1 to 2 elements.\n</details>",
"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\nf = filters\nis_asset = f.Equals(\"asset_id\", 123)\nis_efficiency = f.Equals([\"metadata\", \"type\"], \"efficiency\")\nres = client.time_series.filter(filter=f.And(is_asset, is_efficiency), sort=\"created_time\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nf = filters\nis_asset = f.Equals(SequenceProperty.asset_id, 123)\nis_efficiency = f.Equals(SequenceProperty.metadata_key(\"type\"), \"efficiency\")\nres = client.time_series.filter(filter=f.And(is_asset, 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 sequences\n\nfor seq_list in client.sequences(chunk_size=2500):\n seq_list # do something with the sequences\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<SequenceMetadata> 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": "The 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<details>\r\n<summary>\r\nThe default behavior, when the <code>aggregate</code> 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\n<code>aggregate</code> field is set to <code>count</code>.\r\n</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>uniqueValues</code> and specifying a property in <code>properties</code> (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</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>cardinalityValues</code> will instead return the approximate number of\r\ndistinct values that are taken on by the given property among the matching sequences.\r\n</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>uniqueProperties</code> will return the set of unique properties whose property\r\npath begins with <code>path</code> (which can currently only be <code>[\"metadata\"]</code>) that are contained in the sequences that match the filters.\r\n</summary>\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</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>cardinalityProperties</code> will instead return the approximate number of\r\ndifferent property keys whose path begins with <code>path</code> (which can currently only be <code>[\"metadata\"]</code>, meaning that this can only be used to count the approximate number of distinct metadata keys among the matching sequences).\r\n</summary>\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</details>\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<details>\r\n<summary>\r\nClick here for more details about <code>aggregateFilter</code>. \r\n</summary>\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</details>\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://developer.cognite.com/dev/concepts/request_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": "Retrieves 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(external_id=\"1\")\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<SequenceMetadata> retrievedByExternalIds = client.sequences().retrieve(\"10\");//by varargs of String \nList<Item> listItemsExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<SequenceMetadata> retrievedSequencesExternalIds = client.sequences().retrieve(listItemsExternalIds);//by list of items \n\nList<SequenceMetadata> retrievedByInternalIds = client.sequences().retrieve(10, 20);//by varargs of Long \nList<Item> listItemsInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<SequenceMetadata> retrievedSequencesInternalIds = client.sequences().retrieve(listItemsInternalIds); \n\n"
}
]
}
},
"/sequences/search": {
"post": {
"tags": [
"Sequences"
],
"summary": "Search sequences",
"description": "Retrieves 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": "Updates 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\nmy_update = SequenceUpdate(id=1).columns.add({\"valueType\":\"STRING\",\"externalId\":\"user\",\"description\":\"some description\"})\nres = client.sequences.update(my_update)\n\nfrom cognite.client.data_classes import SequenceUpdate\ncolumn_def = [{\"valueType\":\"STRING\",\"externalId\":\"user\",\"description\":\"some description\"}, {\"valueType\":\"DOUBLE\",\"externalId\":\"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": "Deletes 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<Item> deleteItemsSequencesByExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \nList<Item> externalIdsResults = client.sequences().delete(deleteItemsSequencesByExternalIds); \n\nList<Item> deleteItemsSequencesByInternalIds = List.of(Item.newBuilder().setId(10).build()); \n List<Item> InternalIdsResults = client.sequences().delete(deleteItemsSequencesByInternalIds); \n\n"
}
]
}
},
"/sequences/data": {
"post": {
"tags": [
"Sequences"
],
"summary": "Insert rows",
"description": "Inserts 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": "seq = client.sequences.create(Sequence(columns=[{\"valueType\": \"STRING\", \"externalId\":\"col_a\"},{\"valueType\": \"DOUBLE\", \"externalId\":\"col_b\"}]))\ndata = [(1, ['pi',3.14]), (2, ['e',2.72]) ]\nclient.sequences.data.insert(column_external_ids=[\"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, column_external_ids=[\"col_a\",\"col_b\"]) # implicit columns are retrieved from metadata\n\ndata = {123 : ['str',3], 456 : ['bar',42] }\nclient.sequences.data.insert(column_external_ids=['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,column_external_ids=None)\ndf = client.sequences.data.retrieve_dataframe(id=123, start=0, end=None)\nclient.sequences.data.insert_dataframe(df*2, id=123)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<SequenceMetadata> 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<SequenceBody> upsertSequenceBodyResponse = client.sequences().rows().upsert(List.of(body)); \n\n"
}
]
}
},
"/sequences/data/list": {
"post": {
"tags": [
"Sequences"
],
"summary": "Retrieve rows",
"description": "Processes 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, start=0, end=None)\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<List<SequenceBody>> listRetrieved = client.sequences().rows().retrieve(Request.create()); \n\nIterator<List<SequenceBody>> list = client.sequences().rows().retrieveComplete(List.of(Item.newBuilder().setId(10).build()));//by list of items \nIterator<List<SequenceBody>> list = client.sequences().rows().retrieveComplete(10);//by varargs of Long \n\nIterator<List<SequenceBody>> list = client.sequences().rows().retrieveComplete(List.of(Item.newBuilder().setExternalId(\"10\").build()));//by list of items \nIterator<List<SequenceBody>> list = client.sequences().rows().retrieveComplete(\"10\");//by varargs of String \n\n"
}
]
}
},
"/sequences/data/latest": {
"post": {
"tags": [
"Sequences"
],
"summary": "Retrieve last row",
"description": "Retrieves 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_latest(id=1, before=1000)\n"
}
]
}
},
"/sequences/data/delete": {
"post": {
"tags": [
"Sequences"
],
"summary": "Delete rows",
"description": "Deletes 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)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<SequenceBody> deleteRowsInput = listSequencesRowsResults; \nList<SequenceBody> deleteRowsResults = client.sequences().rows().delete(deleteRowsInput);"
}
]
}
},
"/labels": {
"post": {
"tags": [
"Labels"
],
"summary": "Create label definitions.",
"description": "Creates 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 LabelDefinition\nlabels = [LabelDefinition(external_id=\"ROTATING_EQUIPMENT\", name=\"Rotating equipment\"), LabelDefinition(external_id=\"PUMP\", name=\"pump\")]\nres = client.labels.create(labels)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Label> upsertLabelsList = List.of(Label.newBuilder() \n .setExternalId(\"10\") \n .setName(\"Label name\") \n .setDescription(\"Description\") \n .build()); \n\nList<Label> list = client.labels().upsert(upsertLabelsList); \n\n"
}
]
}
},
"/labels/list": {
"post": {
"tags": [
"Labels"
],
"summary": "Filter labels",
"description": "Use advanced filtering options to find label definitions.",
"operationId": "listLabels",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LabelDefinitionListScope"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/LabelDefinitionListResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"labelsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const labels = await client.labels.list({ filter: { externalIdPrefix: 'Pu'}});"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "label_list = client.labels.list(limit=5, name=\"Pump\")\n\nfor label in client.labels:\n label # do something with the label definition\n\nfor label_list in client.labels(chunk_size=2500):\n label_list # do something with the type definitions\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Label> listLabelsResults = new ArrayList<>(); \nclient.labels() \n .list() \n .forEachRemaining(labels -> listLabelsResults.addAll(labels)); \n\nclient.labels() \n .list(Request.create() \n .withFilterParameter(\"externalIdPrefix\", \"Val\")) \n .forEachRemaining(labels -> listLabelsResults.addAll(labels)); \n\n"
}
]
}
},
"/labels/delete": {
"post": {
"tags": [
"Labels"
],
"summary": "Delete label definitions.",
"description": "Delete all the label definitions specified by their external ids. The resource items that have the corresponding label attached remain unmodified. It is up to the client to clean up the resource items from their attached labels if necessary.",
"operationId": "deleteLabels",
"requestBody": {
"description": "List of external ids of label definitions to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LabelDefinitionExternalIdList"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"labelsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.labels.delete([{externalId: 'PUMP'}, {externalId: 'VALVE'}]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "client.labels.delete(external_id=[\"big_pump\", \"small_pump\"])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> deleteItemsByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList<Item> deleteItemsResults = \n client.labels().delete(deleteItemsByExternalIds); \n\nList<Item> deleteItemsByInternalIds = List.of(Item.newBuilder() \n .setId(10) \n .build()); \nList<Item> deleteItemsResults = \n client.labels().delete(deleteItemsByInternalIds); \n\n"
}
]
}
},
"/relationships": {
"post": {
"summary": "Create relationships",
"tags": [
"Relationships"
],
"description": "List of the relationships to create. You can create a maximum of 1000 relationships per request. Relationships should be unique, but CDF does not prevent you from creating duplicates where only the externalId differs.\n\nRelationships are uniquely identified by their externalId. Non-unique relationships will not be created.\n\nThe order of relationships in the response equals the order in the request.",
"operationId": "createRelationships",
"responses": {
"201": {
"$ref": "#/components/responses/persistedRelationships"
},
"400": {
"$ref": "#/components/responses/400GeneralError"
},
"409": {
"$ref": "#/components/responses/409GeneralError"
},
"500": {
"$ref": "#/components/responses/generalError"
}
},
"requestBody": {
"$ref": "#/components/requestBodies/newRelationship"
},
"deprecated": false,
"x-capability": [
"relationshipsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const relationships = [\n {\n externalId: 'some_relationship',\n sourceExternalId: 'some_source_external_id',\n sourceType: 'asset' as const,\n targetExternalId: 'some_target_external_id',\n targetType: 'event' as const\n }\n];\nconst createdRelationships = await client.relationships.create(relationships);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import Relationship\nflowrel1 = Relationship(\n external_id=\"flow_1\",\n source_external_id=\"source_ext_id\",\n source_type=\"asset\",\n target_external_id=\"target_ext_id\",\n target_type=\"event\",\n confidence=0.1,\n data_set_id=1234\n)\nflowrel2 = Relationship(\n external_id=\"flow_2\",\n source_external_id=\"source_ext_id\",\n source_type=\"asset\",\n target_external_id=\"target_ext_id\",\n target_type=\"event\",\n confidence=0.1,\n data_set_id=1234\n)\nres = client.relationships.create([flowrel1,flowrel2])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Asset> assetUpsertList = //list of Asset; \nList<Event> eventUpsertList = //list of Event; \nList<TimeseriesMetadata> timseriesUpsertList = //list of TimeseriesMetadata; \nList<SequenceMetadata> sequenceUpsertList = // list of SequenceMetadata; \n\nList<Relationship> relationshipList = new ArrayList<>(); \n\n//EVENT AND ASSET \nrelationshipList.add( \n Relationship.newBuilder() \n .setStartTime(Instant.now().toEpochMilli()) \n .setEndTime(Instant.now().toEpochMilli()) \n .setSourceType(Relationship.ResourceType.EVENT) \n .setSourceExternalId(eventUpsertList.get(0).getExternalId()) \n .setTargetType(Relationship.ResourceType.ASSET) \n .setTargetExternalId(assetUpsertList.get(0).getExternalId()) \n .setConfidence(ThreadLocalRandom.current().nextFloat()) \n .build()); \n\n//TIME_SERIES AND ASSET \nrelationshipList.add( \n Relationship.newBuilder() \n .setStartTime(Instant.now().toEpochMilli()) \n .setEndTime(Instant.now().toEpochMilli()) \n .setSourceType(Relationship.ResourceType.TIME_SERIES) \n .setSourceExternalId(timseriesUpsertList.get(1).getExternalId()) \n .setTargetType(Relationship.ResourceType.ASSET) \n .setTargetExternalId(assetUpsertList.get(1).getExternalId()) \n .setConfidence(ThreadLocalRandom.current().nextFloat()) \n .build()); \n\n//SEQUENCE AND EVENT \nrelationshipList.add( \n Relationship.newBuilder() \n .setStartTime(Instant.now().toEpochMilli()) \n .setEndTime(Instant.now().toEpochMilli()) \n .setSourceType(Relationship.ResourceType.SEQUENCE) \n .setSourceExternalId(sequenceUpsertList.get(2).getExternalId()) \n .setTargetType(Relationship.ResourceType.EVENT) \n .setTargetExternalId(eventUpsertList.get(2).getExternalId()) \n .setConfidence(ThreadLocalRandom.current().nextFloat()) \n .build()); \n\nList<Relationship> upsertRelationshipsList = client.relationships() \n .upsert(relationshipList); \n\n"
}
]
},
"get": {
"summary": "List relationships",
"tags": [
"Relationships"
],
"description": "Lists all relationships. The order of retrieved objects may change for two calls with the same parameters.\nThe endpoint supports pagination. The initial call to this endpoint should not contain a cursor, but the cursor parameter should be used to retrieve further pages of results.",
"operationId": "getRelationships",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"$ref": "#/components/parameters/partition"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/pagedPersistedRelationships"
},
"500": {
"$ref": "#/components/responses/generalError"
}
},
"deprecated": false,
"x-capability": [
"relationshipsAcl:READ"
]
}
},
"/relationships/update": {
"post": {
"summary": "Update relationships",
"tags": [
"Relationships"
],
"description": "Update relationships between resources according to the partial definitions of the relationships given in the payload of the request. This means that fields not mentioned in the payload will remain unchanged. Up to 1000 relationships can be updated in one operation.\nTo delete a value from an optional value the `setNull` field should be set to `true`.\nThe order of the updated relationships in the response equals the order in the request.",
"operationId": "updateRelationships",
"requestBody": {
"$ref": "#/components/requestBodies/updateObject"
},
"responses": {
"200": {
"$ref": "#/components/responses/persistedRelationships"
},
"400": {
"$ref": "#/components/responses/generalError"
},
"409": {
"$ref": "#/components/responses/409GeneralError"
}
},
"x-capability": [
"relationshipsAcl:WRITE",
"relationshipsAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "rel = client.relationships.retrieve(external_id=\"flow1\")\nrel.confidence = 0.75\nres = client.relationships.update(rel)\n\nfrom cognite.client.data_classes import RelationshipUpdate\nmy_update = RelationshipUpdate(external_id=\"flow_1\").source_external_id.set(\"alternate_source\").confidence.set(0.97)\nres1 = client.relationships.update(my_update)\nanother_update = RelationshipUpdate(external_id=\"flow_1\").confidence.set(None)\nres2 = client.relationships.update(another_update)\n\nfrom cognite.client.data_classes import RelationshipUpdate\nmy_update = RelationshipUpdate(external_id=\"flow_1\").labels.add([\"PUMP\", \"VERIFIED\"])\nres = client.relationships.update(my_update)\n\nfrom cognite.client.data_classes import RelationshipUpdate\nmy_update = RelationshipUpdate(external_id=\"flow_1\").labels.remove(\"PUMP\")\nres = client.relationships.update(my_update)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Relationship> relationshipList = // list of Relationship for update; \nList<Relationship> upsertRelationshipsList = \n client.relationships().upsert(relationshipList); \n\n"
}
]
}
},
"/relationships/delete": {
"post": {
"summary": "Delete relationships",
"tags": [
"Relationships"
],
"description": "Delete the relationships between resources identified by the external IDs in the request. You can delete a maximum of 1000 relationships per request.",
"operationId": "deleteRelationships",
"requestBody": {
"$ref": "#/components/requestBodies/delete"
},
"responses": {
"202": {
"$ref": "#/components/responses/emptyDeleteResponse"
},
"409": {
"$ref": "#/components/responses/409GeneralError"
},
"500": {
"$ref": "#/components/responses/generalError"
}
},
"x-capability": [
"relationshipsAcl:WRITE"
],
"deprecated": false,
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.relationships.delete([{externalId: 'abc'}, {externalId: 'def'}]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "client.relationships.delete(external_id=[\"a\",\"b\"])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> deleteItemsInput = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList<Item> deleteItemsResults = \n client.relationships().delete(deleteItemsInput); \n\n"
}
]
}
},
"/relationships/byids": {
"post": {
"summary": "Retrieve relationships",
"tags": [
"Relationships"
],
"description": "Retrieve relationships by external IDs. You can retrieve a maximum of 1000 relationships per request.\nThe order of the relationships in the response equals the order in the request.",
"operationId": "byidsRelationships",
"requestBody": {
"$ref": "#/components/requestBodies/listOfExternalIds"
},
"responses": {
"200": {
"$ref": "#/components/responses/enrichedPersistedRelationships"
},
"400": {
"$ref": "#/components/responses/generalError"
},
"409": {
"$ref": "#/components/responses/409GeneralError"
}
},
"x-capability": [
"relationshipsAcl:READ"
],
"deprecated": false,
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const relationships = await client.relationships.retrieve([{externalId: 'abc'}, {externalId: 'def'}]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.relationships.retrieve_multiple(external_ids=[\"abc\", \"def\"])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList<Relationship> list = \n client.relationships().retrieve(byExternalIds);//by list of items \nList<Relationship> list = \n client.relationships().retrieve(\"10\", \"20\");//by varargs of String \n\nList<Item> byInternalIds = List.of(Item.newBuilder() \n .setId(10) \n .build()); \nList<Relationship> list = \n client.relationships().retrieve(byInternalIds, true);//by list of items \nList<Relationship> list1 = \n client.relationships().retrieve(10,20);//by varargs of Long \n\n"
}
]
}
},
"/relationships/list": {
"post": {
"summary": "Filter relationships",
"tags": [
"Relationships"
],
"description": "Lists relationships matching the query filter in the request. You can retrieve a maximum of 1000 relationships per request.",
"operationId": "listRelationships",
"requestBody": {
"$ref": "#/components/requestBodies/advancedList"
},
"responses": {
"200": {
"$ref": "#/components/responses/filteredRelationships"
},
"400": {
"$ref": "#/components/responses/generalError"
},
"409": {
"$ref": "#/components/responses/409GeneralError"
}
},
"x-capability": [
"relationshipsAcl:READ"
],
"deprecated": false,
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const relationships = await client.relationships.list({ filter: { createdTime: { min: new Date('1 jan 2018'), max: new Date('1 jan 2019') }}});"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "relationship_list = client.relationships.list(limit=5)\n\nfor relationship in client.relationships:\n relationship # do something with the relationship\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Relationship> listRelationshipsResults = new ArrayList<>(); \nclient.relationships() \n .list() \n .forEachRemaining(listRelationshipsResults::addAll); \n\nclient.relationships() \n .list(Request.create() \n .withRootParameter(\"fetchResources\", true)) \n .forEachRemaining(listRelationshipsResults::addAll); \n\n"
}
]
}
},
"/context/diagram/detect": {
"post": {
"tags": [
"Engineering diagrams"
],
"summary": "Detect annotations in engineering diagrams",
"description": "Detect annotations in engineering diagrams. Note: All users in a CDF project with assets read-all and files read access to the requested files can access data sent to this endpoint.\nSupported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff. Also note that the header of a successful response contains an `X-Job-Token` which allows to fetch the result of the \njob at `/context/diagram/detect/{jobId}` without requiring 'assetsAcl:READ'.",
"operationId": "diagramDetect",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"entities"
],
"allOf": [
{
"properties": {
"items": {
"type": "array",
"description": "Files to run entity detection on.",
"minItems": 1,
"maxItems": 50,
"items": {
"$ref": "#/components/schemas/FileReferenceWithPageRange"
}
},
"entities": {
"$ref": "#/components/schemas/DiagramDetectEntities"
}
}
},
{
"$ref": "#/components/schemas/DiagramDetectConfig"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId",
"items"
],
"allOf": [
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileReferenceWithPageRange"
}
},
"jobId": {
"$ref": "#/components/schemas/JobId"
},
"status": {
"$ref": "#/components/schemas/BatchJobStatus"
}
}
},
{
"$ref": "#/components/schemas/StatusSchema"
},
{
"$ref": "#/components/schemas/DiagramDetectConfig"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ",
"filesAcl:READ"
]
}
},
"/context/diagram/detect/{jobId}": {
"get": {
"tags": [
"Engineering diagrams"
],
"summary": "Retrieve engineering diagram detect results",
"description": "Get the results from an engineering diagram detect job. Providing the `X-Job-Token` header returned by the \n`/context/diagram/detect` endpoint is required unless the caller has read access to all assets.",
"operationId": "diagramDetectResults",
"parameters": [
{
"$ref": "#/components/parameters/jobId"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId"
],
"allOf": [
{
"properties": {
"jobId": {
"$ref": "#/components/schemas/JobId"
},
"status": {
"$ref": "#/components/schemas/BatchJobStatus"
},
"items": {
"$ref": "#/components/schemas/DiagramDetectResultSchema"
}
}
},
{
"$ref": "#/components/schemas/StatusSchema"
},
{
"$ref": "#/components/schemas/DiagramDetectConfig"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ",
"filesAcl:READ"
]
}
},
"/context/diagram/convert": {
"post": {
"tags": [
"Engineering diagrams"
],
"summary": "Convert a diagram to image format",
"description": "Convert interactive engineering diagrams to image format, with highlighted annotations.\nSupported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff.\nSupported output image formats are PNG and SVG, only the svg embeds the input annotations.",
"operationId": "diagramConvert",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"allOf": [
{
"properties": {
"items": {
"$ref": "#/components/schemas/DiagramConvertRequestSchema"
}
}
},
{
"$ref": "#/components/schemas/DiagramConvertConfig"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId",
"items"
],
"allOf": [
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OneOfFileId"
}
},
"jobId": {
"$ref": "#/components/schemas/JobId"
},
"status": {
"$ref": "#/components/schemas/BatchJobStatus"
}
}
},
{
"$ref": "#/components/schemas/StatusSchema"
},
{
"$ref": "#/components/schemas/DiagramConvertConfig"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ",
"filesAcl:READ"
]
}
},
"/context/diagram/convert/{jobId}": {
"get": {
"tags": [
"Engineering diagrams"
],
"summary": "Get the results for converting an engineering diagram to an image",
"description": "Get the results for converting an engineering diagram to SVG and PNG formats.",
"operationId": "diagramConvertResults",
"parameters": [
{
"$ref": "#/components/parameters/jobId"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId"
],
"allOf": [
{
"properties": {
"jobId": {
"$ref": "#/components/schemas/JobId"
},
"status": {
"$ref": "#/components/schemas/BatchJobStatus"
},
"items": {
"$ref": "#/components/schemas/DiagramConvertResultSchema"
}
}
},
{
"$ref": "#/components/schemas/StatusSchema"
},
{
"$ref": "#/components/schemas/DiagramConvertConfig"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ",
"filesAcl:READ"
]
}
},
"/context/entitymatching": {
"get": {
"tags": [
"Entity matching"
],
"summary": "List entity matching models",
"description": "List all available entity matching models.",
"operationId": "entityMatchingModels",
"parameters": [
{
"in": "query",
"name": "limit",
"description": "Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.",
"schema": {
"type": "integer",
"default": 100,
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:READ"
]
},
"post": {
"tags": [
"Entity matching"
],
"summary": "Create entity matcher model",
"description": "Train a model that predicts matches between entities (for example, time series names to asset names). This is also known as fuzzy joining. If there are no trueMatches (labeled data), you train a static (unsupervised) model, otherwise a machine learned (supervised) model is trained.",
"operationId": "entityMatchingCreate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sources",
"targets"
],
"properties": {
"sources": {
"$ref": "#/components/schemas/Sources"
},
"targets": {
"$ref": "#/components/schemas/Targets"
},
"trueMatches": {
"$ref": "#/components/schemas/TrueMatches"
},
"externalId": {
"$ref": "#/components/schemas/CogniteExternalId"
},
"name": {
"$ref": "#/components/schemas/ModelName"
},
"description": {
"$ref": "#/components/schemas/ModelDescription"
},
"featureType": {
"description": "Each feature type defines one combination of features that will be created and used in the entity matcher model. All features are based on matching tokens. Tokens are defined at the top of the Entity matching section.\nThe options are:\n * Simple: Calculates the cosine-distance similarity score for each of the pairs of fields defined in `matchFields`. This is the fastest option.\n * Insensitive: Similar to Simple, but ignores lowercase/uppercase differences.\n * Bigram: Similar to `simple`, but adds similarity score based on matching bigrams of the tokens.\n * FrequencyWeightedBigram: Similar to `bigram`, but give higher weights to less commonly occurring tokens.\n * BigramExtraTokenizers: Similar to `bigram`, but able to learn that leading zeros, spaces, and uppercase/lowercase differences should be ignored in matching.\n * BigramCombo: Calculates all of the above options, relying on the model to determine the appropriate features to use.\n Hence, this option is only appropriate if there are labeled data/trueMatches. This is the slowest option.\n",
"allOf": [
{
"$ref": "#/components/schemas/FeatureType"
}
]
},
"matchFields": {
"$ref": "#/components/schemas/MatchFields"
},
"classifier": {
"$ref": "#/components/schemas/Classifier"
},
"ignoreMissingFields": {
"$ref": "#/components/schemas/IgnoreMissingFields"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const result = await client.entityMatching.create({\n sources: [{externalId: 'asset1', name: 'asset1'}, {externalId: 'asset2', name: 'asset2'}],\n targets: [{externalId: 'ts1', name: 'ts1'}, {externalId: 'ts2', name: 'ts2'}],\n externalId: 'model123',\n name: 'model123',\n});"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Struct> source = generateSourceStructs(); \nList<Struct> target = generateTargetTrainingStructs(); \n\n// Train the matching model \nRequest entityMatchFitRequest = Request.create() \n .withRootParameter(\"sources\", source) \n .withRootParameter(\"targets\", target) \n .withRootParameter(\"matchFields\", Map.of(\"source\", \"name\", \"target\", \"externalId\")) \n .withRootParameter(\"featureType\", \"insensitive\"); \n\nList<EntityMatchModel> models = client.contextualization() \n .entityMatching() \n .create(List.of(entityMatchFitRequest)); \n\nprivate List<Struct> generateSourceStructs() { \n Struct entityA = Struct.newBuilder() \n .putFields(\"id\", Values.of(1D)) \n .putFields(\"name\", Values.of(\"23-DB-9101\")) \n .putFields(\"fooField\", Values.of(\"bar\")) \n .build(); \n Struct entityB = Struct.newBuilder() \n .putFields(\"id\", Values.of(2D)) \n .putFields(\"name\", Values.of(\"23-PC-9101\")) \n .putFields(\"barField\", Values.of(\"foo\")) \n .build(); \n return List.of(entityA, entityB); \n} \n\nprivate List<Struct> generateTargetTrainingStructs() { \n Struct targetA = Struct.newBuilder() \n .putFields(\"id\", Values.of(1D)) \n .putFields(\"externalId\", Values.of(\"IA-23_DB_9101\")) \n .build(); \n Struct targetB = Struct.newBuilder() \n .putFields(\"id\", Values.of(2D)) \n .putFields(\"externalId\", Values.of(\"VAL_23_PC_9101\")) \n .build(); \n return List.of(targetA, targetB); \n} \n\n"
}
]
}
},
"/context/entitymatching/{id}": {
"get": {
"tags": [
"Entity matching"
],
"summary": "Retrieve an entity matching model by the ID of the model",
"description": "Shows the status of the model. If the status is completed, shows the parameters used to train the model.",
"operationId": "entityMatchingStatus",
"parameters": [
{
"$ref": "#/components/parameters/CogniteInternalId"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"required": [
"classifier",
"featureType"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:READ"
]
}
},
"/context/entitymatching/byids": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Retrieve entity matching models",
"description": "Retrieve entity matching models by IDs or external IDs.",
"operationId": "entityMatchingRetrieve",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"$ref": "#/components/schemas/OneOfId"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const [result] = await client.entityMatching.retrieve([{ externalId: 'model123' }]);"
}
]
}
},
"/context/entitymatching/list": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Filter models",
"description": "Use filtering options to find entity matcher models.",
"operationId": "entityMatchingFilter",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"filter"
],
"properties": {
"limit": {
"description": "<- Limits the number of results to return.",
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"filter": {
"type": "object",
"allOf": [
{
"description": "Filter on models with strict matching."
},
{
"$ref": "#/components/schemas/EntityMatchingFilterSchema"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const { items } = await client.entityMatching.list({ filter: { name: 'model123' }});"
}
]
}
},
"/context/entitymatching/update": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Update entity matching models",
"description": "Update entity matching models by IDs or external IDs.",
"operationId": "entityMatchingUpdate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelChange"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const [updated] = await client.entityMatching.update([{\n externalId: 'model123',\n update: { description: { set: 'ø' }}\n}]);"
}
]
}
},
"/context/entitymatching/delete": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Delete entity matcher model",
"description": "Deletes an entity matching model. Currently, this is a soft delete, and only removes the entry from listing.",
"operationId": "entityMatchingDelete",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"$ref": "#/components/schemas/OneOfId"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Models deleted.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.entityMatching.delete([{ externalId: 'model123' }]);"
}
]
}
},
"/context/entitymatching/predict": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Predict matches",
"description": "Predicts entity matches using a trained model. Note: 'assetsAcl:READ' capability is required unless both `sources` and `targets` are specified in the request. Also note that the header of a successful response contains a `X-Job-Token` which allows to fetch the result of the job at `/context/entitymatching/jobs/{jobId}` without requiring 'assetsAcl:READ'.",
"operationId": "entityMatchingPredict",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityMatchingPredictSchema"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"headers": {
"X-Job-Token": {
"schema": {
"$ref": "#/components/schemas/JobToken"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId"
],
"allOf": [
{
"properties": {
"jobId": {
"$ref": "#/components/schemas/JobId"
}
}
},
{
"$ref": "#/components/schemas/StatusSchema"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const response = await client.entityMatching.predict({\n externalId: 'model123',\n sources: [{externalId: 'asset1', name: 'asset1'}, {externalId: 'asset2', name: 'asset2'}],\n targets: [{externalId: 'ts1', name: 'ts1'}, {externalId: 'ts2', name: 'ts2'}],\n});"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<EntityMatchModel> models = // list of EntityMatchModel; \nlong modelId = models.get(0).getId(); \nList<Struct> source = generateSourceStructs(); \nList<Struct> target = generateTargetStructs(); \nList<EntityMatchResult> matchResults = client.contextualization() \n .entityMatching() \n .predict(modelId, source, target); \n\nprivate List<Struct> generateSourceStructs() { \n Struct entityA = Struct.newBuilder() \n .putFields(\"id\", Values.of(1D)) \n .putFields(\"name\", Values.of(\"23-DB-9101\")) \n .putFields(\"fooField\", Values.of(\"bar\")) \n .build(); \n Struct entityB = Struct.newBuilder() \n .putFields(\"id\", Values.of(2D)) \n .putFields(\"name\", Values.of(\"23-PC-9101\")) \n .putFields(\"barField\", Values.of(\"foo\")) \n .build(); \n return List.of(entityA, entityB); \n} \n\nprivate List<Struct> generateTargetStructs() { \n Struct targetA = Struct.newBuilder() \n .putFields(\"id\", Values.of(1D)) \n .putFields(\"externalId\", Values.of(\"IA-23_DB_9101\")) \n .putFields(\"uuid\", Values.of(UUID.randomUUID().toString())) \n .build(); \n Struct targetB = Struct.newBuilder() \n .putFields(\"id\", Values.of(2D)) \n .putFields(\"externalId\", Values.of(\"VAL_23_PC_9101\")) \n .putFields(\"uuid\", Values.of(UUID.randomUUID().toString())) \n .build(); \n return List.of(targetA, targetB); \n} \n\n"
}
]
}
},
"/context/entitymatching/jobs/{jobId}": {
"get": {
"tags": [
"Entity matching"
],
"summary": "Retrieve entity matcher predict results",
"description": "Get the results from a predict job. Note: 'assetsAcl:READ' capability is required, unless you specify a valid `X-Job-Token` in the request header. The `X-Job-Token` is provided in the response header of the initial call to `/context/entitymatching/predict`",
"operationId": "entityMatchingPredictResults",
"parameters": [
{
"$ref": "#/components/parameters/jobId"
},
{
"in": "header",
"name": "X-Job-Token",
"schema": {
"$ref": "#/components/schemas/JobToken"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId",
"items"
],
"allOf": [
{
"$ref": "#/components/schemas/StatusSchema"
},
{
"properties": {
"jobId": {
"$ref": "#/components/schemas/JobId"
},
"status": {
"$ref": "#/components/schemas/JobStatus"
},
"items": {
"type": "array",
"description": "List of matched entities with confidence score.",
"items": {
"type": "object",
"required": [
"source",
"matches"
],
"properties": {
"source": {
"type": "object",
"example": {
"field": "value",
"ignoredfield": {
"key": "value"
}
},
"description": "The source item given to predict."
},
"matches": {
"type": "array",
"required": [
"score",
"target"
],
"description": "Matched items, sorted from highest score to lowest. May be empty.",
"items": {
"type": "object",
"properties": {
"score": {
"type": "number",
"example": 0.98,
"description": "The model's confidence in the match."
},
"target": {
"type": "object",
"example": {
"field": "value",
"ignoredfield": {
"key": "value"
}
},
"description": "The target item given to predict."
}
}
}
}
}
}
}
}
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ",
"entitymatchingAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const { status, items } = await client.entityMatching.predictResult(12345678);"
}
]
}
},
"/context/entitymatching/refit": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Re-fit entity matcher model",
"description": "Creates a new model by re-training an existing model on existing data but with additional true matches. The old model is not changed. The new model gets a new id and new external id if `newExternalId` is set, or no external id if `newExternalId` is not set. Use for efficient re-training of the model after a user creates additional confirmed matches.",
"operationId": "entityMatchingReFit",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityMatchingRefitSchema"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"required": [
"classifier",
"featureType",
"originalId"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityMatcherResponseSchema"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"entitymatchingAcl:READ",
"entitymatchingAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.entityMatching.refit({\n newExternalId: 'newModel123',\n sources: [{externalId: 'asset1', name: 'asset1'}, {externalId: 'asset2', name: 'asset2'}],\n targets: [{externalId: 'ts1', name: 'ts1'}, {externalId: 'ts2', name: 'ts2'}],\n externalId: 'model123',\n trueMatches: [{sourceExternalId: 'asset1', targetExternalId: 'ts1'}]\n});"
}
]
}
},
"/context/vision/extract": {
"post": {
"tags": [
"Vision"
],
"summary": "Extract features from images",
"description": "Start an asynchronous prediction job for extracting features such as text, asset tags or industrial objects from images.\nThe response of the POST request contains a job ID, which can be used to make subsequent (GET) calls \nto check the status and retrieve the results of the job \n(see [Retrieve results from a feature extraction job](getVisionExtract)).\n\nIt is possible to have up to 20 concurrent jobs per CDF project.\n\nThe files referenced by `items` in the request body must fulfill the following requirements:\n\n* Must have file extension: `.jpeg`, `.jpg` or `.png`\n* Must have `image/png` or `image/jpeg` as `mimeType`\n\nNew feature extractors may be added in the future.\n",
"operationId": "postVisionExtract",
"parameters": [
{
"$ref": "#/components/parameters/cdfversionheader"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/VisionExtractPostRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/VisionExtractPostResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const job = await client.vision.extract(['TextDetection', 'AssetTagDetection', 'PeopleDetection'], [{ fileId: 1234 }]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes.contextualization import VisionFeature\nextract_job = client.vision.extract(features=VisionFeature.ASSET_TAG_DETECTION, file_ids=[1])\nextract_job.wait_for_completion()\nfor item in extract_job.items:\n predictions = item.predictions\n # do something with the predictions\nextract_job.save_predictions()\n"
}
]
}
},
"/context/vision/extract/{jobId}": {
"get": {
"tags": [
"Vision"
],
"summary": "Retrieve results from a feature extraction job on images",
"description": "Retrieve results from a feature extraction job on images.\n\nNote that since files are split up into batches and processed independently of each other, the items in successfully completed batches will be returned even if files in other batches are still being processed. The job status will be `Running` until all batches have been processed. If one of the items in a batch fails, the results from items in other completed batches will still be returned. The corresponding items and error message(s) of failed batches will be populated in `failedItems`.\nAdditionally, the status of the job is set to `Completed` if at least one batch is successfully completed, otherwise the status is set to `Failed`.\n",
"operationId": "getVisionExtract",
"parameters": [
{
"$ref": "#/components/parameters/cdfversionheader"
},
{
"$ref": "#/components/parameters/jobId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/VisionExtractGetResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const { items } = await client.vision.getExtractJob(12345678, true); // get an existing job, wait for it to complete, and get the results\nitems.forEach((item) => {\n const predictions = item.predictions // do something with the predictions\n});"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "extract_job = client.vision.get_extract_job(job_id=1)\nextract_job.wait_for_completion()\nfor item in extract_job.items:\n predictions = item.predictions\n # do something with the predictions\n"
}
]
}
},
"/context/vision/segment": {},
"/vectorstore/delete": {},
"/vectorstore/list": {},
"/vectorstore/namespaces": {},
"/vectorstore/namespace/{namespace}/upsert": {},
"/vectorstore/namespace/{namespace}/embedding": {},
"/vectorstore/namespace/{namespace}/query": {},
"/api/v1/projects/{projectName}/gpt/chat/completions": {},
"/documents/search": {
"post": {
"tags": [
"Documents"
],
"summary": "Search for documents",
"description": "This endpoint lets you search for documents by using advanced filters and free text queries.\nFree text queries are matched against the documents' filenames and contents.\n\n### Free text search\n\n#### Boolean operators\n\nThe `+` symbol represents an AND operation, and the `|` symbol represents an OR.\nSearching for `lorem + ipsum` will match documents containing both \"lorem\" AND \"ipsum\" in the filename or content.\nSimilarly, searching for `lorem | ipsum` will match documents containing either \"lorem\" OR \"ipsum\" in the filename or\ncontent.\n\nThe default operator between the search keywords is AND.\nThat means that searching for two terms without any operator, for example, `lorem ipsum`, will\nmatch documents containing both the words \"lorem\" and \"ipsum\" in the filename or content.\n\nYou can use the operator `-` to exclude documents containing a specific word.\nFor instance, the search `lorem -ipsum` will match documents that contain the word \"lorem\", but does NOT contain the\nword \"ipsum\".\n\n#### Phrases\n\nEnclose multiple words inside double quotes `\"` to group these words together.\nNormally, the search query `lorem ipsum` will match not only \"lorem ipsum\" but also \"lorem cognite ipsum\",\nand in general, there can be any number of words between the two words in the query.\nThe search query `\"lorem ipsum\"`, however, will match only exactly \"lorem ipsum\" and not \"lorem cognite ipsum\".\n\n#### Escape\n\nTo search for the special characters (`+`, `|`, `-`, `\"`. `\\`), escape with a preceding backslash `\\`.\n\n#### Ordering\n\nWhen you search for a term, the endpoint tries to return the most relevant documents first, with less relevant documents further down\nthe list.\nThere are a few factors that determine the relevance of a document:\n\n- If the search terms are found multiple times within a document, the relevance of that document is higher.\n- For searches with multiple terms, documents containing all the terms are considered more relevant than documents\n containing only some.\n- Matches of the terms in the filename field of the document are more relevant than matches in the document's content.\n\n#### Examples\n\nThe following request will return documents matching the specified search query.\n\n```json\n{\n \"search\": {\n \"query\": \"cognite \\\"lorem ipsum\\\"\"\n }\n}\n ```\n\nThe following example combines a query with a filter.\nThe search request will return documents matching the search query, where `externalId` starts with \"1\".\nThe results will be ordered by how well they match the query string.\n\n```json\n{\n \"search\":{\n \"query\":\"cognite \\\"lorem ipsum\\\"\"\n },\n \"filter\":{\n \"prefix\":{\n \"property\":[\n \"externalId\"\n ],\n \"value\":\"1\"\n }\n }\n}\n```\n\n### Highlights\n\nWhen you enable highlights for your search query, the response contains an additional highlight field for each\nsearch hit, including the highlighted fragments for your query matches. However, the result limit is 20 documents due to the operation costs.\n\n### Filtering\n\nFiltering uses a special JSON filtering language.\nIt's quite flexible and consists of a number of different \"leaf\" filters, which can be combined arbitrarily using the boolean clauses `and`, `or`, and `not`.\n\n#### Supported leaf filters\n\n<table>\n<tr>\n<th> <div style=\"width:150px\"> Leaf filter </div> </th> \n<th> <div style=\"width:200px\"> Supported fields </div> </th> \n<th> Description </th>\n</tr>\n\n<tr>\n<td> <code>equals</code> </td> <td> Non-array type fields </td> <td> Only includes results that are equal to the specified value. \n\n```json\n{\n \"equals\":{\n \"property\":[\n \"property\"\n ],\n \"value\":\"example\"\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>in</code> </td> <td> Non-array type fields </td> <td> Only includes results that are equal to one of the specified values. \n\n```json\n{\n \"in\":{\n \"property\":[\n \"property\"\n ],\n \"values\":[\n 1,\n 2,\n 3\n ]\n }\n}\n```\n</td>\n</tr>\n\n<td> <code>containsAll</code> </td> <td> Array type fields </td> <td> Only includes results which contain all of the specified values. \n\n```json\n{\n \"containsAll\":{\n \"property\":[\n \"property\"\n ],\n \"values\":[\n 1,\n 2,\n 3\n ]\n }\n}\n```\n</td>\n<tr>\n\n<td> <code>containsAny</code> </td> <td> Array type fields </td> <td> Only includes results which contain all of the specified values. \n\n```json\n{\n \"containsAny\":{\n \"property\":[\n \"property\"\n ],\n \"values\":[\n 1,\n 2,\n 3\n ]\n }\n}\n```\n</td>\n\n<tr>\n<td> <code>exists</code> </td> <td> All fields </td> <td> Only includes results where the specified property exists (has value). \n\n```json\n{\n \"exists\":{\n \"property\":[\n \"property\"\n ]\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>prefix</code> </td> <td> String type fields </td> <td> Only includes results which start with the specified value. \n\n```json\n{\n \"prefix\":{\n \"property\":[\n \"property\"\n ],\n \"value\":\"example\"\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>range</code> </td> <td> Non-array type fields </td> <td> Only includes results that fall within the specified range. \n\nSupported operators: <code>gt</code>, <code>lt</code>, <code>gte</code>, <code>lte</code>\n\n```json\n{\n \"range\":{\n \"property\":[\n \"property\"\n ],\n \"gt\":1,\n \"lte\":5\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>geojsonIntersects</code> </td> <td> <code>geoLocation</code> </td> <td> Only includes results where the geoshape intersects with the specified geometry.\n\n```json\n{\n \"geojsonIntersects\":{\n \"property\":[\n \"sourceFile\",\n \"geoLocation\"\n ],\n \"geometry\":{\n \"type\":\"Polygon\",\n \"coordinates\": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],\n }\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>geojsonDisjoint</code> </td> <td> <code>geoLocation</code> </td> <td> Only includes results where the geoshape has nothing in common with the specified geometry.\n\n```json\n{\n \"geojsonDisjoint\":{\n \"property\":[\n \"sourceFile\",\n \"geoLocation\"\n ],\n \"geometry\":{\n \"type\":\"Polygon\",\n \"coordinates\": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],\n }\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>geojsonWithin</code> </td> <td> <code>geoLocation</code> </td> <td> Only includes results where the geoshape falls within the specified geometry.\n\n```json\n{\n \"geojsonWithin\":{\n \"property\":[\n \"sourceFile\",\n \"geoLocation\"\n ],\n \"geometry\":{\n \"type\":\"Polygon\",\n \"coordinates\": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],\n }\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>inAssetSubtree</code> </td> <td> <code>assetIds</code>, <code>assetExternalIds</code> </td> <td> Only includes results with a related asset in a subtree rooted at any specified IDs.\n\n```json\n{\n \"filter\":{\n \"inAssetSubtree\":{\n \"property\":[\n \"sourceFile\",\n \"assetIds\"\n ],\n \"values\":[\n 1,\n 2,\n 3\n ]\n }\n }\n}\n```\n</td>\n</tr>\n\n<tr>\n<td> <code>search</code> </td> <td> <code>name</code>, <code>content</code> </td> <td>\n\n```json\n{\n \"search\":{\n \"property\":[\n \"property\"\n ],\n \"value\":\"example\"\n }\n}\n```\n</td>\n</tr>\n\n</table>\n\n#### Properties\n\nThe following overview shows the properties you can filter and which filter applies to which property.\n\n| Property | Type | Applicable filters |\n|------------------------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `[\"id\"]` | integer | equals, in, range, exists |\n| `[\"externalId\"]` | string | equals, in, prefix, exists |\n| `[\"title\"]` | string | equals, in, prefix, exists |\n| `[\"author\"]` | string | equals, in, prefix, exists |\n| `[\"createdTime\"]` | integer | equals, in, range, exists |\n| `[\"modifiedTime\"]` | integer | equals, in, range, exists |\n| `[\"lastIndexedTime\"]` | integer | equals, in, range, exists |\n| `[\"mimeType\"]` | string | equals, in, prefix, exists |\n| `[\"extension\"]` | string | equals, in, prefix, exists |\n| `[\"pageCount\"]` | integer | equals, in, range, exists |\n| `[\"type\"]` | string | equals, in, prefix, exists |\n| `[\"geoLocation\"]` | geometry object | geojsonIntersects, geojsonDisjoint, geojsonWithin, exists |\n| `[\"language\"]` | string | equals, in, prefix, exists |\n| `[\"assetIds\"]` | array of integers | containsAny, containsAll, exists, inAssetSubtree |\n| `[\"assetExternalIds\"]` | array of strings | containsAny, containsAll, exists, inAssetSubtree |\n| `[\"labels\"]` | array of Labels | containsAny, containsAll, exists |\n| `[\"content\"]` | string | search |\n| `[\"sourceFile\", \"name\"]` | string | equals, in, prefix, exists, search |\n| `[\"sourceFile\", \"mimeType\"]` | string | equals, in, prefix, exists |\n| `[\"sourceFile\", \"size\"]` | integer | equals, in, range, exists |\n| `[\"sourceFile\", \"source\"]` | string | equals, in, prefix, exists |\n| `[\"sourceFile\", \"directory\"]` | string | equals, in, prefix, exists |\n| `[\"sourceFile\", \"assetIds\"]` | array of integers | containsAny, containsAll, exists, inAssetSubtree |\n| `[\"sourceFile\", \"assetExternalIds\"]` | array of strings | containsAny, containsAll, exists, inAssetSubtree |\n| `[\"sourceFile\", \"datasetId\"]` | integer | equals, in, range, exists |\n| `[\"sourceFile\", \"securityCategories\"]` | array of integers | containsAny, containsAll, exists |\n| `[\"sourceFile\", \"geoLocation\"]` | geometry object | geojsonIntersects, geojsonDisjoint, geojsonWithin, exists |\n| `[\"sourceFile\", \"labels\"]` | array of Labels | containsAny, containsAll, exists |\n| `[\"sourceFile\", \"metadata\", <key>]` | string | equals, in, prefix, exists |\n| `[\"sourceFile\", \"metadata\"]` | string | equals, in, prefix, exists<br><br>This is a special filter field that targets all metadata values. <br>An alternative to creating a filter for each key in the metadata field. |\n\n#### Full example\n\n```json\n{\n \"filter\": {\n \"and\": [\n {\n \"or\": [\n {\n \"equals\": {\n \"property\": [\n \"type\"\n ],\n \"value\": \"PDF\"\n }\n },\n {\n \"prefix\": {\n \"property\": [\n \"externalId\"\n ],\n \"value\": \"hello\"\n }\n }\n ]\n },\n {\n \"range\": {\n \"property\": [\n \"createdTime\"\n ],\n \"lte\": 1519862400000\n }\n },\n {\n \"not\": {\n \"in\": {\n \"property\": [\n \"sourceFile\",\n \"name\"\n ],\n \"values\": [\n \"My Document.doc\",\n \"My Other Document.docx\"\n ]\n }\n }\n }\n ]\n }\n}\n ```\n\n### Sorting\n\nBy default, search results are ordered by relevance, meaning how well they match the given query string.\nHowever, it's possible to specify a different property to sort by.\nSorting can be ascending or descending. The sort order is ascending if none is specified.\n\n#### Properties\n\nThe following overview shows all properties that can be sorted on.\n\n| Property |\n|---------------------------------|\n| `[\"id\"]` |\n| `[\"externalId\"]` |\n| `[\"mimeType\"]` |\n| `[\"extension\"]` |\n| `[\"pageCount\"]` |\n| `[\"author\"]` |\n| `[\"title\"]` |\n| `[\"language\"]` |\n| `[\"type\"]` |\n| `[\"createdTime\"]` |\n| `[\"modifiedTime\"]` |\n| `[\"lastIndexedTime\"]` |\n| `[\"sourceFile\", \"name\"]` |\n| `[\"sourceFile\", \"mimeType\"]` |\n| `[\"sourceFile\", \"size\"]` |\n| `[\"sourceFile\", \"source\"]` |\n| `[\"sourceFile\", \"datasetId\"]` |\n| `[\"sourceFile\", \"metadata\", *]` |\n\n#### Example\n\n```json\n{\n \"sort\":[\n {\n \"property\":[\n \"createdTime\"\n ],\n \"order\":\"asc\",\n \n }\n ]\n}\n ```\n",
"operationId": "documentsSearch",
"parameters": [
{
"in": "path",
"name": "project",
"required": true,
"description": "The project name.",
"schema": {
"type": "string",
"example": "publicdata"
}
}
],
"requestBody": {
"description": "Fields to be set for the search request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentSearchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/DocumentSearchResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const documents = await client.documents.search({\n search: {\n query: 'Stuck pipe'\n },\n filter: {\n in: {\n property: ['type'],\n values: ['Document', 'PDF']\n }\n },\n limit: 5\n});"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import filters\nfrom cognite.client.data_classes.documents import DocumentProperty\nis_pdf = filters.Equals(DocumentProperty.mime_type, \"application/pdf\")\ndocuments = client.documents.search(\"pump 123\", filter=is_pdf)\n\nfrom datetime import datetime, timedelta\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.documents import DocumentProperty\nfrom cognite.client.utils import timestamp_to_ms\nis_plain_text = filters.Equals(DocumentProperty.mime_type, \"text/plain\")\nlast_week = filters.Range(DocumentProperty.created_time,\n gt=timestamp_to_ms(datetime.now() - timedelta(days=7)))\ndocuments = client.documents.search('\"CPLEX Error 1217: No Solution exists.\"',\n highlight=True,\n filter=filters.And(is_plain_text, last_week))\n"
}
]
}
},
"/documents/aggregate": {
"post": {
"tags": [
"Documents"
],
"summary": "Aggregate documents",
"description": "The aggregation API lets you compute aggregated results on documents, such as\ngetting the count of all documents in a project, checking\ndifferent authors of documents in a project and the count of documents in\neach of those aggregations. By specifying an additional filter or search, you can\naggregate only among documents matching the specified filter or search.\n\nWhen you don't specify the `aggregate` field in the request\nbody, the default behavior is to return the count of all matched documents.\n\n### Supported aggregates\n\n<table>\n\n<tr>\n<th> <div style=\"width:200px\"> Aggregate </div> </th> \n<th> <div style=\"width:350px\"> Description </div> </th> \n<th> Example </th>\n</tr>\n\n<tr>\n<td> <code>count</code> </td> <td> Count of documents matching the specified filters and search. </td> <td> \n\n```json\n{\n \"search\":{\n \"query\":\"example\",\n \n },\n \"aggregate\":\"count\",\n \n}\n```\n\n<tr>\n<td> <code>cardinalityValues</code> </td> <td> Returns an approximate count of \ndistinct values for the specified properties. </td> <td> \n\n```json\n{\n \"aggregate\":\"cardinalityValues\",\n \"properties\":[\n {\n \"property\":[\n \"mimeType\"\n ]\n }\n ]\n}\n```\n\n</td>\n</tr>\n\n<tr>\n<td> <code>cardinalityProperties</code> </td> <td> Returns an approximate count of\ndistinct properties for a given property path. Currently only implemented for the\n<code>[\"sourceFile\", \"metadata\"]</code> path.</td> <td>\n\n```json\n{\n \"aggregate\":\"cardinalityProperties\",\n \"path\":[\"sourceFile\", \"metadata\"]\n}\n```\n\n</td>\n</tr>\n\n</td>\n</tr>\n\n<tr>\n<td> <code>uniqueValues</code> </td> <td> Returns top unique values for specified properties (up to the\nrequested limit) and the count of each in the property specified in <code>properties</code>. \nThe list will have the highest count first. </td> <td> \n\n```json\n{\n \"aggregate\":\"uniqueValues\",\n \"properties\":[\n {\n \"property\":[\n \"author\"\n ]\n }\n ]\n}\n```\n\n</td>\n</tr>\n\n<tr>\n<td> <code>uniqueProperties</code> </td> <td> Returns top unique properties values for specified properties (up to the\nrequested limit) and the count of each in the property specified in <code>properties</code>. \nThe list will have the highest count first.\n\nCurrently, the <code>uniqueProperties</code> aggregate is only supported for property \n<code>[\"sourceFile\", \"metadata\"]</code> .</td> <td> \n\n```json\n{\n \"aggregate\":\"uniqueProperties\",\n \"properties\":[\n {\n \"property\":[\n \"sourceFile\",\n \"metadata\"\n ]\n }\n ]\n}\n```\n\n</td>\n</tr>\n\n</table>\n\n### Aggregate filtering\n\n> Only some aggregate types currently support <code>aggregateFilter</code>\n\nAggregate filtering works directly on the aggregated result. While a normal filter filters relevant documents, aggregate filtering filters the aggregated bucket values. This is useful for e.g. listing metadata keys; while a normal filter will return all metadata keys for related documents, the aggregate filter can be used to reduce the aggregate result even further.\n\nTip: use both <code>filter</code> and <code>aggregateFilter</code> to potentially speed up queries, as the <code>aggregateFilter</code> is essentially a post filter.\n\n\n#### Filter metadata keys by prefix\n\nHere we only show metadata keys which starts with \"car\".\n```json\n{\n \"aggregate\": \"uniqueProperties\",\n \"properties\": [{\"property\": [\"sourceFile\", \"metadata\"]}],\n \"aggregateFilter\": {\"prefix\": {\"value\": \"car\"}}\n}\n```\n\n#### Filter metadata values by prefix\n\nHere we only show metadata values which starts with \"ctx\", for the given metadata key \"car-codes\".\n```json\n{\n \"aggregate\": \"uniqueValues\",\n \"properties\": [{\"property\": [\"sourceFile\", \"metadata\", \"car-codes\"]}],\n \"aggregateFilter\": {\"prefix\": {\"value\": \"ctx\"}}\n}\n```\n",
"operationId": "documentsAggregate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/DocumentsAggregateCountRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateCardinalityValuesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateCardinalityPropertiesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateUniqueValuesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateUniquePropertiesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateAllUniquePropertiesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateAllUniqueValuesRequest"
}
]
},
"examples": {
"unique-values": {
"value": {
"filter": {
"equals": {
"property": [
"type"
],
"value": "PDF"
}
},
"aggregate": "uniqueValues",
"properties": [
{
"property": [
"author"
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/DocumentsAggregateResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes.documents import SourceFileProperty\ncount = client.documents.aggregate_cardinality_properties(SourceFileProperty.metadata)\nfrom cognite.client.data_classes.documents import DocumentProperty\ncount = client.documents.aggregate_cardinality_values(DocumentProperty.type)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.documents import DocumentProperty\nis_plain_text = filters.Equals(DocumentProperty.mime_type, \"text/plain\")\nplain_text_author_count = client.documents.aggregate_cardinality_values(DocumentProperty.author, filter=is_plain_text)\n\nfrom cognite.client.data_classes.documents import DocumentProperty\nfrom cognite.client.data_classes import aggregations\nagg = aggregations\nis_not_text = agg.Not(agg.Prefix(\"text\"))\ntype_count_excluded_text = client.documents.aggregate_cardinality_values(DocumentProperty.type, aggregate_filter=is_not_text)\ncount = client.documents.aggregate_count()\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.documents import DocumentProperty\nis_pdf = filters.Equals(DocumentProperty.mime_type, \"application/pdf\")\npdf_count = client.documents.aggregate_count(filter=is_pdf)\nfrom cognite.client.data_classes.documents import SourceFileProperty\nresult = client.documents.aggregate_unique_values(SourceFileProperty.metadata)\nfrom cognite.client.data_classes.documents import DocumentProperty\nresult = client.documents.aggregate_unique_values(DocumentProperty.mime_type)\nunique_types = result.unique\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.documents import DocumentProperty\nis_abc = filters.Prefix(DocumentProperty.external_id, \"abc\")\nresult = client.documents.aggregate_unique_values(DocumentProperty.language, filter=is_abc)\nunique_languages = result.unique\n\nfrom cognite.client.data_classes.documents import DocumentProperty\nfrom cognite.client.data_classes import aggregations\nagg = aggregations\nis_not_text = agg.Not(agg.Prefix(\"text\"))\nresult = client.documents.aggregate_unique_values(DocumentProperty.mime_type, aggregate_filter=is_not_text)\nunique_mime_types = result.unique\n"
}
]
}
},
"/documents/list": {
"post": {
"tags": [
"Documents"
],
"summary": "List documents",
"description": "Retrieves a list of the documents in a project. You can use filters to narrow down the list.\nUnlike the search endpoint, the pagination isn't restricted to 1000 documents in total, meaning\nthis endpoint can be used to iterate through all the documents in your project.\n\nFor more information on how the filtering works, see the documentation for the search endpoint.",
"operationId": "documentsList",
"requestBody": {
"description": "Fields to be set for the list request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentListRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/DocumentListResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import filters\nfrom cognite.client.data_classes.documents import DocumentProperty\nis_pdf = filters.Equals(DocumentProperty.mime_type, \"application/pdf\")\npdf_documents = client.documents.list(filter=is_pdf)\n\nfrom cognite.client.data_classes.documents import DocumentProperty\nfor document in client.documents:\n print(document.name)\n"
}
]
}
},
"/documents/{id}/content": {
"get": {
"tags": [
"Documents"
],
"summary": "Retrieve document content",
"description": "Returns extracted textual information for the given document.\n\nThe documents pipeline extracts up to 1MiB of textual information from each processed document.\nThe search and list endpoints truncate the textual content of each document, in order to reduce the size\nof the returned payload. If you want the whole text for a document, you can use this endpoint.\n\nThe `accept` request header MUST be set to `text/plain`. Other values will\ngive an HTTP 406 error.",
"operationId": "documentsContent",
"parameters": [
{
"$ref": "#/components/parameters/CogniteInternalId"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"text/plain": {
"schema": {
"type": "string",
"description": "The textual content of the document, truncated to the first 1MB of text",
"example": "ACT I\nSCENE I. Elsinore. A platform before the castle.\n FRANCISCO at his post. Enter to him BERNARDO\nBERNARDO\n Who's there?\n"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "content = client.documents.retrieve_content(id=123)\nfrom pathlib import Path\nwith Path(\"my_file.txt\").open(\"wb\") as buffer:\n c.documents.retrieve_content_buffer(id=123, buffer=buffer)\n"
}
]
}
},
"/documents/{documentId}/preview/image/pages/{pageNumber}": {
"get": {
"tags": [
"Document preview"
],
"summary": "Retrieve a image preview of a page from a document",
"operationId": "documentsPreviewImagePage",
"description": "This endpoint returns a rendered image preview for a specific page of the specified document.\n\nThe `accept` request header MUST be set to `image/png`. Other values will\ngive an HTTP 406 error.\n\nThe rendered image will be downsampled to a maximum of 2400x2400 pixels.\nOnly PNG format is supported and only the first 10 pages can be rendered.\n\nPreviews will be rendered if neccessary during the request. Be prepared\nfor the request to take a few seconds to complete.",
"parameters": [
{
"in": "path",
"name": "documentId",
"schema": {
"type": "integer"
},
"required": true,
"description": "Internal ID for document to preview"
},
{
"in": "path",
"name": "pageNumber",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"required": true,
"description": "Page number to preview. Starting at 1 for first page"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"image/png": {
"schema": {
"description": "Rendered PNG image",
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
},
"401": {
"$ref": "#/components/responses/ErrorResponse"
},
"406": {
"$ref": "#/components/responses/ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "client.documents.previews.download_page_as_png(\"previews\", id=123, page_number=5)\ncontent = client.documents.previews.download_page_as_png_bytes(id=123, page_number=5)\n\nfrom IPython.display import Image\nbinary_png = client.documents.previews.download_page_as_png_bytes(id=123, page_number=5)\nImage(binary_png)\n"
}
]
}
},
"/documents/{documentId}/preview/pdf": {
"get": {
"tags": [
"Document preview"
],
"summary": "Retrieve a PDF preview of a document",
"operationId": "documentsPreviewPdf",
"description": "This endpoint returns a rendered PDF preview for a specified document.\n\nThe `accept` request header MUST be set to `application/pdf`. Other values will\ngive an HTTP 406 error.\n\nThis endpoint is optimized for in-browser previews. We reserve the right\nto adjust the quality and other attributes of the output with this in mind.\nPlease reach out to us if you have a different use case and requirements.\n\nOnly the 100 first pages will be included.\n\nPreviews will be rendered if neccessary during the request. Be prepared\nfor the request to take a few seconds to complete.",
"parameters": [
{
"$ref": "#/components/parameters/cdfversionheader"
},
{
"in": "path",
"name": "documentId",
"schema": {
"type": "integer"
},
"required": true,
"description": "Internal ID for document to preview"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/pdf": {
"schema": {
"description": "Rendered PDF document",
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
},
"401": {
"$ref": "#/components/responses/ErrorResponse"
},
"406": {
"$ref": "#/components/responses/ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "client.documents.previews.download_document_as_pdf(\"previews\", id=123)\ncontent = client.documents.previews.download_document_as_pdf_bytes(id=123)\n"
}
]
}
},
"/documents/{documentId}/preview/pdf/temporarylink": {
"get": {
"tags": [
"Document preview"
],
"summary": "Retrieve a temporary link to a PDF preview of a document",
"operationId": "documentsPreviewPdfTemporaryLink",
"description": "This endpoint works similar as the normal preview endpoint except\nit returns a short-lived temporary link to download the rendered preview instead\nof returning the binary data.",
"parameters": [
{
"$ref": "#/components/parameters/cdfversionheader"
},
{
"in": "path",
"name": "documentId",
"schema": {
"type": "integer"
},
"required": true,
"description": "Internal ID for document to preview"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DocumentsPreviewTemporaryLinkResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
},
"401": {
"$ref": "#/components/responses/ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "link = client.documents.previews.retrieve_pdf_link(id=123)\n"
}
]
}
},
"/geospatial/crs": {
"get": {
"tags": [
"Geospatial"
],
"summary": "List Coordinate Reference Systems",
"description": "List the defined Coordinate Reference Systems. The list can be limited to the custom Coordinate Reference Systems defined for the tenant.",
"operationId": "listGeospatialCoordinateReferenceSystems",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFilterOnlyCustom"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialCoordinateReferenceSystemResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialCrsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const allCRS = await client.geospatial.crs.list({ filterOnlyCustom : true });"
}
]
},
"post": {
"tags": [
"Geospatial"
],
"summary": "Create Coordinate Reference Systems",
"description": "Creates custom Coordinate Reference Systems.",
"operationId": "createGeospatialCoordinateReferenceSystems",
"requestBody": {
"description": "List of custom Coordinate Reference Systems to be created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialCustomCoordinateReferenceSystemSpecs"
},
"examples": {
"GeospatialCreateCoordinateReferenceSystemsExample": {
"$ref": "#/components/examples/GeospatialCreateCoordinateReferenceSystemsExample"
}
}
}
},
"required": true
},
"responses": {
"201": {
"$ref": "#/components/responses/GeospatialCustomCoordinateReferenceSystemResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialCrsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const crsToCreate = [{\n srid: 456789,\n wkt: 'GEOGCS[\\\"WGS 84\\\",DATUM[\\\"WGS_1984\\\",SPHEROID[\\\"WGS 84\\\",6378137,298.257223563,AUTHORITY[\\\"EPSG\\\",\\\"7030\\\"]],AUTHORITY[\\\"EPSG\\\",\\\"6326\\\"]],PRIMEM[\\\"Greenwich\\\",0,AUTHORITY[\\\"EPSG\\\",\\\"8901\\\"]],UNIT[\\\"degree\\\",0.0174532925199433,AUTHORITY[\\\"EPSG\\\",\\\"9122\\\"]],AUTHORITY[\\\"EPSG\\\",\\\"4326\\\"]]',\n projString: '+proj=longlat +datum=WGS84 +no_defs \\\"\\\"'\n }];\n\nconst createdCRS = await client.geospatial.crs.create(crsToCreate);"
}
]
}
},
"/geospatial/crs/byids": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Get Coordinate Reference Systems",
"description": "Get Coordinate Reference Systems by their Spatial Reference IDs",
"operationId": "getCoordinateReferenceSystem",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialReferenceIds"
},
"examples": {
"CoordinateReferenceSystemRequestExample": {
"$ref": "#/components/examples/GeospatialCoordinateReferenceSystemRequestExample"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialCoordinateReferenceSystemResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialCrsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const retrievedCRS = await client.geospatial.crs.retrieve([{ srid: 4326 }]);"
}
]
}
},
"/geospatial/crs/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete Coordinate Reference Systems",
"description": "Delete custom Coordinate Reference Systems.",
"operationId": "deleteGeospatialCoordinateReferenceSystems",
"requestBody": {
"description": "List of custom Coordinate Reference Systems to be deleted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialReferenceIds"
},
"examples": {
"CoordinateReferenceSystemRequestExample": {
"$ref": "#/components/examples/GeospatialCoordinateReferenceSystemRequestExample"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialCrsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.geospatial.crs.delete([{ srid: 4326}]);"
}
]
}
},
"/geospatial/featuretypes": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Create feature types",
"description": "Creates feature types. Each tenant can have up to 100 feature types.",
"operationId": "createFeatureTypes",
"requestBody": {
"description": "List of feature types to be created. It is possible to create up to 100 feature types in one request provided the total number of feature types on the tenant will not exceed 100.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureTypeSpecs"
},
"examples": {
"GeospatialFeatureTypesRequestExample": {
"$ref": "#/components/examples/GeospatialFeatureTypesRequestExample"
}
}
}
},
"required": true
},
"responses": {
"201": {
"$ref": "#/components/responses/GeospatialFeatureTypesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const featureTypes = [\n {\n externalId: 'ocean_temperature',\n properties: { temperature: { type: 'DOUBLE' as const }, location: { type: 'POINT' as const, srid: 4326 } } ,\n searchSpec: { location_idx: { properties : ['location'] } }\n }\n];\nconst createdFeatureTypes = await client.geospatial.featureType.create(featureTypes);"
}
]
}
},
"/geospatial/featuretypes/byids": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Retrieve feature types",
"description": "Retrieves feature types by external ids. It is possible to retrieve up to 100 items per request, i.e. the maximum number of feature types for a tenant.",
"operationId": "getFeatureTypesByIds",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureTypeExternalIds"
},
"examples": {
"ExternalIdsExample": {
"$ref": "#/components/examples/GeospatialFeatureTypeExternalIdsExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureTypesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const retrievedFeatureTypes = await client.geospatial.featureType.retrieve([ { externalId: 'ocean_temperature' } ]);"
}
]
}
},
"/geospatial/featuretypes/list": {
"post": {
"tags": [
"Geospatial"
],
"summary": "List feature types",
"description": "List all feature types",
"operationId": "listFeatureTypes",
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureTypesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const allFeatureTypes = await client.geospatial.featureType.list();"
}
]
}
},
"/geospatial/featuretypes/update": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Update feature types",
"description": "Update one or more feature types",
"operationId": "updateFeatureTypes",
"requestBody": {
"description": "List of feature types to be updated. It is possible to add and remove properties and indexes. WARNING: removing properties will result in data loss in corresponding features.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialUpdateFeatureTypeSpecs"
},
"examples": {
"GeospatialFeatureTypesUpdateRequestExample": {
"$ref": "#/components/examples/GeospatialFeatureTypesUpdateRequestExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureTypesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const featureTypesToUpdate = [\n {\n externalId: 'ocean_temperature',\n update: {\n properties: { add: { depth: { type: 'DOUBLE'} }, remove: ['temperature'] },\n searchSpec: { add: { depth_idx: { properties: ['depth'] } } }\n }\n }\n];\nconst updatedFeatureTypes = await client.geospatial.featureType.update(featureTypesToUpdate);"
}
]
}
},
"/geospatial/featuretypes/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete feature types",
"description": "Delete feature types.",
"operationId": "GeospatialDeleteFeatureTypes",
"requestBody": {
"description": "List of feature types to be deleted. It is possible to delete a maximum of 10 feature types per request. Feature types must not have related features. Feature types with related features can be deleted using force flag.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialDeleteFeatureType"
},
"examples": {
"ExternalIdsExample": {
"$ref": "#/components/examples/GeospatialFeatureTypeExternalIdsExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.geospatial.featureType.delete([{ externalId: 'ocean_temperature'}], { recursive : true });"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Create features",
"description": "Create features",
"operationId": "createFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureSpecs"
},
"examples": {
"GeospatialFeaturesRequestExample": {
"$ref": "#/components/examples/GeospatialFeaturesRequestExample"
}
}
}
},
"required": true
},
"responses": {
"201": {
"$ref": "#/components/responses/GeospatialFeaturesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const featureTypeExternalId = 'ocean_temperature';\nconst features = [\n { externalId: 'measurement_point_765', temperature: 5.65, location: { wkt: 'POINT(60.547602 -5.423433)' }},\n { externalId: 'measurement_point_863', temperature: 5.03, location: { wkt: 'POINT(60.585858 -6.474416)' }},\n];\nconst createdFeatures = await client.geospatial.feature.create(featureTypeExternalId, features);"
}
]
},
"get": {
"tags": [
"Geospatial"
],
"summary": "Get features",
"description": "Get features with paging support",
"operationId": "getFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"in": "query",
"name": "limit",
"schema": {
"$ref": "#/components/schemas/SearchLimit"
}
},
{
"in": "query",
"name": "allowCrsTransformation",
"schema": {
"$ref": "#/components/schemas/GeospatialAllowCrsTransformation"
}
},
{
"in": "query",
"name": "allowDimensionalityMismatch",
"schema": {
"$ref": "#/components/schemas/GeospatialAllowDimensionalityMismatch"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeaturesWithCursorResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/list": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Filter all features",
"description": "List features based on the feature property filter passed in the body of the request. This operation supports pagination by cursor.",
"operationId": "listFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureListRequest"
},
"examples": {
"GeospatialFeatureExternalIdsExample": {
"$ref": "#/components/examples/GeospatialListExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeaturesWithCursorResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const params = {\n filter: {\n and: [\n { range:{ property: 'temperature', gt:4.54 } },\n { stWithin: { property:'location', value:'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))' } }\n ]\n },\n};\n\nconst allFeaturesList = await client.geospatial.feature.list('ocean_temperature', params);"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/byids": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Retrieve features",
"description": "Retrieves features by external ids. It is possible to retrieve up to 1000 items per request.",
"operationId": "getFeaturesByIds",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureIdsWithOutput"
},
"examples": {
"GeospatialFeatureExternalIdsExample": {
"$ref": "#/components/examples/GeospatialFeatureExternalIdsExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeaturesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const featuresToRetrieve = [{ externalId: 'measurement_point_765' }, { externalId: 'measurement_point_765' }];\nconst outputParams = { output: { geometryFormat: 'GEOJSON' as const } };\n\nconst retrievedFeatures = await client.geospatial.feature.retrieve('ocean_temperature', featuresToRetrieve, outputParams);"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/update": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Update features",
"description": "Update features. This is a replace operation, i.e., all feature properties have to be sent in the request body even if their values do not change.",
"operationId": "updateFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"description": "List of features to update.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureSpecs"
},
"examples": {
"GeospatialFeaturesRequestExample": {
"$ref": "#/components/examples/GeospatialFeaturesRequestExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeaturesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const featuresToDelete = [{ externalId: 'measurement_point_765' }, { externalId: 'measurement_point_765' }];\n\nawait client.geospatial.feature.delete('ocean_temperature', featuresToDelete);\n\nconst featuresToUpdate = [\n{ externalId: 'measurement_point_765', temperature: 5.65, location: { wkt: 'POINT(60.547602 -5.423433)' } },\n{ externalId: 'measurement_point_863', temperature: 5.03, location: { wkt: 'POINT(60.585858 -6.474416)' } }\n];\n\nconst updatedFeatures = await client.geospatial.feature.update('ocean_temperature', featuresToUpdate);"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete features",
"description": "Delete features.",
"operationId": "deleteFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"description": "List of features to be deleted. It is possible to post a maximum of 1000 items per request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureIds"
},
"examples": {
"GeospatialFeatureExternalIdsExample": {
"$ref": "#/components/examples/GeospatialFeatureExternalIdsExample"
}
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialAcl:WRITE"
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/search": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Search features",
"description": "Search for features based on the feature property filter passed in the body of the request. The result of the search is limited to a maximum of 1000 items. Results in excess of the limit are truncated. This means that the complete result set of the search cannot be retrieved with this method. However, for a given unmodified feature collection, the result of the search is deterministic and does not change over time.",
"operationId": "searchFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureSearchRequest"
},
"examples": {
"GeospatialSearchExample": {
"$ref": "#/components/examples/GeospatialSearchExample"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureSearchResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const params = {\n filter: {\n and: [\n { range:{ property: 'temperature', gt:4.54 } },\n { stWithin: { property:'location', value:'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))' } }\n ]\n },\n limit: 100,\n sort: [ 'temperature:ASC','location']\n};\n\nconst searchedFeatures = await client.geospatial.feature.search('ocean_temperature', params);"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Search and stream features",
"description": "Search for features based on the feature property filter passed in the body of the request. The streaming response format can be length prefixed, new line delimited, record separator delimited or concatenated depending on requested output (see https://en.wikipedia.org/wiki/JSON_streaming).",
"operationId": "searchFeaturesStreaming",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureSearchStreamingRequest"
},
"examples": {
"GeospatialSearchStreamingExample": {
"$ref": "#/components/examples/GeospatialSearchStreamingExample"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureSearchStreamingResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const params = {\n filter: {\n and: [\n { range:{ property: 'temperature', gt:4.54 } },\n { stWithin: { property:'location', value:'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))' } }\n ]\n },\n limit: 100,\n output: { jsonStreamFormat: 'NEW_LINE_DELIMITED' as const }\n};\n\nconst featureStreamString = await client.geospatial.feature.searchStream('ocean_temperature', params);"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/aggregate": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Aggregate features",
"description": "Search for features based on the feature property filter and perform requested aggregations on a given property. Aggregations are supported for all filters that do not contain `stWithin`, `stWithinProperly`, `stContains` and `stContainsProperly` search in 3D geometries.",
"operationId": "aggregateFeatures",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialFeatureAggregateRequest"
},
"examples": {
"FeatureAggregateExample": {
"$ref": "#/components/examples/GeospatialFeatureAggregateExample"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureAggregateResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const aggregateParams = {\n filter: {\n and: [\n { range:{ property: 'temperature', gt:4.54 } },\n { stWithin: { property:'location', value:'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))' } }\n ]\n },\n property: 'temperature',\n aggregates: ['min', 'max', 'average'],\n groupBy: ['category']\n};\n\nconst featureStream = await client.geospatial.feature.searchStream('ocean_temperature', aggregateParams);"
}
]
}
},
"/geospatial/compute": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Compute",
"description": "Compute custom json output structures or well known binary format responses based on calculation or selection of feature properties or direct values given in the request.",
"operationId": "compute",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialComputeRequest"
},
"examples": {
"StTransformGeometryExample": {
"$ref": "#/components/examples/GeospatialComputeRequestExample"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialComputeResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialCrsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const response = await client.geospatial.compute.compute({\n output: {\n \"output\": {\n stTransform: {\n geometry: {\n ewkt: \"SRID=4326;POLYGON((0 0,10 0,10 10,0 10,0 0))\"\n },\n srid: 4326,\n }\n }\n }\n});"
}
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/{featureExternalId}/rasters/{rasterPropertyName}": {
"put": {
"tags": [
"Geospatial"
],
"summary": "Put a raster into a feature property",
"description": "Put a raster into a feature property. The feature property must be of type RASTER.",
"operationId": "putRaster",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
},
{
"$ref": "#/components/parameters/geospatialFeatureExternalId"
},
{
"$ref": "#/components/parameters/geospatialRasterPropertyName"
},
{
"$ref": "#/components/parameters/geospatialRasterSrid"
},
{
"$ref": "#/components/parameters/geospatialRasterInputFormat"
},
{
"$ref": "#/components/parameters/geospatialRasterPixelScaleX"
},
{
"$ref": "#/components/parameters/geospatialRasterPixelScaleY"
},
{
"$ref": "#/components/parameters/geospatialRasterAllowCrsTransformation"
}
],
"requestBody": {
"content": {
"application/octet-stream": {
"schema": {
"format": "binary"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialRasterMetadataResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialAcl:WRITE"
]
},
"post": {
"tags": [
"Geospatial"
],
"summary": "Get a raster from a feature property",
"description": "Get a raster from a feature property. The feature property must be of type RASTER.",
"operationId": "getRaster",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
},
{
"$ref": "#/components/parameters/geospatialFeatureExternalId"
},
{
"$ref": "#/components/parameters/geospatialRasterPropertyName"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeospatialRasterOutputSpec"
}
}
}
},
"responses": {
"200": {
"description": "The binary file of the raster in the specified format",
"content": {
"application/octet-stream": {
"schema": {
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
]
}
},
"/geospatial/featuretypes/{featureTypeExternalId}/features/{featureExternalId}/rasters/{rasterPropertyName}/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete a raster from a feature property",
"description": "Delete a raster from a feature property. If there is no raster already, the operation is a no-op.",
"operationId": "deleteRaster",
"parameters": [
{
"$ref": "#/components/parameters/geospatialFeatureTypeExternalId"
},
{
"$ref": "#/components/parameters/geospatialFeatureExternalId"
},
{
"$ref": "#/components/parameters/geospatialRasterPropertyName"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ",
"geospatialAcl:WRITE"
]
}
},
"/reportdeletion": {},
"/reportdeletion/pending": {},
"/sessions/batchrefresh": {},
"/sessions/token": {},
"/sessions/detach": {},
"/sessions": {
"get": {
"x-capability": "sessionsAcl:LIST",
"tags": [
"Sessions"
],
"operationId": "listSessions",
"summary": "List sessions",
"description": "List all sessions in the current project.",
"parameters": [
{
"in": "query",
"name": "status",
"description": "If given, only sessions with the given status are returned.\n",
"schema": {
"type": "string",
"enum": [
"ready",
"active",
"cancelled",
"revoked",
"access_lost"
]
}
},
{
"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 sessions in the current project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionList"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
},
"post": {
"x-capability": "sessionsAcl:CREATE",
"tags": [
"Sessions"
],
"operationId": "createSessions",
"summary": "Create sessions",
"description": "Create sessions",
"requestBody": {
"description": "A request containing the information needed to create a session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSessionRequestList"
}
}
}
},
"responses": {
"200": {
"description": "List of session creation related information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSessionResponseList"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/sessions/byids": {
"post": {
"x-capability": "sessionsAcl:LIST",
"tags": [
"Sessions"
],
"operationId": "getSessionsByIds",
"summary": "Retrieve sessions with given IDs",
"description": "Retrieves sessions with given IDs. The request will fail if any of the IDs does not belong to an existing session.",
"requestBody": {
"description": "List of session IDs to retrieve",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionReferenceIds"
}
}
}
},
"responses": {
"200": {
"description": "A list of sessions with the given ids",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionByIds"
},
"example": {
"items": [
{
"id": 105049194919491,
"type": "TOKEN_EXCHANGE",
"status": "ACTIVE",
"creationTime": 1638795559528,
"expirationTime": 1638795559628
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/sessions/revoke": {
"post": {
"x-capability": "sessionsAcl:DELETE",
"tags": [
"Sessions"
],
"operationId": "revokeSessions",
"summary": "Revoke sessions",
"description": "Revoke access to a session.\nRevocation of a session may in some cases take up to 1 hour to take effect.\n",
"requestBody": {
"description": "A request containing the information needed to revoke sessions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeSessionRequestList"
}
}
}
},
"responses": {
"200": {
"description": "List of revoked sessions.\nIf the user does not have the `sessionsAcl:LIST` capability, then only the session IDs will be present in the response.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionList"
},
"example": {
"items": [
{
"id": 0,
"type": "CLIENT_CREDENTIALS",
"status": "REVOKED",
"creationTime": 1638795554528,
"expirationTime": 1638795554528,
"clientId": "client-123"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/extpipes": {
"get": {
"tags": [
"Extraction Pipelines"
],
"summary": "List extraction pipelines",
"description": "Returns a list of all extraction pipelines for a given project",
"operationId": "listExtPipes",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Response with the list of extraction pipelines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipesWithCursor"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "ep_list = client.extraction_pipelines.list(limit=5)\n"
}
]
},
"post": {
"tags": [
"Extraction Pipelines"
],
"summary": "Create extraction pipelines",
"description": "Creates multiple new extraction pipelines. A maximum of 1000 extraction pipelines can be created per request.",
"operationId": "createExtPipes",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsRequest_CreateExtPipe_"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with the list of extraction pipelines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipesWithCursor"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:WRITE",
"datasetsAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import ExtractionPipeline\nextpipes = [ExtractionPipeline(name=\"extPipe1\",...), ExtractionPipeline(name=\"extPipe2\",...)]\nres = client.extraction_pipelines.create(extpipes)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<ExtractionPipeline> upsertPipelinesList = List.of(ExtractionPipeline.newBuilder() \n .setExternalId(\"10\") \n .setName(\"generated-\") \n .setDescription(\"Generated description\") \n .setDataSetId(dataSetId) \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .addContacts(ExtractionPipeline.Contact.newBuilder() \n .setName(\"generated-\") \n .setRole(\"generated\") \n .build()) \n .build()); \n\nclient.extractionPipelines().upsert(upsertPipelinesList); \n\n"
}
]
}
},
"/extpipes/delete": {
"post": {
"tags": [
"Extraction Pipelines"
],
"summary": "Delete extraction pipelines",
"description": "Delete extraction pipelines for given list of ids and externalIds. When the extraction pipeline is deleted, all extraction pipeline runs related to the extraction pipeline are automatically deleted.",
"operationId": "deleteExtPipes",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendedItemsRequest_ExtPipeId_"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:WRITE",
"datasetsAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "client.extraction_pipelines.delete(id=[1,2,3], external_id=\"3\")\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> deleteByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList<Item> deleteItemsResults = \n client.extractionPipelines().delete(deleteByExternalIds); \n\nList<Item> deleteByInternalIds = List.of(Item.newBuilder()\n .setId(10) \n .build()); \nList<Item> deleteItemsResults = \n client.extractionPipelines().delete(deleteByInternalIds); \n\n"
}
]
}
},
"/extpipes/update": {
"post": {
"tags": [
"Extraction Pipelines"
],
"summary": "Update extraction pipelines",
"description": "Update information for a list of extraction pipelines. Fields that are not included in the request, are not changed.",
"operationId": "updateExtPipes",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsRequest_ExtPipeUpdate_"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with the list of updated extraction pipelines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipes"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:WRITE",
"datasetsAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "update = ExtractionPipelineUpdate(id=1)\nupdate.description.set(\"Another new extpipe\")\nres = client.extraction_pipelines.update(update)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<ExtractionPipeline> upsertPipelinesList = //list of ExtractionPipeline \nclient.extractionPipelines().upsert(upsertPipelinesList); \n\n"
}
]
}
},
"/extpipes/{id}": {
"get": {
"tags": [
"Extraction Pipelines"
],
"summary": "Retrieve an extraction pipeline by its ID.",
"description": "Retrieve an extraction pipeline by its ID. If you want to retrieve extraction pipelines by externalIds, use Retrieve extraction pipelines instead.",
"operationId": "showExtPipe",
"parameters": [
{
"$ref": "#/components/parameters/CogniteInternalId"
}
],
"responses": {
"200": {
"description": "Single extraction pipeline response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipe"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.extraction_pipelines.retrieve(id=1)\n\nres = client.extraction_pipelines.retrieve(external_id=\"1\")\n"
}
]
}
},
"/extpipes/byids": {
"post": {
"tags": [
"Extraction Pipelines"
],
"summary": "Retrieve extraction pipelines",
"description": "Retrieves information about multiple extraction pipelines in the same project. All ids and externalIds must be unique.",
"operationId": "byidsExtPipes",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendedItemsRequest_ExtPipeId_"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with the list of extraction pipelines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipes"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.extraction_pipelines.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.extraction_pipelines.retrieve_multiple(external_ids=[\"abc\", \"def\"], ignore_unknown_ids=True)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> itemsByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nList<ExtractionPipeline> retrievedEvents = \n client.extractionPipelines().retrieve(itemsByExternalIds);//by list of items \nList<ExtractionPipeline> retrievedEvents = \n client.extractionPipelines().retrieve(\"10\");//by varargs of String \n\nList<Item> itemsByInternalIds = List.of(Item.newBuilder() \n .setId(10) \n .build()); \nList<ExtractionPipeline> retrievedEvents = \n client.extractionPipelines().retrieve(itemsByInternalIds); \n List<ExtractionPipeline> retrievedEvents = \n client.extractionPipelines().retrieve(10);//by varargs of Long \n\n"
}
]
}
},
"/extpipes/list": {
"post": {
"tags": [
"Extraction Pipelines"
],
"summary": "Filter extraction pipelines",
"description": "Use advanced filtering options to find extraction pipelines.",
"operationId": "filterExtPipes",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipesFilterRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with the list of extraction pipelines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtPipes"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionpipelinesAcl:READ"
],
"x-code-samples": [
{
"lang": "Java",
"label": "Java SDK",
"source": "List<ExtractionPipeline> listPipelinesResults = new ArrayList<>(); \nclient.extractionPipelines() \n .list(Request.create() \n .withFilterParameter(\"source\", \"source\")) \n .forEachRemaining(events -> listPipelinesResults.addAll(events)); \n\n"
}
]
}
},
"/extpipes/config": {
"get": {
"tags": [
"Extraction Pipelines Config"
],
"summary": "Get a single configuration revision",
"description": "Retrieves a single configuration revision. By default, the latest revision is retrieved.",
"operationId": "getExtPipeConfigRevision",
"parameters": [
{
"name": "externalId",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "revision",
"in": "query",
"required": false,
"schema": {
"minimum": 0,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "activeAtTime",
"in": "query",
"required": false,
"schema": {
"minimum": 0,
"type": "integer",
"format": "int64",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Response with the retrieved configuration revision",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfigResponse"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionconfigsAcl:READ"
]
},
"post": {
"tags": [
"Extraction Pipelines Config"
],
"summary": "Create extraction configuration revision",
"description": "Creates a configuration revision for the given extraction pipeline.",
"operationId": "createExtPipeConfig",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateConfigRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with the created configuration revision",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfigResponse"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionconfigsAcl:WRITE"
]
}
},
"/extpipes/config/revisions": {
"get": {
"tags": [
"Extraction Pipelines Config"
],
"summary": "List configuration revisions",
"description": "Lists configuration revisions for the given extraction pipeline.",
"operationId": "listExtPipeConfigRevisions",
"parameters": [
{
"name": "externalId",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Response with the retrieved configuration revisions and an optional cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsResponse_ListConfigResponse_"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionconfigsAcl:READ"
]
}
},
"/extpipes/config/revert": {
"post": {
"tags": [
"Extraction Pipelines Config"
],
"summary": "Revert configuration revision",
"description": "Reverts the latest configuration revision to an older revision. Equivalent to creating a new revision identical to the old revision.",
"operationId": "revertExtPipeConfigRevision",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevertConfigRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with the new latest configuration revision",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfigResponse"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionconfigsAcl:WRITE"
]
}
},
"/extpipes/runs": {
"get": {
"tags": [
"Extraction Pipelines Runs"
],
"summary": "List extraction pipeline runs",
"description": "List of all extraction pipeline runs for a given extraction pipeline. Sorted by createdTime value with descendant order.",
"operationId": "runs",
"parameters": [
{
"name": "externalId",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "Response with list of extraction pipeline runs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsResponse_ExtPipeRunResponse_"
}
}
}
}
},
"x-capability": [
"extractionrunsAcl:READ"
]
},
"post": {
"tags": [
"Extraction Pipelines Runs"
],
"summary": "Create extraction pipeline runs",
"description": "Create multiple extraction pipeline runs. Current version supports one extraction pipeline run per request. Extraction pipeline runs support three statuses: success, failure, seen. The content of the Error Message parameter is configurable and will contain any messages that have been configured within the extraction pipeline.",
"operationId": "createRuns",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsRequest_ExtPipeRunRequest_"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of extraction pipeline runs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsResponse_CreateExtPipeRunResponse_"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionrunsAcl:WRITE",
"datasetsAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import ExtractionPipelineRun\nres = client.extraction_pipelines.runs.create(\n ExtractionPipelineRun(status=\"success\", extpipe_external_id=\"extId\"))\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<ExtractionPipeline> listPipelinesResults = //list of ExtractionPipeline; \nList<ExtractionPipelineRun> upsertPipelineRunsList = \n List.of(ExtractionPipelineRun.newBuilder() \n .setExternalId(listPipelinesResults.get(0).getExternalId()) \n .setCreatedTime(Instant.now().toEpochMilli()) \n .setMessage(\"generated-\") \n .setStatus(ExtractionPipelineRun.Status.SUCCESS) \n .build()); \n\n client.extractionPipelines().runs().create(upsertPipelineRunsList); \n\n"
}
]
}
},
"/extpipes/runs/list": {
"post": {
"tags": [
"Extraction Pipelines Runs"
],
"summary": "Filter extraction pipeline runs",
"description": "Use advanced filtering options to find extraction pipeline runs. Sorted by createdTime value with descendant order.",
"operationId": "filterRuns",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsFilterRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of extraction pipeline runs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsResponse_ExtPipeRunResponse_"
}
}
}
},
"400": {
"description": "Response for a failed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultError"
}
}
}
}
},
"x-capability": [
"extractionrunsAcl:READ"
],
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "runsList = client.extraction_pipelines.runs.list(external_id=\"test ext id\", limit=5)\n\nrunsList = client.extraction_pipelines.runs.list(external_id=\"test ext id\", statuses=[\"seen\"], statuslimit=5)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<ExtractionPipelineRun> listPipelinesRunsResults = new ArrayList<>(); \nclient.extractionPipelines() \n .runs() \n .list() \n .forEachRemaining(run -> listPipelinesRunsResults.addAll(run)); \n\nclient.extractionPipelines() \n .runs() \n .list(Request.create().withFilterParameter(\"statuses\", \"success\")) \n .forEachRemaining(run -> listPipelinesRunsResults.addAll(run)); \n\n"
}
]
}
},
"/transformations": {
"get": {
"tags": [
"Transformations"
],
"summary": "List transformations",
"description": "List transformations. Use nextCursor to paginate through the results.",
"operationId": "getTransformations",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Limits the number of results to be returned. The maximum is 1000, default limit is 100.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 1000
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor for paging through results.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "includePublic",
"in": "query",
"description": "Whether public transformations should be included in the results. The default is true.",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "withJobDetails",
"in": "query",
"description": "Whether transformations should contain information about jobs. The default is true.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Paged response with list of transformations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_TransformationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "transformations_list = client.transformations.list()\n"
}
]
},
"post": {
"tags": [
"Transformations"
],
"summary": "Create transformations",
"description": "Create a maximum of 1000 transformations per request.",
"operationId": "createTransformations",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_TransformationCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of transformations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_TransformationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import Transformation, TransformationDestination\nfrom cognite.client.data_classes.transformations.common import ViewInfo, EdgeType, DataModelInfo\ntransformations = [\n Transformation(\n name=\"transformation1\",\n destination=TransformationDestination.assets()\n ),\n Transformation(\n name=\"transformation2\",\n destination=TransformationDestination.raw(\"myDatabase\", \"myTable\")\n ),\n Transformation(\n name=\"transformation3\",\n view = ViewInfo(space=\"TypeSpace\", external_id=\"TypeExtId\", version=\"version\"),\n destination=TransformationDestination.nodes(view, \"InstanceSpace\")\n ),\n Transformation(\n name=\"transformation4\",\n view = ViewInfo(space=\"TypeSpace\", external_id=\"TypeExtId\", version=\"version\"),\n destination=TransformationDestination.edges(view, \"InstanceSpace\")\n ),\n Transformation(\n name=\"transformation5\",\n edge_type = EdgeType(space=\"TypeSpace\", external_id=\"TypeExtId\"),\n destination=TransformationDestination.edges(edge_type,\"InstanceSpace\")\n ),\n Transformation(\n name=\"transformation6\",\n data_model = DataModelInfo(space=\"modelSpace\", external_id=\"modelExternalId\",version=\"modelVersion\",destination_type=\"viewExternalId\"),\n destination=TransformationDestination.instances(data_model,\"InstanceSpace\")\n ),\n Transformation(\n name=\"transformation7\",\n data_model = DataModelInfo(space=\"modelSpace\", external_id=\"modelExternalId\",version=\"modelVersion\",destination_type=\"viewExternalId\", destination_relationship_from_type=\"connectionPropertyName\"),\n destination=TransformationDestination.instances(data_model,\"InstanceSpace\")\n ),\n]\nres = client.transformations.create(transformations)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Transformation.Builder builder = Transformation.newBuilder() \n .setName(\"TransformationTestSDK-\") \n .setQuery(\"select * from teste\") \n .setConflictMode(\"upsert\") \n .setIsPublic(true) \n .setExternalId(\"TestSKD-\") \n .setIgnoreNullFields(true) \n .setDataSetId(dataSetId) \n .setDestination(Transformation.Destination.newBuilder() \n .setType(\"raw\") \n .setDatabase(\"Test\") \n .setTable(\"Test\") \n .build() \n ); \nList<Transformation> createdList = client.transformations().upsert(List.of(builder.build())); \n\n"
}
]
}
},
"/transformations/byids": {
"post": {
"tags": [
"Transformations"
],
"summary": "Retrieve transformations",
"description": "Retrieve a maximum of 1000 transformations by ids and externalIds per request.",
"operationId": "getTransformationsByIds",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithByIdsFlags_CogniteId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of transformations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_TransformationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.transformations.retrieve(id=1)\n\nres = client.transformations.retrieve(external_id=\"1\")\nres = client.transformations.retrieve_multiple(ids=[1,2,3], external_ids=['transform-1','transform-2'])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> byExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \nclient.transformations().retrieve(byExternalIds);"
}
]
}
},
"/transformations/filter": {
"post": {
"tags": [
"Transformations"
],
"summary": "Filter transformations",
"description": "Filter transformations. Use nextCursor to paginate through the results.",
"operationId": "filterTransformations",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TransformationAdvancedList"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Paged response with list of transformations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_TransformationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Transformation> listTransformationResults = new ArrayList<>(); \nclient.transformations()\n .list(Request.create().withFilterParameter(\"isPublic\", true))\n .forEachRemaining(listTransformationResults::addAll); \n\n"
}
]
}
},
"/transformations/delete": {
"post": {
"tags": [
"Transformations"
],
"summary": "Delete transformations",
"description": "Delete a maximum of 1000 transformations by ids and externalIds per request.",
"operationId": "deleteTransformations",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_CogniteId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Empty response.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "client.transformations.delete(id=[1,2,3], external_id=\"function3\")\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> deleteByExternalIds = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build()); \n\nList<Item> deleteItemsResults = client.transformations().delete(deleteByExternalIds);\n\n"
}
]
}
},
"/transformations/update": {
"post": {
"tags": [
"Transformations"
],
"summary": "Update transformations",
"description": "Update the attributes of transformations, maximum 1000 per request.",
"operationId": "updateTransformations",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_UpdateItem_TransformationUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of transformations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_TransformationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "transformation = client.transformations.retrieve(id=1)\ntransformation.query = \"SELECT * FROM _cdf.assets\"\nres = client.transformations.update(transformation)\n\nfrom cognite.client.data_classes import TransformationUpdate\nmy_update = TransformationUpdate(id=1).query.set(\"SELECT * FROM _cdf.assets\").is_public.set(False)\nres = client.transformations.update(my_update)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Transformation> editedInput = // List of Transformations \nList<Transformation> updatedList = client.transformations().upsert(editedInput);\n\n"
}
]
}
},
"/transformations/run": {
"post": {
"tags": [
"Transformations"
],
"summary": "Run a transformation",
"operationId": "runTransformation",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationRunWithExternalId"
},
{
"$ref": "#/components/schemas/TransformationRunWithId"
}
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with a single job.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.transformations.run(transformation_id = 1)\n\nres = client.transformations.run(transformation_id = 1, wait = False)\nimport asyncio\nasync def run_transformation():\n res = await c.transformations.run_async(id = 1)\nloop = asyncio.get_event_loop()\nloop.run_until_complete(run_transformation())\nloop.close()\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Transformation.Job jobRead = \n client.transformations().jobs().run(10L);"
}
]
}
},
"/transformations/jobs": {
"get": {
"tags": [
"Transformation Jobs"
],
"summary": "List jobs",
"operationId": "getTransformationJobs",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "transformationId",
"in": "query",
"description": "List only jobs for the specified transformation. The transformation is identified by ID.",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "transformationExternalId",
"in": "query",
"description": "List only jobs for the specified transformation. The transformation is identified by external ID.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Limits the number of results to be returned. The maximum is 1000, default limit is 100.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 1000
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor for paging through results.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Response with list of jobs.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_JobRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "transformation_jobs_list = client.transformations.jobs.list()\n\ntransformation_jobs_list = client.transformations.jobs.list(transformation_id = 1)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Iterator<List<Transformation.Job>> listJobs = \n client.transformations().jobs().list(); \n\n client. \n transformations() \n .jobs() \n .list(Request.create() \n .withRootParameter(\"transformationId\", 10)); \n\n client \n .transformations() \n .jobs() \n .list(Request.create() \n .withRootParameter(\"transformationExternalId\", 10)); \n\n"
}
]
}
},
"/transformations/jobs/byids": {
"post": {
"tags": [
"Transformation Jobs"
],
"summary": "Retrieve jobs by ids",
"description": "Retrieve a maximum of 1000 jobs by ids per request.",
"operationId": "getTransformationJobsByIds",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_CogniteInternalId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of jobs.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_JobRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.transformations.jobs.retrieve(id=1)\nres = client.transformations.jobs.retrieve_multiple(ids=[1, 2, 3])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> retrieveItems = new ArrayList<>(); \nretrieveItems.add(Item.newBuilder() \n .setId(10) \n .build()); \nList<Transformation.Job> retrievedItems = \n client.transformations().jobs().retrieve(retrieveItems); \n\n"
}
]
}
},
"/transformations/jobs/{id}/metrics": {
"get": {
"tags": [
"Transformation Jobs"
],
"summary": "List job metrics by job id",
"operationId": "getTransformationJobsMetrics",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"description": "The job id.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Metrics for how many resources has been read/written by the transformation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_MetricCounter"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.transformations.jobs.list_metrics(id=1)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Iterator<List<Transformation.Job.Metric>> it = \n client.transformations().jobs().metrics().list(10); \n\n"
}
]
}
},
"/transformations/cancel": {
"post": {
"tags": [
"Transformations"
],
"summary": "Cancel a transformation",
"operationId": "postApiV1ProjectsProjectTransformationsCancel",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Empty response.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import TransformationJobStatus\nres = client.transformations.run(id = 1, timeout = 60.0)\nif res.status == TransformationJobStatus.RUNNING:\n res.cancel()\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Boolean jobResult1 = \n client.transformations().jobs().cancel(10L);"
}
]
}
},
"/transformations/schedules": {
"get": {
"tags": [
"Transformation Schedules"
],
"summary": "List all schedules",
"description": "List all transformation schedules. Use nextCursor to paginate through the results.",
"operationId": "getTransformationSchedules",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Limits the number of results to be returned. The maximum is 1000, default limit is 100.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 1000
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor for paging through results.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "includePublic",
"in": "query",
"description": "Whether public transformations should be included in the results. The default is true.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Response with list of schedules.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_Schedule"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "schedules_list = client.transformations.schedules.list()\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Iterator<List<Transformation.Schedule>> it = \n client.transformations().schedules().list();\n\n"
}
]
},
"post": {
"tags": [
"Transformation Schedules"
],
"summary": "Schedule transformations",
"description": "Schedule transformations with the specified configurations.",
"operationId": "createTransformationSchedules",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "List of the schedules to create. Must be up to a maximum of 1000 items.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_ScheduleParameters"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Response with list of schedules.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Schedule"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import TransformationSchedule\nschedules = [TransformationSchedule(id = 1, interval = \"0 * * * *\"), TransformationSchedule(external_id=\"transformation2\", interval = \"5 * * * *\"))]\nres = client.transformations.schedules.create(schedules)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Transformation.Schedule> objects = new ArrayList<>(); \nobjects.add(Transformation.Schedule.newBuilder() \n .setExternalId(\"10\") \n .setInterval(\"*/5 * * * *\") \n .setIsPaused(false) \n .build());\nList<Transformation.Schedule> createdListSchedules = \n client.transformations().schedules().schedule(objects);\n\n"
}
]
}
},
"/transformations/schedules/byids": {
"post": {
"tags": [
"Transformation Schedules"
],
"summary": "Retrieve schedules",
"description": "Retrieve transformation schedules by transformation IDs or external IDs.",
"operationId": "getTransformationSchedulesByIds",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "List of transformation IDs of schedules to retrieve. Must be up to a maximum of 1000 items and all of them must be unique.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_CogniteId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of schedules.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Schedule"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.transformations.schedules.retrieve(id=1)\n\nres = client.transformations.schedules.retrieve(external_id=\"1\")\nres = client.transformations.schedules.retrieve_multiple(ids=[1, 2, 3])\n\nres = client.transformations.schedules.retrieve_multiple(external_ids=[\"t1\", \"t2\"])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> itemsToRetrieve = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build());\nList<Transformation.Schedule> retrievedItems = \n client.transformations().schedules().retrieve(itemsToRetrieve);\n\n"
}
]
}
},
"/transformations/schedules/delete": {
"post": {
"tags": [
"Transformation Schedules"
],
"summary": "Unschedule transformations",
"description": "Unschedule transformations by IDs or externalIds.",
"operationId": "deleteTransformationSchedules",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "List of transformation IDs of schedules to delete. Must be up to a maximum of 1000 items and all of them must be unique.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_CogniteId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Empty response.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "client.transformations.schedules.delete(id=[1,2,3], external_id=\"3\")\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> deleteSchedule = List.of(Item.newBuilder() \n .setExternalId(\"10\") \n .build());\nBoolean isUnSchedule = \n client.transformations().schedules().unSchedule(deleteSchedule);\n\n"
}
]
}
},
"/transformations/schedules/update": {
"post": {
"tags": [
"Transformation Schedules"
],
"summary": "Update schedules",
"operationId": "updateTransformationSchedules",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "List of schedule updates. Must be up to a maximum of 1000 items.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_UpdateItem_ScheduleUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of schedules.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Schedule"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "transformation_schedule = client.transformations.schedules.retrieve(id=1)\ntransformation_schedule.is_paused = True\nres = client.transformations.schedules.update(transformation_schedule)\n\nfrom cognite.client.data_classes import TransformationScheduleUpdate\nmy_update = TransformationScheduleUpdate(id=1).interval.set(\"0 * * * *\").is_paused.set(False)\nres = client.transformations.schedules.update(my_update)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Transformation.Schedule> editedInput = List.of(Transformation.Schedule.newBuilder() \n .setExternalId(\"10\") \n .setIsPaused(true) \n .setInterval(\"*/10 * * * *\") \n .build());\nList<Transformation.Schedule> updatedList = \n client.transformations().schedules().schedule(editedInput);\n\n"
}
]
}
},
"/transformations/notifications": {
"get": {
"tags": [
"Transformation Notifications"
],
"summary": "List notification subscriptions",
"operationId": "getTransformationNotifications",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "transformationId",
"in": "query",
"description": "List only notifications for the specified transformation. The transformation is identified by ID.",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "transformationExternalId",
"in": "query",
"description": "List only notifications for the specified transformation. The transformation is identified by external ID.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "destination",
"in": "query",
"description": "Filter by notification destination.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Limits the number of results to be returned. The maximum is 1000, default limit is 100.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 1000
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor for paging through results.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Response with paged list of notification subscriptions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_NotificationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "notifications_list = client.transformations.notifications.list()\n\nnotifications_list = client.transformations.notifications.list(transformation_id = 1)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Iterator<List<Transformation.Notification>> itNotifications = \n client.transformations().notifications().list();\n\n"
}
]
},
"post": {
"tags": [
"Transformation Notifications"
],
"summary": "Subscribe for notifications",
"description": "Subscribe for notifications on the transformation errors.",
"operationId": "createTransformationNotifications",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "List of the notifications for new subscriptions. Must be up to a maximum of 1000 items.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_NotificationCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with list of created notification subscriptions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_NotificationRead"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import TransformationNotification\nnotifications = [TransformationNotification(transformation_id = 1, destination=\"my@email.com\"), TransformationNotification(transformation_external_id=\"transformation2\", destination=\"other@email.com\"))]\nres = client.transformations.notifications.create(notifications)\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Transformation.Notification.Subscription> subscribes = \n List.of(Transformation.Notification.Subscription.newBuilder() \n .setDestination(\"test@test.com\") \n .setTransformationId(10) \n .build());\nList<Transformation.Notification> createdSubscribes = \n client.transformations().notifications().subscribe(subscribes);\n\n"
}
]
}
},
"/transformations/notifications/delete": {
"post": {
"tags": [
"Transformation Notifications"
],
"summary": "Delete notification subscriptions by notification ID",
"description": "Deletes the specified notification subscriptions on the transformation. Requests to delete non-existing subscriptions do nothing, but do not throw an error.",
"operationId": "deleteTransformationNotifications",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "List of IDs to be deleted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_CogniteInternalId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Empty response.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"409": {
"description": "The response for a conflict.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:WRITE",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "client.transformations.notifications.delete(id=[1,2,3])\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "List<Item> deleteNotification = List.of(Item.newBuilder() \n .setId(10) \n .build());\nList<Item> deletedItems = \n client.transformations().notifications().delete(deleteNotification);\n\n"
}
]
}
},
"/transformations/schema/sequence_rows": {
"get": {
"tags": [
"Schema"
],
"summary": "Get the schema of a sequence",
"operationId": "getTransformationSequenceRowSchema",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "externalId",
"in": "query",
"description": "External ID of the Sequence",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Response with the schema columns of the target schema type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_ColumnType"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ"
}
},
"/transformations/schema/instances": {
"get": {
"tags": [
"Schema"
],
"summary": "Get Instance schema.",
"description": "For View centric schema, `viewSpace`, `viewExternalId`, `viewVersion` need to be specified while `withInstanceSpace`, `isConnectionDefinition`, `instanceType` are optional . For Data Model centric schema, `dataModelSpace`, `dataModelExternalId`, `dataModelVersion`, `type` need to be specified and `relationshipFromType` is optional. For Both scenarios `conflictMode` is required.",
"operationId": "getFlexibleDataModelInstanceSchema",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "conflictMode",
"in": "query",
"description": "conflict mode of the transformation.\n One of the following conflictMode types can be provided:\n `upsert`, `delete`\n ",
"required": false,
"schema": {
"type": "string",
"enum": [
"abort",
"upsert",
"update",
"delete"
]
}
},
{
"name": "viewSpace",
"in": "query",
"description": "Space of the View. Not required if `isConnectionDefinition` is true. Relevant for View centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "viewExternalId",
"in": "query",
"description": "External id of the View. Not required if `isConnectionDefinition` is true. Relevant for View centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "viewVersion",
"in": "query",
"description": "Version of the View. Not required if `isConnectionDefinition` is true. Relevant for View centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "instanceType",
"in": "query",
"description": "Instance type to deal with",
"required": false,
"schema": {
"type": "string",
"enum": [
"nodes",
"edges"
]
}
},
{
"name": "withInstanceSpace",
"in": "query",
"description": "Is instance space set at the transformation config or not",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "isConnectionDefinition",
"in": "query",
"description": "If the edge is a connection definition or not",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "dataModelSpace",
"in": "query",
"description": "Space of the Data Model. Relevant for Data Model centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "dataModelExternalId",
"in": "query",
"description": "External id of the Data Model. Relevant for Data Model centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "dataModelVersion",
"in": "query",
"description": "Version of the Data Model. Relevant for Data Model centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "type",
"in": "query",
"description": "External id of the View in the Data model. Relevant for Data Model centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "relationshipFromType",
"in": "query",
"description": "Property Identifier of Connection Definition in `type`. Relevant for Data Model centric schema.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Response with the schema columns of the target schema type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_ColumnType"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ"
}
},
"/transformations/schema/{schemaType}": {
"get": {
"tags": [
"Schema"
],
"summary": "Get the schema of resource type",
"operationId": "getTransformationSchema",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaType",
"in": "path",
"description": "Name of the target schema type, please provide one of the following:\n `assets`, `timeseries`, `asset_hierarchy`, `events`, `datapoints`\n `string_datapoints`, `sequences`, `files`, `labels`,\n `relationships`, `raw`, `data_sets`",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "conflictMode",
"in": "query",
"description": "One of the following conflictMode types can be provided:\n `abort`, `upsert`, `update`, `delete`",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Response with the schema columns of the target schema type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_ColumnType"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import TransformationDestination\ncolumns = client.transformations.schema.retrieve(destination = TransformationDestination.assets())\n"
}
]
}
},
"/transformations/query/run": {
"post": {
"tags": [
"Query"
],
"summary": "Run query",
"description": "Preview a SQL query.",
"operationId": "runPreview",
"parameters": [
{
"name": "project",
"in": "path",
"description": "The project name.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryRequestBody"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with resulting rows from the query.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryResultsBody"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
},
"403": {
"description": "The response for a forbidden request.",
"content": {
"application/json": {
"schema": {
"required": [
"error"
],
"type": "object",
"properties": {
"error": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code."
},
"message": {
"type": "string",
"description": "Error message."
},
"missing": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of lookup objects that do not match any results."
},
"duplicated": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TransformationCogniteExternalId"
},
{
"$ref": "#/components/schemas/TransformationCogniteInternalId"
}
]
},
"description": "List of objects that are not unique."
}
}
}
}
}
}
}
}
},
"x-capability": "transformationsAcl:READ",
"x-code-samples": [
{
"lang": "Python",
"label": "Python SDK",
"source": "query_result = client.transformations.preview(query=\"select * from _cdf.assets\")\n\ndf = client.transformations.preview(query=\"select * from _cdf.assets\").to_pandas()\n"
}
]
}
},
"/annotations": {
"post": {
"tags": [
"Annotations"
],
"summary": "Create annotations",
"description": "Creates the given annotations.\n\n### Identifiers\nAn annotation _must_ reference an **annotated resource**.\n\nThe reference can be made by providing the internal ID of the annotated resource.\n\n### Status\nThe annotation _must_ have the `status` field set to either \"suggested\", \"rejected\", or \"approved\"\n\n### Access control\nThe caller _must_ have read-access on all the **annotated resources**, otherwise the call will fail.\n\n### Annotation types and Data\nThe annotation **type** property _must_ be set to one of the globally available annotation types.\nSee the documentation of the `annotationType` and `data` attributes for details.\n\nThe annotation **data** _must_ conform to the schema provided by the annotation type.\n\n### Creating Application and User\nThe creating application and its version _must_ be provided. The creating user _must_ be provided, but if the\nannotation is being created by a service, this _can_ be set to `null`.",
"operationId": "annotationsCreate",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2CreateRequestSchema"
},
"responses": {
"201": {
"$ref": "#/components/responses/AnnotationsV2CreateResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const data = {\n pageNumber: 7,\n textRegion: { xMin: 0, xMax: 0.1, yMin: 0, yMax: 0.2 },\n extractedText: 'i am your father',\n};\nconst annotation = {\n annotatedResourceType: 'file' as const,\n annotatedResourceId: 1,\n annotationType: 'documents.ExtractedText',\n creatingApp: 'integration-tests',\n creatingAppVersion: '0.0.1',\n creatingUser: 'integration-tests',\n status: 'suggested' as const,\n data,\n};\nconst created = await client.annotations.create([annotation]);"
}
]
}
},
"/annotations/suggest": {
"post": {
"tags": [
"Annotations"
],
"summary": "Suggest annotations",
"description": "Suggests the given annotations, i.e. creates them with `status` set to \"suggested\"\n\n### Identifiers\nAn annotation _must_ reference an **annotated resource**.\n\nThe reference can be made by providing the internal ID of the annotated resource.\n\n### Access control\nThe caller _must_ have read-access on all the **annotated resources**, otherwise the call will fail.\n\n### Annotation types and Data\nThe annotation **type** property _must_ be set to one of the globally available annotation types.\nSee the documentation of the `annotationType` and `data` attributes for details.\n\nThe annotation **data** _must_ conform to the schema provided by the annotation type.\n\n### Creating Application and User\nThe creating application and its version _must_ be provided. The creating user _must_ be provided, but if the\nannotation is being created by a service, this _can_ be set to `null`.",
"operationId": "annotationsSuggest",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2SuggestRequestSchema"
},
"responses": {
"201": {
"$ref": "#/components/responses/AnnotationsV2CreateResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:SUGGEST"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const data = {\n pageNumber: 7,\n textRegion: { xMin: 0, xMax: 0.1, yMin: 0, yMax: 0.2 },\n extractedText: 'i am your father',\n};\nconst partial = {\n annotatedResourceType: 'file' as const,\n annotatedResourceId: 1,\n annotationType: 'documents.ExtractedText',\n creatingApp: 'integration-tests',\n creatingAppVersion: '0.0.1',\n creatingUser: 'integration-tests',\n data,\n};\n\nconst created = await client.annotations.suggest([partial]);"
}
]
}
},
"/annotations/{annotationId}": {
"get": {
"tags": [
"Annotations"
],
"summary": "Get an annotation",
"description": "Retrieves the referenced annotation.\n\nThe caller _must_ have read-access on the **annotated resource**, otherwise the call will fail.",
"operationId": "annotationsGet",
"parameters": [
{
"$ref": "#/components/parameters/AnnotationId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2ResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const annotationIds = [{ id: 1 }, { id: 2 }];\n\nconst response = await client.annotations.retrieve(annotationIds);"
}
]
}
},
"/annotations/list": {
"post": {
"tags": [
"Annotations"
],
"summary": "Filter annotations",
"description": "Lists the annotations the caller has access to, based on a filter.\n\nThe caller _must_ have read-access on the **annotated resources** listed in the filter, otherwise the call will\nfail.",
"operationId": "annotationsFilter",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ListRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2CursoredListResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const annotatedFileId = 1;\nconst limitOne = await client.annotations.list({\n limit: 1,\n filter: {\n annotatedResourceType: 'file',\n annotatedResourceIds: [{ id: 1 }],\n },\n});"
}
]
}
},
"/annotations/byids": {
"post": {
"tags": [
"Annotations"
],
"summary": "Retrieve annotations",
"description": "Retrieves the referenced annotations.\n\nThe caller _must_ have read-access on all the **annotated resources**, otherwise the call will fail.",
"operationId": "annotationsByids",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ByIdsRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2ListResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const annotationIds = [{ id: 1 }, { id: 2 }];\n\nconst response = await client.annotations.retrieve(annotationIds);"
}
]
}
},
"/annotations/delete": {
"post": {
"tags": [
"Annotations"
],
"summary": "Delete annotations",
"description": "Deletes the referenced annotations completely.\n\nThe caller _must_ have read-access on all the **annotated resources**, otherwise the call will fail.",
"operationId": "annotationsDelete",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ByIdsRequestSchema"
},
"responses": {
"200": {
"description": "Successful deletion"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const annotationIds = [{ id: 1 }, { id: 2 }];\n\nawait client.annotations.delete(annotationIds);"
}
]
}
},
"/annotations/update": {
"post": {
"tags": [
"Annotations"
],
"summary": "Update annotations",
"description": "Updates the referenced annotations.\n\nThe caller _must_ have read-access on all the **annotated resources**, otherwise the call will fail.",
"operationId": "annotationsUpdate",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2UpdateRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2UpdateResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const data = {\n pageNumber: 8,\n fileRef: { externalId: 'def_file_changed' },\n textRegion: { xMin: 0, xMax: 0.1, yMin: 0, yMax: 0.2 },\n};\nconst changes = [\n {\n id: 1,\n update: {\n data: {\n set: data,\n },\n },\n },\n];\n\nconst updatedResp = await client.annotations.update(changes);"
}
]
}
},
"/seismic/seismics/segy/{seismicId}": {
"get": {
"tags": [
"Seismic"
],
"summary": "Download a seismic object as a SEG-Y file",
"description": "Retrieves a SEG-Y file with all traces contained within the given seismic object.",
"operationId": "downloadSeismic",
"parameters": [
{
"$ref": "#/components/parameters/seismicId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DownloadSeismicResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"seismicAcl:READ"
]
}
},
"/seismic/batchdownload": {
"post": {
"tags": [
"Seismic"
],
"summary": "Download multiple seismic objects as a ZIP archive",
"description": "Download multiple seismic objects specified by the filter, as a streamed ZIP archive file.",
"operationId": "batchDownloadSeismic",
"requestBody": {
"description": "The filter that determines the seismic objects to return.",
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/BatchDownloadRequestSeismic"
},
{
"$ref": "#/components/schemas/BatchDownloadRequestFilter"
}
]
}
}
}
},
"responses": {
"200": {
"description": "The generated ZIP archive file",
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary/zip"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"seismicAcl:READ",
"experimentAcl:USE"
]
}
},
"/profiles": {
"get": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"operationId": "listUserProfiles",
"summary": "List all user profiles",
"description": "List all user profiles in the current project. This operation supports pagination by cursor.\nThe results are ordered alphabetically by name.",
"parameters": [
{
"name": "identityType",
"in": "query",
"schema": {
"$ref": "#/components/schemas/IdentityTypeFilter"
}
},
{
"name": "limit",
"description": "Limits the number of results to be returned. The server returns no more than 1000 results even if the specified limit is larger. The default limit is 25.",
"in": "query",
"schema": {
"type": "integer",
"default": 25,
"minimum": 1,
"maximum": 1000
}
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesListResponse"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const response = await client.profiles.list({ limit: 1000 });"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.user_profiles.list(limit=None)\n"
}
]
}
},
"/profiles/me": {
"get": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"operationId": "getRequesterUserProfile",
"summary": "Get the user profile of the principal issuing the request",
"description": "Retrieves the user profile of the principal issuing the request.\nIf a principal doesn't have a user profile, you get a not found (404) response code.",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfileItem"
}
}
}
},
"404": {
"description": "The user profile for the requesting principal was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesNotFoundResponse"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const response = await client.profiles.me();"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.user_profiles.me()\n"
}
]
}
},
"/profiles/byids": {
"post": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"operationId": "getUserProfilesByIds",
"summary": "Retrieve one or more user profiles by ID",
"description": "Retrieve one or more user profiles indexed by the user identifier in the same CDF project.",
"requestBody": {
"description": "Specify a maximum of 1000 unique IDs.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesByIdsRequest"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesByIdsResponse"
}
}
}
},
"400": {
"description": "The response for a failed request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesErrorResponse"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const response = await client.profiles.retrieve([{ userIdentifier: 'abcd' }]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.user_profiles.retrieve(\"foo\")\n\nres = client.iam.user_profiles.retrieve([\"bar\", \"baz\"])\n"
}
]
}
},
"/profiles/search": {
"post": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"operationId": "userProfilesSearch",
"summary": "Search user profiles",
"description": "Search user profiles in the current project. The result set ordering and match criteria \nthreshold may change over time. This operation does not support pagination.",
"requestBody": {
"description": "Query for user profile search.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesSearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "List of matched user profiles. If no user profile matches, you'll receive an empty set.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserProfilesSearchResponse"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const response = await client.profiles.search({ search: { name: 'John' } });"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.user_profiles.search(name=\"Alex\")\n"
}
]
}
},
"/hostedextractors/destinations": {
"get": {
"tags": [
"Destinations"
],
"operationId": "list_destinations",
"x-capability": [
"hostedExtractors:READ"
],
"parameters": [
{
"$ref": "#/components/parameters/100Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"description": "List all destinations in a given project. If more than `limit` destinations exist, a cursor for pagination will be returned with the response.",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_Destination_"
}
}
},
"description": "List of destinations and an optional cursor."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ErrorResponse",
"description": "Validation Error"
}
},
"summary": "List Destinations"
},
"post": {
"tags": [
"Destinations"
],
"operationId": "create_destinations",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Create up to 100 destinations.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_CreateDestination_"
}
}
},
"required": true,
"description": "Destinations to create."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Destination_"
}
}
},
"description": "List of created destinations"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse",
"description": "Response for a failed request"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Create Destinations"
}
},
"/hostedextractors/destinations/byIds": {
"post": {
"tags": [
"Destinations"
],
"operationId": "retrieve_destinations",
"x-capability": [
"hostedExtractors:READ"
],
"description": "Retrieve a list of up to 100 destinations by their external ID, optionally ignoring unknown IDs.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of destinations to retrieve."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Destination_"
}
}
},
"description": "List of retrieved destinations."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Retrieve Destinations"
}
},
"/hostedextractors/destinations/delete": {
"post": {
"tags": [
"Destinations"
],
"operationId": "delete_destinations",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Delete a list of destinations by their external ID. This operation will fail if any destination in the request is associated with a job, unless the `force` query parameter is set to `true`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIdsAndForce_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of destinations to delete."
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse",
"description": "Empty response"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Delete Destinations"
}
},
"/hostedextractors/destinations/update": {
"post": {
"tags": [
"Hosted Extractor Destinations"
],
"operationId": "update_destinations",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Update up to 100 destinations.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_DestinationUpdateItem_"
}
}
},
"required": true,
"description": "Destinations to update."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Destination_"
}
}
},
"description": "List of updated destinations."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Update Destinations"
}
},
"/hostedextractors/jobs": {
"get": {
"tags": [
"Jobs"
],
"operationId": "list_jobs",
"x-capability": [
"hostedExtractors:READ"
],
"description": "List all jobs in a given project. If more than `limit` jobs exist, a cursor for pagination will be returned with the response.",
"parameters": [
{
"$ref": "#/components/parameters/100Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"in": "query",
"name": "source",
"description": "External ID of source the returned jobs must be tied to.",
"required": false,
"schema": {
"type": "string",
"title": "Source"
}
},
{
"in": "query",
"name": "destination",
"description": "External ID of destination the returned jobs must be tied to.",
"required": false,
"schema": {
"type": "string",
"title": "Destination"
}
},
{
"in": "query",
"name": "mapping",
"description": "External ID of mapping the returned jobs must be tied to.",
"required": false,
"schema": {
"type": "string",
"title": "Mapping"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_MinimalJob_"
}
}
},
"description": "List of jobs and an optional cursor."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "List Jobs"
},
"post": {
"tags": [
"Jobs"
],
"operationId": "create_jobs",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Create up to 100 jobs.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_CreateJob_"
}
}
},
"required": true,
"description": "Jobs to create."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_MinimalJob_"
}
}
},
"description": "Successful Response"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Create Jobs"
}
},
"/hostedextractors/jobs/byIds": {
"post": {
"tags": [
"Jobs"
],
"operationId": "retrieve_jobs",
"x-capability": [
"hostedExtractors:READ"
],
"description": "Retrieve a list of up to 100 jobs by their external ID, optionally ignoring unknown IDs.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of jobs to retrieve."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_MinimalJob_"
}
}
},
"description": "List of retrieved jobs."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Retrieve Jobs"
}
},
"/hostedextractors/jobs/delete": {
"post": {
"tags": [
"Jobs"
],
"operationId": "delete_jobs",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Delete a list of jobs by their external ID.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of jobs to delete."
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse",
"description": "Empty response"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Delete Jobs"
}
},
"/hostedextractors/jobs/logs": {
"get": {
"tags": [
"Jobs"
],
"operationId": "get_job_logs",
"x-capability": [
"hostedExtractors:READ"
],
"description": "List logs, optionally filtering on job, source, or destination. Logs are retrieved in reverse chronological order.",
"parameters": [
{
"in": "query",
"name": "job",
"required": false,
"schema": {
"type": "string",
"title": "Job"
},
"description": "Require returned logs to belong to the job given by this external ID."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"type": "string",
"title": "Source"
},
"description": "Require returned logs to belong to the any job with source given by this external ID."
},
{
"in": "query",
"name": "destination",
"required": false,
"schema": {
"type": "string",
"title": "Destination"
},
"description": "Require returned logs to belong to the any job with destination given by this external ID."
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_JobLogEntry_"
}
}
},
"description": "List of retrieved job logs"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Get Job Logs"
}
},
"/hostedextractors/jobs/metrics": {
"get": {
"tags": [
"Jobs"
],
"operationId": "get_job_metrics",
"x-capability": [
"hostedExtractors:READ"
],
"description": "List metrics, optionally filtering on job, source, or destination. Logs are retrieved in reverse chronological order.",
"parameters": [
{
"in": "query",
"name": "job",
"required": false,
"schema": {
"type": "string",
"title": "Job"
},
"description": "Require returned metrics to belong to the job given by this external ID."
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"type": "string",
"title": "Source"
},
"description": "Require returned metrics to belong to the any job with source given by this external ID."
},
{
"in": "query",
"name": "destination",
"required": false,
"schema": {
"type": "string",
"title": "Destination"
},
"description": "Require returned metrics to belong to the any job with destination given by this external ID."
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_JobMetrics_"
}
}
},
"description": "List of retrieved job metrics."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Get Job Metrics"
}
},
"/hostedextractors/jobs/update": {
"post": {
"tags": [
"Jobs"
],
"operationId": "update_jobs",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Update a list of up to 100 jobs.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_JobUpdateItem_"
}
}
},
"required": true,
"description": "Jobs to update."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_MinimalJob_"
}
}
},
"description": "List of updated jobs."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Update Jobs"
}
},
"/hostedextractors/sources": {
"get": {
"tags": [
"Sources"
],
"operationId": "list_sources",
"x-capability": [
"hostedExtractors:READ"
],
"description": "List all sources in a given project. If more than `limit` sources exist, a cursor for pagination will be returned with the response.",
"parameters": [
{
"$ref": "#/components/parameters/100Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_Source_"
}
}
},
"description": "List of sources and an optional cursor."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse",
"description": "Response for a failed request"
},
"422": {
"$ref": "#/components/responses/ErrorResponse",
"description": "Validation Error"
}
},
"summary": "List Sources"
},
"post": {
"tags": [
"Sources"
],
"operationId": "create_sources",
"x-capability": [
"hostedExtractors:READ"
],
"description": "Create up to 100 sources.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_CreateSource_"
}
}
},
"required": true,
"description": "Sources to create."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Source_"
}
}
},
"description": "List of created sources."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Create Sources"
}
},
"/hostedextractors/sources/byIds": {
"post": {
"tags": [
"Sources"
],
"operationId": "retrieve_sources",
"x-capability": [
"hostedExtractors:READ"
],
"description": "Retrieve a list of up to 100 sources by their external ID, optionally ignoring unknown IDs.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of sources to retrieve."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Source_"
}
}
},
"description": "List of retrieved sources."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Retrieve Sources"
}
},
"/hostedextractors/sources/delete": {
"post": {
"tags": [
"Sources"
],
"operationId": "delete_sources",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Delete a list of sources by their external ID. This operation will fail if any destination in the request is associated with a job, unless the `force` query parameter is set to `true`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIdsAndForce_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of sources to delete."
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse",
"description": "Empty response"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Delete Sources"
}
},
"/hostedextractors/sources/update": {
"post": {
"tags": [
"Sources"
],
"operationId": "update_sources",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Update up to 100 sources.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_UpdateSource_"
}
}
},
"description": "Sources to update."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Source_"
}
}
},
"description": "List of updated sources."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Update Sources"
}
},
"/hostedextractors/mappings": {
"get": {
"tags": [
"Mappings"
],
"operationId": "list_mappings",
"x-capability": [
"hostedExtractors:READ"
],
"description": "List all mappings in a given project. If more than `limit` mappings exist, a cursor for pagination will be returned with the response.",
"parameters": [
{
"$ref": "#/components/parameters/100Limit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithCursor_Mapping_"
}
}
},
"description": "List of mappings and an optional cursor."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "List Mappings"
},
"post": {
"tags": [
"Mappings"
],
"operationId": "create_mappings",
"x-capability": [
"hostedExtractors:WRITE"
],
"description": "Create up to 100 mappings.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_CreateMapping_"
}
}
},
"required": true,
"description": "Mappings to create."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Mapping_"
}
}
},
"description": "List of created mappings"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Create Mappings"
}
},
"/hostedextractors/mappings/byIds": {
"post": {
"operationId": "retrieve_mappings",
"x-capability": [
"hostedExtractors:READ"
],
"tags": [
"Mappings"
],
"description": "Retrieve a list of up to 100 mappings by their external ID, optionally ignoring unknown IDs.",
"parameters": [
{
"in": "header",
"name": "cdf-version",
"required": false,
"schema": {
"title": "Cdf-Version",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIds_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of mappings to retrieve."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Mapping_"
}
}
},
"description": "List of retrieved mappings."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Retrieve Mappings"
}
},
"/hostedextractors/mappings/delete": {
"post": {
"operationId": "delete_mappings",
"x-capability": [
"hostedExtractors:WRITE"
],
"tags": [
"Mappings"
],
"description": "Delete a list of mappings by their external ID. This operation will fail if any mapping in the request is associated with a job, unless the `force` query parameter is set to `true`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsWithIgnoreUnknownIdsAndForce_ExternalId_"
}
}
},
"required": true,
"description": "List of external IDs of mappings to delete."
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse",
"description": "Empty response"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Delete Mappings"
}
},
"/hostedextractors/mappings/update": {
"post": {
"operationId": "update_mappings",
"x-capability": [
"hostedExtractors:WRITE"
],
"tags": [
"Mappings"
],
"description": "Update up to 100 mappings.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_MappingUpdateItem_"
}
}
},
"required": true,
"description": "Mappings to update."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Items_Mapping_"
}
}
},
"description": "List of updated mappings."
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"422": {
"$ref": "#/components/responses/ValidationError"
}
},
"summary": "Update Mappings"
}
},
"/units/byids": {
"post": {
"tags": [
"Units"
],
"summary": "Retrieve units by external IDs",
"description": "Retrieves one or more units by external ID. The response returns the units in the same order as in the request.",
"operationId": "byIdsUnits",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestrictedItemList_ExternalIdRef_"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response with a list of units",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewList_Unit_"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const units = await client.units.retrieve([{ externalId: 'temperature:deg_c' }, { externalId: 'pressure:bar' }]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.units.retrieve('temperature:deg_c')\n\nres = client.units.retrieve(['temperature:deg_c', 'pressure:bar'])\n"
}
]
}
},
"/units/systems": {
"get": {
"tags": [
"Unit Systems"
],
"summary": "List all unit systems",
"description": "List all unit systems.",
"operationId": "listUnitSystems",
"responses": {
"200": {
"description": "Response with a list of unit systems",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewList_UnitSystem_"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const units = await client.units.listUnitSystems();"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.units.systems.list()\n"
}
]
}
},
"/units/{externalId}": {
"get": {
"tags": [
"Units"
],
"summary": "Retrieve unit by external ID",
"description": "Retrieve a single unit by its external ID.",
"operationId": "getUnit",
"parameters": [
{
"name": "externalId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "External ID of the unit",
"title": "Externalid"
},
"description": "External ID of the unit"
}
],
"responses": {
"200": {
"description": "Response with a single unit",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewList_Unit_"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
},
"description": "Bad Request"
}
}
}
},
"/units": {
"get": {
"tags": [
"Units"
],
"summary": "List all units",
"description": "List all units.",
"operationId": "listUnits",
"responses": {
"200": {
"description": "Response with a list of units",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewList_Unit_"
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const units = await client.units.list();"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.units.list()\n"
}
]
}
}
},
"components": {
"securitySchemes": {
"oidc-token": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "OpenID Connect or OAuth2 token",
"description": "Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider."
},
"oauth2-client-credentials": {
"type": "oauth2",
"description": "Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://your-idps.token.url/",
"scopes": {
"default": "https://{cluster}.cognitedata.com/.default"
}
}
}
},
"oauth2-auth-code": {
"type": "oauth2",
"description": "Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://your-idps.authorization.url/",
"tokenUrl": "https://your-idps.token.url/",
"scopes": {
"default": "https://{cluster}.cognitedata.com/.default"
}
}
}
},
"oauth2-open-industrial-data": {
"type": "oauth2",
"description": "Auth flow for Open Industrial Data. Get your client secret from https://hub.cognite.com/open-industrial-data-211.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://login.microsoftonline.com/48d5043c-cf70-4c49-881c-c638f5796997/oauth2/v2.0/token",
"scopes": {
"default": "https://api.cognitedata.com/.default"
}
}
}
},
"token": {
"type": "http",
"description": "Users log in via an OpenID/OAuth flow. Use the /login/redirect flow to obtain a bearer access token. Use a header key of 'Authorization' with a value of 'Bearer: $accesstoken'",
"scheme": "bearer"
}
},
"schemas": {
"TokenInspectionResponse": {
"type": "object",
"required": [
"subject",
"projects",
"capabilities"
],
"properties": {
"subject": {
"type": "string",
"description": "Subject (sub claim) of JWT"
},
"projects": {
"$ref": "#/components/schemas/Projects"
},
"capabilities": {
"$ref": "#/components/schemas/Capabilities"
}
}
},
"Projects": {
"type": "array",
"title": "projects",
"items": {
"type": "object",
"required": [
"projectUrlName",
"groups"
],
"properties": {
"projectUrlName": {
"type": "string",
"description": "Project url name"
},
"groups": {
"type": "array",
"description": "Group IDs",
"items": {
"type": "integer",
"description": "group ids",
"format": "int64"
}
}
}
}
},
"Capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Capability"
}
},
"Capability": {
"type": "object",
"oneOf": [
{
"title": "Groups Capability",
"properties": {
"groupsAcl": {
"$ref": "#/components/schemas/cognitegroups_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Assets Capability",
"properties": {
"assetsAcl": {
"$ref": "#/components/schemas/cogniteassets_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Events Capability",
"properties": {
"eventsAcl": {
"$ref": "#/components/schemas/cogniteevents_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Files Capability",
"properties": {
"filesAcl": {
"$ref": "#/components/schemas/cognitefiles_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Projects Capability",
"properties": {
"projectsAcl": {
"$ref": "#/components/schemas/cogniteprojects_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Security Category Capability",
"properties": {
"securityCategoriesAcl": {
"$ref": "#/components/schemas/cognitesecuritycategories_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Raw Capability",
"properties": {
"rawAcl": {
"$ref": "#/components/schemas/cogniteraw_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "TimeSeries Capability",
"properties": {
"timeSeriesAcl": {
"$ref": "#/components/schemas/cognitetimeseries_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Threed Capability",
"properties": {
"threedAcl": {
"$ref": "#/components/schemas/cognitethreed_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Sequences Capability",
"properties": {
"sequencesAcl": {
"$ref": "#/components/schemas/cognitesequences_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Labels Capability",
"properties": {
"labelsAcl": {
"$ref": "#/components/schemas/cognitelabels_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Analytics Capability",
"properties": {
"analyticsAcl": {
"$ref": "#/components/schemas/cogniteanalytics_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Digital Twin Capability",
"properties": {
"digitalTwinAcl": {
"$ref": "#/components/schemas/cognitedigitaltwin_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Data Modeling Schema Capability",
"properties": {
"digitalTwinAcl": {
"$ref": "#/components/schemas/cognitedatamodels_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Data Modeling Instances Capability",
"properties": {
"digitalTwinAcl": {
"$ref": "#/components/schemas/cognitedatamodelinstances_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Relationships Capability",
"properties": {
"relationshipsAcl": {
"$ref": "#/components/schemas/cogniterelationships_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Datasets Capability",
"properties": {
"datasetsAcl": {
"$ref": "#/components/schemas/cognitedatasets_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Seismic Capability",
"properties": {
"seismicAcl": {
"$ref": "#/components/schemas/cogniteseismic_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Types Capability",
"properties": {
"typesAcl": {
"$ref": "#/components/schemas/cognitetypes_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Functions Capability",
"properties": {
"functionsAcl": {
"$ref": "#/components/schemas/functions_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Extraction Pipelines Capability",
"properties": {
"extractionpipelinesAcl": {
"$ref": "#/components/schemas/extractionpipelines_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
},
{
"title": "Extraction Pipeline Runs Capability",
"properties": {
"extractionrunsAcl": {
"$ref": "#/components/schemas/extractionruns_aclAcl"
},
"projectScope": {
"$ref": "#/components/schemas/ProjectScope"
}
}
}
]
},
"ProjectScope": {
"oneOf": [
{
"type": "object",
"title": "allProjects",
"required": [
"allProjects"
],
"properties": {
"allProjects": {
"type": "object",
"description": "All projects"
}
}
},
{
"type": "object",
"title": "projectsList",
"required": [
"projects"
],
"properties": {
"projects": {
"type": "array",
"title": "projectUrlNames",
"items": {
"$ref": "#/components/schemas/ProjectUrlName"
}
}
}
}
]
},
"ResourceDescription": {
"type": "string",
"description": "The description of the resource type.",
"maxLength": 500
},
"IgnoreUnknownIdsField": {
"type": "object",
"properties": {
"ignoreUnknownIds": {
"description": "Ignore IDs and external IDs that are not found",
"type": "boolean",
"default": false
}
}
},
"Limit": {
"type": "object",
"properties": {
"limit": {
"description": "Limits the number of results to return.",
"type": "integer",
"default": 100,
"minimum": 1,
"maximum": 1000
}
}
},
"ExternalIdPrefixFilter": {
"description": "filter external ids starting with the prefix specified",
"type": "string",
"maxLength": 255
},
"DataLong": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"example": [
23872937137,
1238712837,
128371973
],
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "integer",
"format": "int64"
}
}
}
},
"Error": {
"type": "object",
"required": [
"code",
"message"
],
"description": "Cognite API error.",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code.",
"format": "int32",
"example": 401
},
"message": {
"type": "string",
"description": "Error message.",
"example": "Could not authenticate."
},
"missing": {
"type": "array",
"description": "List of lookup objects that do not match any results.",
"items": {
"type": "object",
"additionalProperties": true
}
},
"duplicated": {
"type": "array",
"description": "List of objects that are not unique.",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
},
"429Error": {
"type": "object",
"required": [
"code",
"message"
],
"description": "Cognite API throttling.",
"properties": {
"code": {
"type": "integer",
"description": "429 HTTP status code.",
"format": "int32",
"example": 429
},
"message": {
"type": "string",
"description": "The error message specifies which kind of throttling happened: \n - Too many concurrent requests for a single project or an identity.\n - Too high rate of requests for a single project or an identity.\n\nSee more [here](https://docs.cognite.com/dev/concepts/request_throttling/ \"requests throttling\").",
"example": "Project exceeded maximum number='50' of concurrent requests. Please try again later."
}
}
},
"ObjectPatch": {
"type": "object",
"description": "Custom, application specific metadata. String key -> String value.",
"oneOf": [
{
"$ref": "#/components/schemas/ObjectPatchSet"
},
{
"$ref": "#/components/schemas/ObjectPatchAddRemove"
}
]
},
"ObjectPatchSet": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"uniqueItems": true,
"type": "object",
"description": "Set the key-value pairs. All existing key-value pairs will be removed.",
"additionalProperties": {
"type": "string"
},
"example": {
"key1": "value1",
"key2": "value2"
}
}
}
},
"ObjectPatchAddRemove": {
"title": "add/remove",
"type": "object",
"properties": {
"add": {
"uniqueItems": true,
"type": "object",
"description": "Add the key-value pairs. Values for existing keys will be overwritten.",
"additionalProperties": {
"type": "string"
},
"example": {
"key1": "value1",
"key2": "value2"
}
},
"remove": {
"uniqueItems": true,
"type": "array",
"description": "Remove the key-value pairs with the specified keys.",
"example": [
"value1",
"value2"
],
"items": {
"type": "string"
}
}
}
},
"ObjectPatchEvent": {
"type": "object",
"description": "Custom, application specific metadata. String key -> String value. Limits of updated event: Maximum length of key is 128 bytes, value 128000 bytes, up to 256 key-value pairs, of total size at most 200000.",
"oneOf": [
{
"$ref": "#/components/schemas/ObjectPatchEventSet"
},
{
"$ref": "#/components/schemas/ObjectPatchEventAddRemove"
}
]
},
"ObjectPatchEventSet": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"uniqueItems": true,
"type": "object",
"description": "Set the key-value pairs. All existing key-value pairs will be removed.",
"additionalProperties": {
"type": "string",
"maxLength": 128000
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 200000,
"maxProperties": 256,
"example": {
"key1": "value1",
"key2": "value2"
}
}
}
},
"ObjectPatchEventAddRemove": {
"title": "add/remove",
"type": "object",
"properties": {
"add": {
"uniqueItems": true,
"type": "object",
"description": "Add the key-value pairs. Values for existing keys will be overwritten.",
"additionalProperties": {
"type": "string",
"maxLength": 128000
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 200000,
"maxProperties": 256,
"example": {
"key1": "value1",
"key2": "value2"
}
},
"remove": {
"uniqueItems": true,
"type": "array",
"description": "Remove the key-value pairs with the specified keys.",
"example": [
"value1",
"value2"
],
"items": {
"type": "string"
}
}
}
},
"ObjectPatchAsset": {
"type": "object",
"description": "Custom, application specific metadata. String key -> String value. Limits of updated asset: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.",
"oneOf": [
{
"$ref": "#/components/schemas/ObjectPatchSetAsset"
},
{
"$ref": "#/components/schemas/ObjectPatchAddRemoveAsset"
}
]
},
"ObjectPatchSetAsset": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"uniqueItems": true,
"type": "object",
"description": "Set the key-value pairs. All existing key-value pairs will be removed.",
"additionalProperties": {
"type": "string",
"maxLength": 10240
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 10240,
"maxProperties": 256,
"example": {
"key1": "value1",
"key2": "value2"
}
}
}
},
"ObjectPatchAddRemoveAsset": {
"title": "add/remove",
"type": "object",
"properties": {
"add": {
"uniqueItems": true,
"type": "object",
"description": "Add the key-value pairs. Values for existing keys will be overwritten.",
"additionalProperties": {
"type": "string",
"maxLength": 10240
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 10240,
"maxProperties": 256,
"example": {
"key1": "value1",
"key2": "value2"
}
},
"remove": {
"uniqueItems": true,
"type": "array",
"description": "Remove the key-value pairs with the specified keys.",
"example": [
"value1",
"value2"
],
"items": {
"type": "string"
}
}
}
},
"ObjectPatchDataSet": {
"type": "object",
"description": "Custom, application specific metadata. String key -> String value. Limits of updated asset: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.",
"oneOf": [
{
"$ref": "#/components/schemas/ObjectPatchSetDataSet"
},
{
"$ref": "#/components/schemas/ObjectPatchAddRemoveDataSet"
}
]
},
"ObjectPatchSetDataSet": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"uniqueItems": true,
"type": "object",
"description": "Set the key-value pairs. All existing key-value pairs will be removed.",
"additionalProperties": {
"type": "string",
"maxLength": 10240
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 10240,
"maxProperties": 256,
"example": {
"key1": "value1",
"key2": "value2"
}
}
}
},
"ObjectPatchAddRemoveDataSet": {
"title": "add/remove",
"type": "object",
"properties": {
"add": {
"uniqueItems": true,
"type": "object",
"description": "Add the key-value pairs. Values for existing keys will be overwritten.",
"additionalProperties": {
"type": "string",
"maxLength": 10240
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 10240,
"maxProperties": 256,
"example": {
"key1": "value1",
"key2": "value2"
}
},
"remove": {
"uniqueItems": true,
"type": "array",
"description": "Remove the key-value pairs with the specified keys.",
"example": [
"value1",
"value2"
],
"items": {
"type": "string"
}
}
}
},
"ArrayPatchLongSet": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"uniqueItems": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
}
},
"ArrayPatchLongAddOrRemove": {
"title": "add/remove",
"type": "object",
"properties": {
"add": {
"uniqueItems": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"remove": {
"uniqueItems": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
}
},
"ArrayPatchLong": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/ArrayPatchLongSet"
},
{
"$ref": "#/components/schemas/ArrayPatchLongAddOrRemove"
}
],
"description": "Change that will be applied to the array."
},
"ArrayPatchStringSet": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"uniqueItems": true,
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ArrayPatchStringAddOrRemove": {
"title": "add/remove",
"type": "object",
"properties": {
"add": {
"uniqueItems": true,
"type": "array",
"items": {
"type": "string"
}
},
"remove": {
"uniqueItems": true,
"type": "array",
"items": {
"type": "string"
}
}
}
},
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment