Skip to content

Instantly share code, notes, and snippets.

@ks93

ks93/23cc431c-37bb-4adf-8e08-3bfe80ab5d36

Created August 11, 2023 13:55
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/2d8d917b8a6d0d363cbf19337621e91c to your computer and use it in GitHub Desktop.
Save ks93/2d8d917b8a6d0d363cbf19337621e91c to your computer and use it in GitHub Desktop.
Download ZIP
beta api 23cc431c-37bb-4adf-8e08-3bfe80ab5d36
Raw
23cc431c-37bb-4adf-8e08-3bfe80ab5d36
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\nYou can download our postman collection [here](https://storage.googleapis.com/cognite-postman-collections/20230101.json).\nOpen Postman, click `Import -> Import From Link`, insert the link and import.\n\nYou can read more about how to use Postman [here](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\nIf you want to download a lot of resources (let's say events), paginating through millions of records can be slow.\nWe support 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.\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 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",
"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\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 Model Storage API to manage your data in CDF.\n\nYou define a data model with views and data containers. Data containers specify how the service stores data. \nViews define the logical view of the stored data. Nodes and edges are representations of data containers. \nWe call these node and edge representations \"instances\". Each node or edge can hold one or more data \ncontainers. You can query nodes and edges using views. Views combine data from one or more data containers.\n\nA container represents a bag of properties. These properties have a type. They also have optional constraints, \ndefault values, and you can choose to index them.\n\nEach data container has a default view available so you can query all its properties.\n\nA data model is a collection (set) of views. Use the data model to group and structure views into a \nrecognizable, and understood model. The model represents a reusable collection of data.\n\nEach data model has a version. A data model can also import other data models, so you can reuse views.\n\nAll resources described have to belong to a space. You use a space to create a logical grouping of your \nresources, and to act as a governance boundary. A space defines a namespace. \n\nYou use the space (name) and the external-id - externalId - for the resource to identify it. For view or \ncontainer properties, the external-id for the view - or container - is part of the identifier. This means you \ncan have resources using the exact external-id in two different spaces.\n"
},
{
"name": "Events",
"description": "Event objects store complex information about multiple assets over a time\nperiod. For example, an event can describe two hours of maintenance on a\nwater pump and some associated pipes, or a future time window where the\npump is scheduled for inspection. This is in contrast with data points in\ntime series that store single pieces of information about one asset at\nspecific points in time (e.g., temperature measurements).\n\n\nAn event’s time period is defined by a start time and end time, both\nmillisecond timestamps since the UNIX epoch. The timestamps can be in the\nfuture. In addition, events can have a text description as well as\narbitrary metadata and properties.\n\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\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 events](operation/listEvents), [Filter events](operation/advancedListEvents), \n[Aggregate events](operation/aggregateEvents) and [Search events](operation/searchEvents) 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 events](operation/aggregateEvents) 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": "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": "Data point subscriptions",
"description": "A data point subscription is a way to listen to changes to time series data points, in ingestion order.\n\nA single subscription can listen to many time series, and a time series can be part of many subscriptions.\n\nYou listen to subscriptions by calling the “list subscription data“ endpoint. It will return\na list of data point upserts and deleted ranges, together with a cursor to retrieve the next\nbatch of updates. It will store updates from when the subscription was created, but updates\nolder than 7 days may be discarded.\n\nSubscriptions can be defined explicitly through a list of time series external ids, or\nimplicitly through a filter. The filter is a subset of the advanced filter query in the regular\n“time series search“ endpoint.\n\nPartitions:\nSubscriptions can be further divided into a number of partitions, for the purpose of\nfetching subscription data in parallel. Each partition will return data in ingestion order,\nbut the order between partitions is not guaranteed.\n\nLimitations (may be subject to change):\n- Each subscription can have at most 10000 time series\n- A time series can be part of at most 10 subscriptions\n- A project can have at most 1000 subscriptions, of which 100 filter subscriptions\n- Time series with security categories can not be shown in filter subscriptions\n- Time series without externalId cannot be added to non-filter subscriptions\n- The number of partitions cannot be changed after creation\n\nBeta: Subscriptions are available only when the `cdf-version` header with the value `beta` is provided.\n\nAccess control: You need to have experimental access to timeseries-subscriptions as long as\nsubscriptions are in beta. You also need READ access to subscriptions ACL to read/list\nsubscriptions or list data, and you need WRITE access to create/update/delete subscriptions.\nFurthermore, you need READ access to the time series you want to get updates from.\nFor filter subscriptions, you either need READ access to all time series, or the filter must\nbe restricted according to your access rights (e.g. by filtering on specific data set IDs).\n\nExample capabilities:\n```\n[\n {\"timeSeriesAcl\":{\"actions\":[\"READ\"], \"scope\":{\"all\":{}}}},\n {\"timeSeriesSubscriptionsAcl\":{\"actions\":[\"WRITE\", \"READ\"], \"scope\":{\"all\":{}}}},\n {\"experimentAcl\":{\"actions\":[\"USE\"], \"scope\":{\"experimentscope\":{\"experiments\":[\"timeseries-subscription\"]}}}}\n]\n```"
},
{
"name": "Synthetic Time Series",
"description": "Synthetic Time Series (STS) is a way to combine various input time series, constants and operators, to create completely new time series.\n\nFor example can we use the expression `24 * TS{externalId='production/hour'}` to convert from hourly to daily production rates.\n\nBut STS is not limited to simple conversions.\n* We support combination of different time series `TS{id=123} + TS{externalId='hei'}`.\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. Each project will have a variable number of raw databases, each of which will have a variable number of tables, each of which will have a variable number of key-value objects. Only queries on key are supported through this API."
},
{
"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](/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.\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": "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"
}
],
"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/partition"
}
],
"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": "asset_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": "asset_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\"})\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)\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/list": {
"post": {
"tags": [
"Data models"
],
"summary": "Filter data models",
"description": "List data models in a project when they match a given filter.",
"operationId": "advancedListDataModels",
"requestBody": {
"description": "Filter based on name, externalIds, versions and space. It also supports sorting and pagination.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataModelsListRequest"
}
}
},
"required": true
},
"x-capability": [
"DataModelsAcl:READ"
],
"responses": {
"200": {
"$ref": "#/components/responses/DataModelCollectionResponseWithCursor"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/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/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\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. 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.data_modeling.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=(\"myNode\", \"mySpace\"))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId\nclient.data_modeling.instances.delete(NodeId('mySpace', 'myNode'), EdgeId('mySpace', 'myEdge'))\n"
}
]
}
},
"/models/instances/query": {
"post": {
"tags": [
"Instances"
],
"summary": "Query nodes/edges",
"description": "# Querying\n\nThe Data Modelling API exposes an advanced query interface. The query interface supports parameterization, \nrecursive edge traversal, chaining of result sets, and granular property selection.\n\nA query is composed of a with section defining result set expressions that describe the input to the query, \na set of optional parameter placeholders if the query is parameterized, and then the select section that defines \nwhich properties are to be returned back as part of the result.\n\nImagine you have a data set with airplanes and airports, represented as two sets of nodes with edges between them\nindicating in which airports the airplanes land. Here is an example of a query which fetches a specific airplane as \nwell as the airports it lands in:\n\n```yaml\nwith:\n airplanes:\n nodes:\n filter:\n equals:\n property: [\"node\", \"externalId\"]\n value: {\"parameter\": \"airplaneExternalId\"}\n limit: 1\n lands_in_airports:\n edges:\n from: airplanes\n maxDistance: 1\n direction: outwards\n filter:\n equals:\n property: [\"edge\", \"type\"]\n value: [\"aviation\", \"lands-in\"]\n airports:\n nodes:\n from: lands_in_airports\nparameters:\n airplaneExternalId: myFavouriteAirplane\nselect:\n airplanes: {}\n airports: {}\n```\n\n## Result Set Expressions\n\nResult set expressions appear directly below `with` in a query, and define a set of either nodes or edges. \nThe set may be used to return results, as stepping stones to derive other sets from, or both.\nResult set expressions are named and can be chained as we'll see examples of later.\n\nA result set expression may also define `sort` order and a `limit`. See [sorting](#sorting-and-limiting) for more \ndetails.\n\nWhile result set expressions may relate to each other via chaining, they don't have to. You can query for \nentirely unrelated things in the same query, but different sets are generally used to power graph traversals.\n\nA set either queries nodes _or_ it queries edges, possibly recursively.\n\nAll fields:\n- `nodes`: An object to specify a result set of matching nodes.\n- `edges`: An object to specify a result set of matching edges.\n- `sort`: A list of sort configurations\n- `limit`: How many nodes or edges to return in the result. Default: 100\n\n### Pagination\nThe max limit you can set for any table expression is 10,000. In order to support retrieving the entire result set, \npagination cursors are emitted for each result set expression, allowing you to page through everything. Pagination \ncursors cannot be combined with custom sorts. If no pagination cursor is present for a given result set expression \nin the response, then there is guaranteed no more data that matches.\n\n### Node result set expressions\nA `nodes` statement in your result set expression will make the set contain nodes. \n\nA node result set can be chained off both node and edge result set expressions. When chaining off another node result \nset you will retrieve the nodes pointed to by a given direct relation property, this direct relation \nproperty is defined using the `through` field. When chaining off an edge result set, you will retrieve the end nodes \ndefined by the edges in the set.\n\n- `from`: A different result set expression to chain from\n- `through`: What property to join the `from` \"through\". The `through` property must be a direct relation.\n- `chainTo`: Control which side of the edge to chain to. This option is only applicable if the view referenced in the `from` field consists of edges. `chainTo` can be one of:\n\n - `source` will chain to `start` if you're following edges outwards i.e `direction=outwards`. If you're following edges inwards i.e `direction=inwards`, it will chain to `end`.\n\n - `destination (default)` will chain to `end` if you're following edges outwards i.e `direction=outwards`. If you're following edges inwards i.e `direction=inwards`, it will chain to `start`.\n\n- `filter`: A filter to determine which nodes to match and thus be returned in the respective result set.\n\n### Edge result set expressions\n\nAn `edges` statement in a result set expression will make the set contain edges, and the statement defines the rules \nthe graph traversal will follow.\n\nA graph traversal can start from some initial set. This can be defined by `from`, which will name another result \nset expression.\n\nThe graph traversal follows edges in a particular direction, controlled by `direction`, which defaults to `outwards`.\n\n```\n Alice -is_parent-> Bob\n Bob -fancies-> Mallory\n```\n\nGiven the above graph, if you follow any edge from `Bob` _outwards_ (which is default), you'll get the edges \n`Bob -fancies-> Mallory`. If you follow edges inwards, i.e. `direction=inwards`, you'll get `Alice -is-parent-> Bob`.\n\nThe traversal happens breadth first. See [limitations](#limitations) for more details.\n\nA traversal is defined by what edges to follow, what nodes to match, and what nodes to terminate traversal at.\n\nThis is controlled by `filter`, `nodeFilter` and `terminationFilter`.\n\n`filter` is a filter on edges. You would typically filter on the property `[edge, type]`, but any property on an edge \ncan be filtered on.\n\n`nodeFilter` is a node filter, which the node on the \"other\" side must match. With `direction: outwards`, that means \nthe \"end node\" of the edge must match. With `direction: inwards`, the \"start node\" must match.\n\n`terminationFilter` is similar to `nodeFilter`, except if it matches, traversal will end. A node must also match \n`nodeFilter` (if any) to steer the traversal to the node to terminate at in the first place.\n\n`maxDistance` controls how many hops away from the initial set traversal will go. `maxDistance` defaults to unlimited \n(but the set must respect its `limit`, defined on the result set expression). If `maxDistance` is 1, execution might \nbe faster, so if you know there will only be one level, it's worth configuring `maxDistance: 1`.\n\nFull options:\n\n- `from`: Result set expression to chain from.\n- `filter`: Edges traversed must match this filter.\n- `nodeFilter`: Nodes on the \"other\" side of the edge must match this filter.\n- `terminationFilter`. Do not traverse beyond nodes matching this filter.\n- `maxDistance`: How many levels to traverse. Default unlimited.\n- `direction`: Whether to traverse edges pointing out of the initial set, or _into_ the initial set.\n- `limitEach`: Limit the number of returned edges for each of the source nodes in the result set. The indicated uniform\nlimit applies to the result set from the referenced from. limitEach only has meaning when you also specify \nmaxDistance=1 and from.\n\n## Selects\nSelect configurations appear directly below `select` in a query. These specify which data to retrieve for the respective\nresult set expression. It specifies a number of sources (views) and a property selector for each of these. The property\nselectors define which view properties will be emitted in the query result.\n\nIt's possible to have sets whose properties are not emitted. This can be useful if the sets are necessary for chaining,\nbut not actually interesting to include in the final results. Sets that are neither chained nor selected\nwill not be executed (but will cause very slight query processing overhead)\n\nResults are grouped by their respective sets, and the results contain properties that match the property selectors for\nthe set.\n\n\n## Filters\n\nFilters define what a part of the query matches. Filters are tree structures where the operator comes first, and then \nthe parameters for that operator.\n\nA simple example is the `in` filter:\n\n```yaml\nin:\n property: [node, name]\n values: [movie]\n```\n\nIf the property `node.name`, which is text property, is equal to any of the values in the provided list, the node will \nmatch. Properties are typed. What query operators you can use on a property depends on its type.\n\nAn exhaustive list of filters and their descriptions can be found by examining the request body schema below.\n\n### Compound filters\n\nFilters can be combined with `and`/`or`/`not`:\n\n```yaml\nand:\n - not:\n in:\n property: [node, type]\n values: [movie]\n - range:\n property: [imdb, movie, released]\n gte: {parameter: start}\n```\n\nThis would correspond to `(NOT node.type in ('movie')) AND imdb.movie.released >= $start`.\n\n### HasData filter\nAlthough this filter is documentented in the request body schema, it merits a more detailed explanation. \nA `hasData` filters will match if data is present in a given set of containers or views.\n\nThere is an implicit `AND` between the containers and views referenced in the filter, so the filter will match\nif and only if the node/edge has data in _all_ of the specified containers and views.\n\nWhen a container is specified, the filter will match if the instance has all required properties populated\nfor that particular container. \n\nWhen a view is specified, the filter will match nodes with data in all of the containers which the view references \nthrough properties, respecting the filters of the view if defined (and the filters of views implemented by the view).\n\nExample:\n\n```yaml\nhasData:\n - type: container\n space: my_space\n externalId: my_container\n - type: view\n space: my_space\n externalId: my_view\n version: v1\n```\n\nIf `my_space.my_view.v1` maps properties in the containers `my_space.c1` and `my_space.c2`. The filter will match\nif there is data in `my_space.my_container AND (my_space.c1 AND my_space.c2)` if there is no filter defined on \n`my_space.my_view.v1`, and `my_space.my_container AND my_space.my_view.v1.filter` if there is a filter defined on\n`my_space.my_view.v1`.\n\n### Parameters\n\nValues in filters can be parameterised. Parameters are provided as part of the query object, and not in the filter \nitself.\n\nThis filter is parameterised:\n\n```yaml\nrange:\n property: [imdb, movie, released]\n gte: {parameter: start}\n```\n\nA query containing this filter will only run if the parameter `start` is provided. The parameter must be compatible \nwith all the types and operators that refer to the parameter. In the above example, the \"released\" property is a date. \nThus, the start parameter must be compatible with the date type, or the query will fail completely, even if the range \nfilter is optional because it's OR-ed\n___\n**TIP**\n\n Parameterise your filters!\nIt's a best practice to parameterise queries that take user input. This enables reusing query plans across queries, \nwhich will be noticable with read-heavy workloads.\n___\n\n\n## Sorting and Limiting\n\nSorting and limiting can happen in multiple places in a query:\n\n- In the result set expression, i.e. in the `with` object that defines a node or edge set.\n- In the result selection, i.e. under `select` where defined sets can be emitted as results.\n\nSorting and limiting the set definitions under `with` will transitively affect dependent sets.\n\nChanges to a set defined under `with` will naturally affect sets that depend on it, transitively. If you only change \nthe sort order of a `with` expression, dependent sets will not (necessarily) change (based on how the dependent sets \nare defined), but if you put a limit on an expression, all dependent sets will inherit this and change as a consequence.\n\nThis is also true for sets that aren't actually emitted via `select`, i.e. sets that are only defined as stepping-stones\nfor other sets.\n\nSorts and limits defined under `select` changes the result appearing order for that set only, and _not_ for depending \nsets.\n\nExample:\n\n```yaml\nwith:\n some_nodes:\n … # omitted. No sort here\n some_edges:\n from: some_nodes\n # omitted. also no sorting\n target_nodes:\n from: some_edges\n # …\nselect:\n some_nodes:\n properties: ...\n sort:\n - {property: [node, created], direction: descending}\n limit: 100\n```\n\nThe above query would still let `some_edges` and `target_nodes` pull from the full amount of nodes in `some_nodes`, \neven though what's returned as a result for `some_nodes` is capped at 100.\n\n### Order of sorting and limiting\n\n---\n**NOTE**\n\n A limit in an edge traversal applies to when to start traversing, which happens before sorting.\n\n---\nNodes and edges have subtly different sorting and limiting behaviour: Nodes sort and limit simultaneously, while \nrecursive edge exploration do limited traversal, _then_ sort.\n\nThe top-n set of nodes sorted by some property will be guaranteed to have the top-n of that property for the set.\n\nFor edges found through traversal, i.e. via `edges`, the `limit` applies to how many edges to discover. This may not \nbe all the edges that _could_ have been discovered in a full traversal. If you start traversing from some node and ask\nfor 100 edges sorted by creation timestamp, the 100 edges discovered before traversal stops get sorted. The full graph \nis _not_ traversed in order to find the 100 newest edges that exist in the graph defined by the traversal filters.\n\nTherefore, to do sorting with a recursive graph traversal, you'll need to specify the sort configuration via `postSort`.\n\nAn edge traversal with `maxDistance=1` can take a normal `sort` configuration, however.\n\n\n## Limitations\n\n### Graph traversal\nAny query that involves a graph traversal will force nested loop-style execution. This will work well enough for \ntraversals limited to a few hundred thousand unique paths.\n\nThe graph traversal is breadth first. All possible paths are traversed. This is important to keep in mind with \ntraversals across loops. For example, a fully connected graph will not do well in a query that follows all possible \npaths, and is very likely to be terminated due to constraints on either time, memory, or temporary disk usage.\n\n### Timeout errors\n\nQueries get cancelled with a 408 Request Timeout error if they take longer than the timeout.\nIf hitting a timeout like this you will need to reduce load or contention, or optimise your query.",
"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"
}
}
}
},
"/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.",
"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"
}
}
}
},
"/events": {
"post": {
"tags": [
"Events"
],
"summary": "Create events",
"description": "Creates multiple event objects in the same project. It is possible to post a maximum of 1000 events per request.",
"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/partition"
},
{
"$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": "event_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",
"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": "event_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. \nIt is a subject of the new throttling schema (limited 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\"})\naggregate_subtype = client.events.aggregate_unique_values(filter={\"type\": \"failure\"}, fields=[\"subtype\"])\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.\n\nA maximum of 1000 event IDs may be listed per request and all of them must be unique.",
"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.\n\nFor primitive fields (String, Long, Int), use 'set': 'value' to update value; use 'setNull': true to set that field to null.\n\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.\n\nA maximum of 1000 events can be updated per request, and all of the event IDs must be unique.",
"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.",
"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 upload link for a file.\n\nTo upload the file, use the uploadUrl link in the response in a separate request. \nTo upload a file, send an HTTP PUT request to the uploadUrl 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.",
"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"
}
]
},
"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/partition"
}
],
"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"
},
{
"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"
}
]
}
},
"/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(name=\"myfunction\", folder=\"path/to/code\", function_path=\"path/to/function.py\")\n\nfunction = client.functions.create(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=\"1\")\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 3D file",
"description": "Retrieve the contents of a 3D file.\n\nThis endpoint supported 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/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 }\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.",
"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.",
"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": "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.",
"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.",
"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": "res = 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": "A time series with the specified `externalId` already exists.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalIdsAlreadyExistResponse"
}
}
}
},
"422": {
"description": "ExternalIds duplicated.",
"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": "IDs duplicated.",
"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": "Retrieves a list of time series that match the given criteria.\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| `[\"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",
"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": "res = 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\"})\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 `externalId` already exists.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalIdsAlreadyExistResponse"
}
}
}
},
"422": {
"description": "IDs duplicated.",
"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": "IDs duplicated.",
"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": "IDs or external IDs duplicated.",
"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/subscriptions": {
"post": {
"tags": [
"Data point subscriptions"
],
"summary": "Create subscriptions",
"description": "Create one or more subscriptions that can be used to listen for changes in data points for a set of time series.\nAll subscription endpoints require experimental acl access, USE the `timeseries-subscription` experiment.\nContact cognite support for more information.\n\nIn beta. Available only when the `cdf-version` header with the value `beta` is provided.",
"operationId": "postSubscriptions",
"requestBody": {
"description": "The subscriptions to create.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "A list of subscriptions that were created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListSubscriptionDTO"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:WRITE"
]
},
"get": {
"tags": [
"Data point subscriptions"
],
"summary": "List subscriptions",
"description": "List all subscriptions for the tenant. Use nextCursor to paginate through the results.",
"operationId": "listSubscriptions",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Limit on the number of results to return.",
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer",
"format": "int32",
"default": 100
}
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"responses": {
"200": {
"description": "A complete list of subscriptions in the tenant.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListSubscriptionDTOWithCursor"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:READ"
]
}
},
"/timeseries/subscriptions/members": {
"get": {
"tags": [
"Data point subscriptions"
],
"summary": "List subscription members",
"description": "List all member time series for a subscription. Use nextCursor to paginate through the results.",
"operationId": "listSubscriptionMembers",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Limit on the number of results to return.",
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer",
"format": "int32",
"default": 100
}
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "externalId",
"description": "External id of the subscription.",
"in": "query",
"schema": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
],
"responses": {
"200": {
"description": "A complete list of member time series in the subscription.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListSubscriptionMemberDTOWithCursor"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:READ"
]
}
},
"/timeseries/subscriptions/byids": {
"post": {
"tags": [
"Data point subscriptions"
],
"summary": "Retrieve subscriptions",
"description": "Retrieve one or more subscriptions by external ID.",
"operationId": "getSubscriptionsByIds",
"requestBody": {
"description": "Specify a list of the subscriptions to retrieve.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsByIdsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The retrieved subscriptions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListSubscriptionDTO"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:READ"
]
}
},
"/timeseries/subscriptions/update": {
"post": {
"tags": [
"Data point subscriptions"
],
"summary": "Update subscriptions",
"description": "Updates one or more subscriptions. Fields that are not included in the request, are not changed.",
"operationId": "updateSubscriptions",
"requestBody": {
"description": "The subscriptions to update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "A list of subscriptions updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListSubscriptionDTO"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:WRITE"
]
}
},
"/timeseries/subscriptions/delete": {
"post": {
"tags": [
"Data point subscriptions"
],
"summary": "Delete subscriptions",
"description": "Delete subscription(s). This operation cannot be undone",
"operationId": "deleteSubscriptions",
"requestBody": {
"description": "Specify a list of the subscriptions to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsLookupById"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
},
"400": {
"description": "IDs not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:WRITE"
]
}
},
"/timeseries/subscriptions/data/list": {
"post": {
"tags": [
"Data point subscriptions"
],
"summary": "List subscription data",
"description": "Fetch the next batch of data from a given subscription and partition(s). Data can be ingested datapoints and time ranges where data is deleted. This endpoint will also return changes to the subscription itself, that is, if time series are added or removed from the subscription.",
"operationId": "listSubscriptionData",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsListDataRequest"
}
}
}
},
"responses": {
"200": {
"description": "A batch of data from the subscription.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsListDataResponse"
}
}
}
}
},
"x-capability": [
"timeSeriesSubscriptionsAcl:READ"
]
}
},
"/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\n**Note** There is no rollback if an error occurs, which means partial data may be written. However, it's safe to retry the request, since this endpoint supports both update and insert (upsert).\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",
"responses": {
"200": {
"$ref": "#/components/responses/ProjectListResponse"
}
}
}
},
"/projects/{projectName}": {
"parameters": [
{
"$ref": "#/components/parameters/projectName"
}
],
"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');"
}
]
}
},
"/projects/{projectName}/update": {
"parameters": [
{
"$ref": "#/components/parameters/projectName"
}
],
"post": {
"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": "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"
]
}
},
"/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": "res = 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 = [{\"valueType\":\"STRING\",\"externalId\":\"user\",\"description\":\"some description\"}, {\"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": "Retrieves a list of sequences that match the given criteria.\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",
"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": "res = 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\"})\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=0, 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=0, 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=0, rows=[1,2,42])\nclient.sequences.data.delete_range(id=0, 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-all capabilities can access data sent to this endpoint.\nSupported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff.",
"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.",
"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"
]
}
},
"/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](#operation/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 }]);"
}
]
}
},
"/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": "// get an existing job, wait for it to complete, and get the results\nconst { items } = await client.vision.getExtractJob(1, true);\nitems.forEach((item) => {\n const predictions = item.predictions;\n // do something with the predictions\n})"
}
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
},
"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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
},
"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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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"
]
}
},
"/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 ) \n .setSourceApiKey(\"TestApiKey\") \n .setDestinationApiKey(\"TestApiKey\"); \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": "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"
]
}
},
"/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"
]
}
},
"/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"
}
}
}
},
"/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"
}
}
}
},
"/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"
}
}
}
},
"/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"
]
}
},
"/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"
]
}
},
"/annotations/reverselookup": {
"post": {
"tags": [
"Annotations"
],
"summary": "Reverse lookup",
"description": "Provided an annotation filter and an annotated resource type (file/3D), returns ids of annotated resources\nhaving annotations matching the filter. A typical use case is looking up files with annotations linking to a\nspecific asset. Only ids of annotated resources that the client has access to will be returned.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"operationId": "annotationsReverseLookup",
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ReverseLookupRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2ReverseLookupSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
]
}
},
"/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"
],
"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": "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"
}
}
}
}
}
}
},
"/profiles/me": {
"get": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"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"
}
}
}
}
}
}
},
"/profiles/byids": {
"post": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"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"
}
}
}
}
}
}
},
"/profiles/search": {
"post": {
"x-capability": [
"userProfilesAcl:READ"
],
"tags": [
"User profiles"
],
"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"
}
}
}
}
}
}
}
},
"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": "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": "Model Hosting Capability",
"properties": {
"modelHostingAcl": {
"$ref": "#/components/schemas/modelhosting_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": "array",
"title": "projects",
"items": {
"type": "object",
"required": [
"urlName"
],
"properties": {
"urlName": {
"type": "string",
"description": "Project URL name to which the capabilities apply"
}
}
}
}
]
},
"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"
}
}
}
},
"ArrayPatchString": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/ArrayPatchStringSet"
},
{
"$ref": "#/components/schemas/ArrayPatchStringAddOrRemove"
}
],
"description": "Change that will be applied to the array."
},
"SinglePatchBoolean": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"type": "boolean"
}
}
},
"JsonArrayInt64": {
"type": "string",
"format": "jsonArray(int64)",
"example": "[1238712837, 238712361376, 23786237623]"
},
"JsonArrayString": {
"type": "string",
"format": "jsonArray(string)"
},
"EpochTimestamp": {
"description": "The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.",
"type": "integer",
"minimum": 0,
"format": "int64"
},
"EpochTimestampRange": {
"description": "Range between two timestamps (inclusive).",
"type": "object",
"properties": {
"max": {
"description": "Maximum timestamp (inclusive). The timestamp is represented as number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.",
"type": "integer",
"minimum": 0,
"format": "int64"
},
"min": {
"description": "Minimum timestamp (inclusive). The timestamp is represented as number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.",
"type": "integer",
"minimum": 0,
"format": "int64"
}
}
},
"IsNull": {
"type": "object",
"properties": {
"isNull": {
"type": "boolean",
"example": true,
"description": "Set to true if you want to search for data with field value not set, false to search for cases where some value is present."
}
}
},
"Partition": {
"description": "Splits the data set into `N` partitions. \nThe attribute is specified as a \"M/N\" string, where `M` is a natural number in the interval of `[1, N]`.\nYou need to follow the cursors within each partition in order to receive all the data.\n\nTo prevent unexpected problems and maximize read throughput, you should at most use 10 (N <= 10) partitions.\n\nWhen using more than 10 partitions, CDF may reduce the number of partitions silently.\nFor example, CDF may reduce the number of partitions to `K = 10` so if you specify an `X/N` `partition` value where `X = 8` and `N = 20` - i.e. `\"partition\": \"8/20\"`- then\nCDF will change `N` to `N = K = 10` and process the request. \nBut if you specify the `X/N` `partition` value where `X = 11` (`X > K`) and `N = 20` - i.e. `\"partition\": \"11/20\"`- then\nCDF will reply with an empty result list and no cursor in the response. \n\nIn future releases of the resource APIs, Cognite may reject requests if you specify more than 10 partitions.\nWhen Cognite enforces this behavior, the requests will result in a 400 Bad Request status.\n",
"type": "string",
"example": "1/10"
},
"PartitionObject": {
"type": "object",
"properties": {
"partition": {
"$ref": "#/components/schemas/Partition"
}
}
},
"Cursor": {
"description": "Cursor for paging through results.",
"type": "object",
"properties": {
"cursor": {
"type": "string",
"example": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}
}
},
"SetLongField": {
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"type": "integer",
"format": "int64"
}
}
},
"SetStringField": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"type": "string"
}
}
},
"SetIntegerField": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"type": "integer"
}
}
},
"SetBooleanField": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"type": "boolean"
}
}
},
"GeoLocationFilter": {
"description": "Only include files matching the specified geographic relation.",
"type": "object",
"required": [
"relation",
"shape"
],
"properties": {
"relation": {
"type": "string",
"enum": [
"INTERSECTS",
"DISJOINT",
"WITHIN"
],
"description": "One of the supported queries."
},
"shape": {
"type": "object",
"description": "Represents the points, curves and surfaces in the coordinate space.",
"oneOf": [
{
"$ref": "#/components/schemas/Point"
},
{
"$ref": "#/components/schemas/LineString"
},
{
"$ref": "#/components/schemas/Polygon"
},
{
"$ref": "#/components/schemas/MultiLineString"
},
{
"$ref": "#/components/schemas/MultiPolygon"
}
],
"discriminator": {
"propertyName": "type"
}
}
}
},
"GeoLocationGeometry": {
"type": "object",
"required": [
"type"
],
"description": "Represents the points, curves and surfaces in the coordinate space.",
"oneOf": [
{
"$ref": "#/components/schemas/Point"
},
{
"$ref": "#/components/schemas/LineString"
},
{
"$ref": "#/components/schemas/Polygon"
},
{
"$ref": "#/components/schemas/MultiPoint"
},
{
"$ref": "#/components/schemas/MultiLineString"
},
{
"$ref": "#/components/schemas/MultiPolygon"
}
],
"discriminator": {
"propertyName": "type"
}
},
"Point": {
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Point"
]
},
"coordinates": {
"$ref": "#/components/schemas/PointCoordinates"
}
}
},
"PointCoordinates": {
"description": "Coordinates of a point in 2D space, described as an array of 2 numbers.\n\nExample: `[4.306640625, 60.205710352530346]`\n",
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number"
}
},
"LineString": {
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"LineString"
]
},
"coordinates": {
"$ref": "#/components/schemas/LineStringCoordinates"
}
}
},
"LineStringCoordinates": {
"description": "Coordinates of a line described by a list of two or more points.\nEach point is defined as a pair of two numbers in an array, representing coordinates of a point in 2D space.\n\nExample: `[[30, 10], [10, 30], [40, 40]]`\n",
"type": "array",
"minItems": 2,
"items": {
"$ref": "#/components/schemas/PointCoordinates"
}
},
"Polygon": {
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Polygon"
]
},
"coordinates": {
"$ref": "#/components/schemas/PolygonCoordinates"
}
}
},
"PolygonCoordinates": {
"description": "List of one or more linear rings representing a shape.\n\nA linear ring is the boundary of a surface or the boundary of a hole in a surface. It is defined as a list consisting of 4 or more Points, where the first and last Point is equivalent.\n\nEach Point is defined as an array of 2 numbers, representing coordinates of a point in 2D space.\n\nExample: `[[[35, 10], [45, 45], [15, 40], [10, 20], [35, 10]], [[20, 30], [35, 35], [30, 20], [20, 30]]]`\n",
"type": "array",
"minItems": 2,
"items": {
"$ref": "#/components/schemas/LineStringCoordinates"
}
},
"MultiPoint": {
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"MultiPoint"
]
},
"coordinates": {
"$ref": "#/components/schemas/MultiPointCoordinates"
}
}
},
"MultiPointCoordinates": {
"description": "List of Points. Each Point is defined as an array of 2 numbers, representing coordinates of a point in 2D space.\n\nExample: `[[35, 10], [45, 45]]`\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/PointCoordinates"
}
},
"MultiLineString": {
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"MultiLineString"
]
},
"coordinates": {
"$ref": "#/components/schemas/MultiLineStringCoordinates"
}
}
},
"MultiLineStringCoordinates": {
"description": "List of lines where each line (LineString) is defined as a list of two or more points.\nEach point is defined as a pair of two numbers in an array, representing coordinates of a point in 2D space.\n\nExample: `[[[30, 10], [10, 30]], [[35, 10], [10, 30], [40, 40]]]`\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/LineStringCoordinates"
}
},
"MultiPolygon": {
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"MultiPolygon"
]
},
"coordinates": {
"$ref": "#/components/schemas/MultiPolygonCoordinates"
}
}
},
"MultiPolygonCoordinates": {
"description": "List of multiple polygons.\n\nEach polygon is defined as a list of one or more linear rings representing a shape.\n\nA linear ring is the boundary of a surface or the boundary of a hole in a surface. It is defined as a list consisting of 4 or more Points, where the first and last Point is equivalent.\n\nEach Point is defined as an array of 2 numbers, representing coordinates of a point in 2D space.\n\nExample: `[[[[30, 20], [45, 40], [10, 40], [30, 20]]], [[[15, 5], [40, 10], [10, 20], [5, 10], [15, 5]]]]`\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/PolygonCoordinates"
}
},
"GeoLocation": {
"description": "Geographic metadata.",
"required": [
"type",
"geometry"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Feature"
],
"description": "One of the GeoJSON types. Currently only the 'Feature' type is supported."
},
"geometry": {
"$ref": "#/components/schemas/GeoLocationGeometry"
},
"properties": {
"type": "object",
"description": "Additional properties in a String key -> Object value format."
}
}
},
"SinglePatchGeoLocation": {
"title": "set",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetGeoLocation"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the geoLocation, or remove the value."
},
"SetGeoLocation": {
"title": "set",
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"$ref": "#/components/schemas/GeoLocation"
}
}
},
"RemoveField": {
"title": "remove",
"type": "object",
"required": [
"setNull"
],
"properties": {
"setNull": {
"type": "boolean",
"example": true
}
}
},
"SetExternalId": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
},
"SetDataSetId": {
"type": "object",
"required": [
"set"
],
"properties": {
"set": {
"$ref": "#/components/schemas/DataSetId"
}
}
},
"SetDescription": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"$ref": "#/components/schemas/ResourceDescription"
}
}
},
"SinglePatchResourceDescription": {
"title": "set",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetDescription"
},
{
"$ref": "#/components/schemas/RemoveField"
}
]
},
"SinglePatchDataSetId": {
"title": "set",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetDataSetId"
},
{
"$ref": "#/components/schemas/RemoveField"
}
]
},
"SinglePatchExternalId": {
"title": "set",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetExternalId"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the externalId, or remove the value. Must be unique for the resource type."
},
"SinglePatchLong": {
"title": "set",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetLongField"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the long, or remove the value."
},
"ModifyPatchInteger": {
"title": "modify",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetIntegerField"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the integer, or remove the value"
},
"ModifyPatchBoolean": {
"title": "modify",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetBooleanField"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the boolean, or remove the value"
},
"SinglePatchString": {
"title": "set",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetStringField"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the string, or remove the value."
},
"SinglePatchRequiredString": {
"title": "set",
"type": "object",
"properties": {
"set": {
"type": "string"
}
},
"description": "Set a new value for the string.",
"required": [
"set"
]
},
"CogniteInternalId": {
"description": "A server-generated ID for the object.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"format": "int64"
},
"CogniteExternalId": {
"description": "The external ID provided by the client. Must be unique for the resource type.",
"type": "string",
"maxLength": 255,
"example": "my.known.id"
},
"CogniteExternalIdPrefix": {
"description": "Filter by this (case-sensitive) prefix for the external ID.",
"type": "string",
"maxLength": 255,
"example": "my.known.prefix"
},
"DataSetInternalId": {
"type": "object",
"title": "DataSetInternalId",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CogniteInternalId"
}
}
},
"DataSetExternalId": {
"type": "object",
"title": "DataSetExternalId",
"required": [
"externalId"
],
"properties": {
"externalId": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
},
"DataSetIdEither": {
"oneOf": [
{
"$ref": "#/components/schemas/DataSetInternalId"
},
{
"$ref": "#/components/schemas/DataSetExternalId"
}
]
},
"DataSetIdEithers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataSetIdEither"
}
},
"DataSetId": {
"description": "The dataSet Id for the item.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"format": "int64"
},
"TimestampOrStringStart": {
"oneOf": [
{
"type": "integer",
"default": 0
},
{
"type": "string"
}
],
"description": "Get datapoints starting from, and including, this time. The format is N[timeunit]-ago where\ntimeunit is w,d,h,m,s. Example: '2d-ago' gets datapoints that are up to 2 days\nold. You can also specify time in milliseconds since epoch. Note that for aggregates, the start time is rounded down to a whole granularity unit (in UTC timezone). Daily granularities (d)\nare rounded to 0:00 AM; hourly granularities (h) to the start of the hour, etc."
},
"TimestampOrStringEnd": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string",
"default": "now"
}
],
"description": "Get datapoints up to, but excluding, this point in time. Same format as for start. Note that when using aggregates, the end will be rounded up such that the last aggregate represents a full aggregation interval containing the original end, where the interval is the granularity unit times the granularity multiplier. For granularity 2d, the aggregation interval is 2 days, if end was originally 3 days after the start, it will be rounded to 4 days after the start."
},
"CountAggregateResult": {
"description": "Common aggregate structure to represent aggregate result which have one count for filter resultset (Documents Count, Property Cardinality, etc).",
"title": "CountResult",
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"count"
],
"properties": {
"count": {
"type": "integer",
"description": "Number of items in this aggregation group.",
"format": "int64"
}
}
}
}
},
"example": {
"items": [
{
"count": 10
}
]
}
},
"StringValue": {
"title": "String",
"description": "A unique string value in the field.",
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "string"
}
}
},
"AggregateStringValues": {
"title": "Strings",
"type": "object",
"required": [
"count",
"values"
],
"properties": {
"count": {
"description": "Number of items in this aggregation bucket.",
"type": "integer",
"format": "int64"
},
"values": {
"description": "An array of unique string values in the property.",
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "string"
}
},
"value": {
"deprecated": true,
"description": "A unique string value in the field.",
"type": "string"
}
}
},
"AggregateIntegerValues": {
"title": "Integers",
"type": "object",
"required": [
"count",
"values"
],
"properties": {
"count": {
"description": "Number of items in this aggregation bucket.",
"type": "integer",
"format": "int64"
},
"values": {
"description": "An array of unique integer values in the property.",
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "integer",
"format": "int64"
}
},
"value": {
"deprecated": true,
"description": "A unique integer value in the field.",
"type": "integer",
"format": "int64"
}
}
},
"AggregatePropertyValues": {
"title": "Properties",
"description": "A single bucket to represent `uniqueProperties` aggregate result.\n",
"type": "object",
"required": [
"count",
"values"
],
"properties": {
"count": {
"description": "Number of items in this aggregation bucket.",
"type": "integer",
"format": "int64"
},
"values": {
"description": "An array of unique properties for UniqueProperties aggregate.\n",
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"$ref": "#/components/schemas/AggregateProperty"
}
},
"example": {
"property": [
"metadata",
"key1"
]
}
}
},
"value": {
"deprecated": true,
"description": "A unique property for UniqueProperties aggregate.\n",
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"$ref": "#/components/schemas/AggregateProperty"
}
}
}
}
},
"ValuesAggregateResult": {
"description": "Common aggregate structure to represent aggregate result which have count buckets for filter resultset (Unique Property Values, Not Null Document Properties, etc).",
"title": "BucketsResult",
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AggregateStringValues"
},
{
"$ref": "#/components/schemas/AggregateIntegerValues"
},
{
"$ref": "#/components/schemas/AggregatePropertyValues"
}
]
}
}
},
"example": {
"items": [
{
"count": 5,
"values": [
"value_1"
]
},
{
"count": 10,
"values": [
"value_2"
]
}
]
}
},
"AggregateResult": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/CountAggregateResult"
},
{
"$ref": "#/components/schemas/ValuesAggregateResult"
}
]
},
"Label": {
"type": "object",
"title": "Label",
"required": [
"externalId"
],
"description": "A label assigned to a resource.",
"properties": {
"externalId": {
"description": "An external ID to a predefined label definition.",
"allOf": [
{
"$ref": "#/components/schemas/CogniteExternalId"
}
]
}
}
},
"LabelList": {
"type": "array",
"description": "A list of the labels associated with this resource item.",
"minItems": 0,
"maxItems": 10,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/Label"
}
},
"LabelFilter": {
"description": "Return only the resource matching the specified label constraints.",
"oneOf": [
{
"$ref": "#/components/schemas/LabelContainsAnyFilter"
},
{
"$ref": "#/components/schemas/LabelContainsAllFilter"
}
]
},
"LabelContainsAnyFilter": {
"type": "object",
"required": [
"containsAny"
],
"properties": {
"containsAny": {
"description": "The resource item contains at least one of the listed labels.",
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"LabelContainsAllFilter": {
"type": "object",
"required": [
"containsAll"
],
"properties": {
"containsAll": {
"description": "The resource item contains at least all the listed labels.",
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"LabelDefinitionExternalId": {
"type": "object",
"required": [
"externalId"
],
"properties": {
"externalId": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
},
"LabelDefinitionExternalIdList": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/LabelDefinitionExternalId"
}
}
}
},
"LabelsPatch": {
"description": "Updates the resource's assigned labels.\n\nLabels can be added, removed or replaced (set). Adding an already attached label is an idempotent operation. Removing a label with no matching externalId is silently ignored.",
"oneOf": [
{
"$ref": "#/components/schemas/LabelsAddRemove"
},
{
"$ref": "#/components/schemas/LabelsSet"
}
]
},
"LabelsAddRemove": {
"type": "object",
"properties": {
"add": {
"type": "array",
"description": "A list of the labels to add to a resource.",
"minItems": 0,
"maxItems": 10,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/Label"
}
},
"remove": {
"type": "array",
"description": "A list of the labels to remove from a resource.",
"minItems": 0,
"maxItems": 10,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"LabelsSet": {
"type": "object",
"properties": {
"set": {
"type": "array",
"description": "A list of the labels to replace (set) to a resource.",
"minItems": 0,
"maxItems": 10,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"EqualsFilter": {
"type": "object",
"title": "equals",
"required": [
"equals"
],
"properties": {
"equals": {
"required": [
"property",
"value"
],
"description": "Matches items where the given property is **exactly** equal to the given value.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"value": {
"$ref": "#/components/schemas/Value"
}
}
}
}
},
"InFilter": {
"type": "object",
"title": "in",
"required": [
"in"
],
"properties": {
"in": {
"required": [
"property",
"values"
],
"description": "Matches items where the given property is **exactly** equal to one of the given values. This filter can only be applied to single-valued properties.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"values": {
"$ref": "#/components/schemas/Values"
}
}
}
}
},
"GenericRangeFilter": {
"type": "object",
"title": "range",
"required": [
"range"
],
"properties": {
"range": {
"required": [
"property"
],
"description": "Matches items that contain terms within the provided range.\nIt is not allowed to specify both inclusive and exclusive bounds (such as `gte`, `gt`) together.\n`gte`: Greater than or equal to.\n`gt`: Greater than.\n`lte`: Less than or equal to.\n`lt`: Less than.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"gte": {
"$ref": "#/components/schemas/RangeValue"
},
"gt": {
"$ref": "#/components/schemas/RangeValue"
},
"lte": {
"$ref": "#/components/schemas/RangeValue"
},
"lt": {
"$ref": "#/components/schemas/RangeValue"
}
}
}
}
},
"PrefixFilter": {
"type": "object",
"title": "prefix",
"required": [
"prefix"
],
"properties": {
"prefix": {
"required": [
"property",
"value"
],
"description": "Matches items that contain a specific prefix in the provided property.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"value": {
"$ref": "#/components/schemas/StringValue"
}
}
}
}
},
"AggregateInFilter": {
"type": "object",
"title": "in",
"required": [
"in"
],
"properties": {
"in": {
"required": [
"values"
],
"description": "Matches items where the given property is **exactly** equal to one of the given values. This filter can only be applied to single-valued properties.\n",
"type": "object",
"properties": {
"values": {
"$ref": "#/components/schemas/Values"
}
}
}
}
},
"AggregatePrefixFilter": {
"type": "object",
"title": "prefix",
"required": [
"prefix"
],
"properties": {
"prefix": {
"required": [
"value"
],
"description": "Matches aggregate values that contain a specific prefix.\n",
"type": "object",
"properties": {
"value": {
"$ref": "#/components/schemas/StringValue"
}
}
}
}
},
"AggregateRangeFilter": {
"type": "object",
"title": "range",
"required": [
"range"
],
"properties": {
"range": {
"description": "Matches items that contain terms within the provided range.\nIt's not allowed to specify both inclusive and exclusive bounds (such as `gte`, `gt`) together.\n`gte`: Greater than or equal to.\n`gt`: Greater than.\n`lte`: Less than or equal to.\n`lt`: Less than.\n",
"type": "object",
"properties": {
"gte": {
"$ref": "#/components/schemas/RangeValue"
},
"gt": {
"$ref": "#/components/schemas/RangeValue"
},
"lte": {
"$ref": "#/components/schemas/RangeValue"
},
"lt": {
"$ref": "#/components/schemas/RangeValue"
}
}
}
}
},
"ExistsFilter": {
"type": "object",
"title": "exists",
"required": [
"exists"
],
"properties": {
"exists": {
"required": [
"property"
],
"description": "Will match items that have a value in the specified property.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
}
}
}
}
},
"ContainsAnyFilter": {
"type": "object",
"title": "containsAny",
"required": [
"containsAny"
],
"properties": {
"containsAny": {
"required": [
"property",
"values"
],
"description": "Matches items where the property contains one or more of the given values.\nThis filter can only be applied to multivalued properties.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"values": {
"$ref": "#/components/schemas/Values"
}
}
}
}
},
"ContainsAllFilter": {
"type": "object",
"title": "containsAll",
"required": [
"containsAll"
],
"properties": {
"containsAll": {
"required": [
"property",
"values"
],
"description": "Matches items where the property contains all the given values.\nThis filter can only be applied to multivalued properties.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"values": {
"$ref": "#/components/schemas/Values"
}
}
}
}
},
"SearchFilter": {
"type": "object",
"title": "search",
"required": [
"search"
],
"properties": {
"search": {
"required": [
"property",
"value"
],
"description": "Fuzzy search in the specified property. Introduced to provide functional parity with `/search` endpoints.\n",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"value": {
"$ref": "#/components/schemas/Value"
}
}
}
}
},
"FilterProperty": {
"description": "Property you want to filter. Use a list of strings to specify nested properties.\n\n<u>Example:</u>\n\nYou have the object \n```\n{\n \"room\": {\n \"id\": \"b53\"\n }, \n \"roomId\": \"a23\"\n}\n```\n\nUse `[\"room\", \"id\"]` to return the value in the nested `id` property, which is a part of the `room` object. \n\nYou can also read the value(s) in the standalone property `roomId` with `[\"roomId\"]`.\n",
"type": "array",
"minItems": 1,
"maxItems": 3,
"items": {
"type": "string"
}
},
"AggregateProperty": {
"description": "Property you want to aggregate.\nUse a list of strings to specify nested properties.\nThe same way the properties are represented in aggregate responses.\n\n<u>Example:</u>\n\nYou have the object \n```\n{\n \"metadata\": {\n \"id\": \"b53\"\n }, \n \"source\": \"a23\"\n}\n```\n\nTo address \"id\" metadata key use `[\"metadata\", \"id\"]` property. \nYou can also aggregate the value(s) for the standalone property `source` with `[\"source\"]`.\n",
"type": "array",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "string"
},
"example": [
"metadata",
"key1"
]
},
"Value": {
"description": "Value you wish to find in the provided property.",
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "boolean"
}
]
},
"Values": {
"description": "One or more values you wish to find in the provided property.",
"type": "array",
"minItems": 1,
"maxItems": 5000,
"items": {
"$ref": "#/components/schemas/Value"
}
},
"RangeValue": {
"description": "Value you wish to find in the provided property using a range clause.",
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
}
]
},
"MatchAllFilter": {
"type": "object",
"title": "matchAll",
"required": [
"matchAll"
],
"properties": {
"matchAll": {
"description": "All the listed items must match the clause.",
"type": "object"
}
}
},
"AssetName": {
"type": "string",
"description": "The name of the asset.",
"minLength": 1,
"maxLength": 140
},
"AssetDescription": {
"type": "string",
"description": "The description of the asset.",
"maxLength": 500
},
"AssetQuery": {
"type": "string",
"description": "Whitespace-separated terms to search for in assets. Does a best-effort fuzzy search in relevant fields (currently name and description) for variations of any of the search terms, and orders results by relevance. Uses a different search algorithm than the name and description parameters, and will generally give much better results. Matching and ordering is not guaranteed to be stable over time, and the fields being searched may be extended.",
"minLength": 1,
"maxLength": 140
},
"AssetMetadata": {
"type": "object",
"description": "Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.",
"additionalProperties": {
"type": "string",
"maxLength": 10240
},
"x-maxKeyLength": 128,
"x-maxTotalSize": 10240,
"maxProperties": 256
},
"AssetParentExternalId": {
"description": "The external ID of the parent. This will be resolved to an internal ID and stored as `parentId`.",
"type": "string",
"maxLength": 255,
"example": "my.known.id"
},
"AssetSource": {
"type": "string",
"maxLength": 128,
"description": "The source of the asset."
},
"SetAssetSource": {
"type": "object",
"title": "set",
"required": [
"set"
],
"properties": {
"set": {
"$ref": "#/components/schemas/AssetSource"
}
}
},
"AssetInternalId": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CogniteInternalId"
}
}
},
"AssetExternalId": {
"type": "object",
"required": [
"externalId"
],
"properties": {
"externalId": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
},
"AssetIdEither": {
"oneOf": [
{
"$ref": "#/components/schemas/AssetInternalId"
},
{
"$ref": "#/components/schemas/AssetExternalId"
}
]
},
"AssetIdentifier": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CogniteInternalId"
}
}
},
"DeleteRequest": {
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetIdEither"
},
"maxItems": 1000,
"minItems": 1
},
"recursive": {
"description": "Recursively delete all asset subtrees under the specified IDs.",
"type": "boolean",
"default": false
}
}
},
{
"$ref": "#/components/schemas/IgnoreUnknownIdsField"
}
]
},
"AssetDataIds": {
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetIdEither"
},
"maxItems": 1000,
"minItems": 1
}
}
},
{
"$ref": "#/components/schemas/IgnoreUnknownIdsField"
},
{
"$ref": "#/components/schemas/AggregatedProperties"
}
]
},
"ExternalAsset": {
"type": "object",
"required": [
"name"
],
"properties": {
"externalId": {
"$ref": "#/components/schemas/CogniteExternalId"
},
"name": {
"$ref": "#/components/schemas/AssetName"
},
"parentId": {
"description": "The parent node's ID used to specify parent-child relationship.\n\nYou should not use this field in combination with the parentExternalId field.\n",
"allOf": [
{
"$ref": "#/components/schemas/CogniteInternalId"
}
]
},
"parentExternalId": {
"description": "The parent node's external ID used to specify the parent-child relationship.\nWhen specifying this field, the API will resolve the external ID into an internal ID and use the internal ID to store the parent-child relation.\nAs a result, a later change to update the parent's external ID will not affect this parent-child relationship as it is based on internal ID.\n\nYou should not use this field in combination with the parentId field.\n",
"allOf": [
{
"$ref": "#/components/schemas/CogniteExternalId"
}
]
},
"description": {
"$ref": "#/components/schemas/AssetDescription"
},
"dataSetId": {
"description": "The id of the dataset this asset belongs to.",
"allOf": [
{
"$ref": "#/components/schemas/CogniteInternalId"
}
]
},
"metadata": {
"$ref": "#/components/schemas/AssetMetadata"
},
"source": {
"$ref": "#/components/schemas/AssetSource"
},
"labels": {
"$ref": "#/components/schemas/LabelList"
},
"geoLocation": {
"$ref": "#/components/schemas/GeoLocation"
}
},
"description": "A representation of a physical asset, for example a factory or a piece of equipment."
},
"Asset": {
"allOf": [
{
"type": "object",
"required": [
"rootId",
"createdTime",
"lastUpdatedTime"
],
"properties": {
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"rootId": {
"description": "The ID of the root asset. The root asset is the asset spanning the entire asset hierarchy that this asset belongs to.",
"allOf": [
{
"$ref": "#/components/schemas/CogniteInternalId"
}
]
},
"aggregates": {
"$ref": "#/components/schemas/AggregateResultItem"
},
"parentId": {
"description": "The ID of the parent of this node, null if it is the root node.",
"allOf": [
{
"$ref": "#/components/schemas/CogniteInternalId"
}
]
},
"parentExternalId": {
"description": "The external ID of the parent. The property is omitted if the asset doesn't have a parent or if the parent doesn't have externalId.",
"allOf": [
{
"$ref": "#/components/schemas/CogniteExternalId"
}
]
}
}
},
{
"$ref": "#/components/schemas/ExternalAsset"
},
{
"$ref": "#/components/schemas/AssetInternalId"
}
]
},
"AggregateResultItem": {
"description": "Aggregated metrics of the asset.",
"type": "object",
"properties": {
"childCount": {
"type": "integer",
"description": "Number of direct descendants for the asset.",
"format": "int32",
"minimum": 0
},
"depth": {
"type": "integer",
"description": "Asset path depth (number of levels below root node).",
"format": "int32",
"minimum": 0
},
"path": {
"description": "IDs of assets on the path to the asset.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetIdentifier"
}
}
}
},
"DataAsset": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Asset"
}
}
}
},
"DataAssetChange": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetChange"
},
"minItems": 1,
"maxItems": 1000
}
}
},
"DataExternalAssetItem": {
"allOf": [
{
"$ref": "#/components/schemas/ExternalAsset"
},
{
"type": "object",
"properties": {
"parentExternalId": {
"$ref": "#/components/schemas/AssetParentExternalId"
}
}
}
]
},
"DataExternalAsset": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataExternalAssetItem"
},
"minItems": 1,
"maxItems": 1000
}
}
},
"DataWithCursorAsset": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Asset"
}
},
"nextCursor": {
"type": "string",
"description": "The cursor to get the next page of results (if available)."
}
},
"description": "A list of objects along with possible cursors to get the next or previous page of results."
},
"AggregatedProperty": {
"type": "string",
"enum": [
"childCount",
"path",
"depth"
]
},
"AggregatedProperties": {
"type": "object",
"properties": {
"aggregatedProperties": {
"description": "Set of aggregated properties to include",
"type": "array",
"items": {
"$ref": "#/components/schemas/AggregatedProperty"
}
}
}
},
"AssetFilter": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"description": "Filter on assets with strict matching.",
"title": "Filter",
"properties": {
"name": {
"$ref": "#/components/schemas/AssetName"
},
"parentIds": {
"description": "Return only the direct descendants of the specified assets.",
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/CogniteInternalId"
}
},
"parentExternalIds": {
"description": "Return only the direct descendants of the specified assets.",
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/CogniteExternalId"
}
},
"rootIds": {
"description": "This parameter is deprecated. Use `assetSubtreeIds` instead. Only include these root assets and their descendants.",
"deprecated": true,
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/AssetIdEither"
}
},
"assetSubtreeIds": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Only include assets in subtrees rooted at the specified assets (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.",
"items": {
"$ref": "#/components/schemas/AssetIdEither"
}
},
"dataSetIds": {
"type": "array",
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/DataSetIdEither"
}
},
"metadata": {
"$ref": "#/components/schemas/AssetMetadata"
},
"source": {
"$ref": "#/components/schemas/AssetSource"
},
"createdTime": {
"$ref": "#/components/schemas/EpochTimestampRange"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestampRange"
},
"root": {
"type": "boolean",
"description": "Whether the filtered assets are root assets, or not. Set to True to only list root assets."
},
"externalIdPrefix": {
"$ref": "#/components/schemas/CogniteExternalIdPrefix"
},
"labels": {
"$ref": "#/components/schemas/LabelFilter"
},
"geoLocation": {
"$ref": "#/components/schemas/GeoLocationFilter"
}
}
}
}
},
"AssetLimit": {
"type": "object",
"properties": {
"limit": {
"description": "Limits the number of results to return.",
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 1000,
"default": 100
}
}
},
"AssetSort": {
"type": "object",
"properties": {
"sort": {
"description": "Sort by array of selected properties.\n",
"type": "array",
"minItems": 1,
"maxItems": 2,
"items": {
"$ref": "#/components/schemas/AssetSortProperty"
},
"example": [
{
"property": [
"createdTime"
],
"order": "desc"
},
{
"property": [
"metadata",
"customMetadataKey"
],
"nulls": "first"
}
]
}
}
},
"AssetSortProperty": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "array",
"description": "Property to sort on.\nSorting can be done on the following properties:\n | Property |\n |---------------------------------|\n | `[\"createdTime\"]` |\n | `[\"dataSetId\"]` |\n | `[\"description\"]` |\n | `[\"externalId\"]` |\n | `[\"lastUpdatedTime\"]` |\n | `[\"metadata\", \"someCustomKey\"]` |\n | `[\"name\"]` |\n | `[\"source\"]` |\n | `[\"_score_\"]` |",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "string"
}
},
"order": {
"type": "string",
"description": "The `order` attribute is optional and defaults to `desc` for `_score_` and `asc` for all other properties.",
"enum": [
"asc",
"desc"
]
},
"nulls": {
"type": "string",
"description": "The `nulls` attribute is optional and defaults to `auto`.\n`auto` is translated to `last` for the `asc` order and to `first` for the `desc` order by the service.",
"enum": [
"first",
"last",
"auto"
],
"default": "auto"
}
}
},
"AssetAggregateRequest": {
"description": "Aggregation request of assets. Filters behave the same way as for the `filter` endpoint. Default aggregation is `count`.",
"oneOf": [
{
"$ref": "#/components/schemas/AssetCountAggregate"
},
{
"$ref": "#/components/schemas/AssetWithPropertyCountAggregate"
},
{
"$ref": "#/components/schemas/AssetCardinalityValuesAggregate"
},
{
"$ref": "#/components/schemas/AssetCardinalityPropertiesAggregate"
},
{
"$ref": "#/components/schemas/AssetUniqueValuesAggregate"
},
{
"$ref": "#/components/schemas/AssetUniquePropertiesAggregate"
},
{
"$ref": "#/components/schemas/AssetMetadataKeysAggregate"
},
{
"$ref": "#/components/schemas/AssetMetadataValuesAggregate"
}
]
},
"AssetCardinalityValuesAggregate": {
"allOf": [
{
"type": "object",
"title": "ApproximateCardinalityForValues",
"description": "Request values approximate cardinality aggregate on a specific property.",
"required": [
"aggregate"
],
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`cardinalityValues`: Get approximate number of unique values for the specified property.\n",
"type": "string",
"enum": [
"cardinalityValues"
]
},
"aggregateFilter": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetAggregateProperties"
}
]
},
"AssetCardinalityPropertiesAggregate": {
"allOf": [
{
"type": "object",
"title": "ApproximateCardinalityForProperties",
"description": "Request resource properties approximate cardinality aggregate.",
"required": [
"aggregate"
],
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`cardinalityProperties`: Get approximate number of unique properties.\n",
"type": "string",
"enum": [
"cardinalityProperties"
]
},
"aggregateFilter": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"properties": {
"path": {
"description": "The scope in every document to aggregate properties.\nThe only value allowed now is [\"metadata\"].\nIt means to aggregate only metadata properties (aka keys).\n",
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "string",
"enum": [
"metadata"
]
},
"default": [
"metadata"
]
}
}
}
]
},
"AssetUniqueValuesAggregate": {
"allOf": [
{
"type": "object",
"title": "UniqueValues",
"description": "Request unique value buckets aggregate on a specific Asset property.\nEach bucket is defined by the `values` array and has the number of the `values` occurrences.",
"required": [
"aggregate"
],
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`uniqueValues`: Get unique values (up to max 1000) in the specified property ordered by the frequency.\nNote: When aggregate on the `[\"metadata\"]` property, a value may occur multiple times in one Asset for different metadata keys.\nEach occurrence is counted.\n",
"type": "string",
"enum": [
"uniqueValues"
]
},
"aggregateFilter": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetAggregateProperties"
}
]
},
"AssetUniquePropertiesAggregate": {
"allOf": [
{
"type": "object",
"title": "UniqueProperties",
"description": "Request unique non-null property buckets aggregate.",
"required": [
"aggregate"
],
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`uniqueProperties`: Get unique properties (up to max 1000) in the specified document path (default path is [\"metadata\"] - metadata keys only).\nOrdered by frequency.\n",
"type": "string",
"enum": [
"uniqueProperties"
]
},
"aggregateFilter": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"properties": {
"path": {
"description": "The scope in every document to aggregate properties.\nThe only value allowed now is [\"metadata\"].\nIt means to aggregate only metadata properties (aka keys).\n",
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "string",
"enum": [
"metadata"
]
},
"default": [
"metadata"
]
}
}
}
]
},
"AssetCountAggregate": {
"allOf": [
{
"type": "object",
"title": "AssetCount",
"description": "Request aggregate to count number of Assets matching the filters. Default aggregate for the endpoint.",
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`count`: Get approximate number of Assets matching the filters.\n",
"type": "string",
"enum": [
"count"
]
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
}
]
},
"AssetWithPropertyCountAggregate": {
"allOf": [
{
"type": "object",
"title": "AssetWithPropertyCount",
"description": "Request aggregate to count the number of Assets with the specific property (property is not null)\nand matching the filters.",
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`count`: Get an approximate number of Assets with the specific property (property is not null) and matching the filters.\n",
"type": "string",
"enum": [
"count"
]
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetAggregateProperties"
}
]
},
"AssetMetadataKeysAggregate": {
"deprecated": true,
"allOf": [
{
"type": "object",
"title": "MetadataKeys",
"description": "Get unique values (up to max 1000) of metadata keys ordered by frequency.",
"required": [
"aggregate"
],
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`metadataKeys`: Get unique values of metadata keys ordered by frequency.\n",
"type": "string",
"enum": [
"metadataKeys"
]
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
}
]
},
"AssetMetadataValuesAggregate": {
"deprecated": true,
"allOf": [
{
"type": "object",
"title": "MetadataValues",
"description": "Get unique values (up to max 1000) of values for a particular metadata key, ordered by frequency.",
"required": [
"aggregate",
"keys"
],
"properties": {
"aggregate": {
"description": "Type of aggregation to apply.\n`metadataValues`: Get unique values of values for a particular metadata key, ordered by frequency.\n",
"type": "string",
"enum": [
"metadataValues"
]
}
}
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetAggregateKeys"
}
]
},
"AssetAggregateProperties": {
"type": "object",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "array",
"description": "The property name(s) to apply the aggregation on. Currently limited to one property per request.",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "array",
"description": "It's an array of strings to allow specifying nested properties.\n Supported properties: \n | Property | Type |\n |---------------------------------|------------------------------|\n | `[\"dataSetId\"]` | number |\n | `[\"description\"]` | string |\n | `[\"labels\"]` | array of [string] |\n | `[\"name\"]` | string |\n | `[\"parentId\"]` | number |\n | `[\"rootId\"]` | number |\n | `[\"source\"]` | string |\n | `[\"metadata\"]` | string |\n | `[\"metadata\", <key>]` | string |",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"example": [
"parentId"
]
},
"filter": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
}
}
}
},
"AssetAggregateKeys": {
"type": "object",
"properties": {
"keys": {
"description": "For `metadataValues`, `aggregateType` sets the metadata key(s) to apply the aggregation on. Currently supports exactly one key per request.\n",
"type": "array",
"maxItems": 1,
"items": {
"type": "string"
}
}
}
},
"AssetListScope": {
"allOf": [
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetAdvancedFilter"
},
{
"$ref": "#/components/schemas/AssetLimit"
},
{
"$ref": "#/components/schemas/AssetSort"
},
{
"$ref": "#/components/schemas/Cursor"
},
{
"$ref": "#/components/schemas/AggregatedProperties"
},
{
"$ref": "#/components/schemas/PartitionObject"
}
]
},
"AssetAggregateFilter": {
"type": "object",
"description": "A filter DSL (Domain Specific Language) to define aggregate filter queries.\n\nSee more information about filtering DSL [here](https://docs.cognite.com/dev/concepts/resource_filtering_dsl/ \"filtering DSL\").\n",
"oneOf": [
{
"$ref": "#/components/schemas/AssetAggregateBoolFilter"
},
{
"$ref": "#/components/schemas/AssetAggregateLeafFilter"
}
],
"example": {
"or": [
{
"not": {
"and": [
{
"equals": {
"value": 10
}
},
{
"in": {
"values": [
11,
12
]
}
},
{
"range": {
"gte": 13,
"lt": 15
}
}
]
}
},
{
"and": [
{
"equals": {
"value": 42
}
}
]
}
]
}
},
"AssetAggregateLeafFilter": {
"description": "Aggregate leaf filter.",
"title": "AggregateLeafFilter",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AggregateInFilter"
},
{
"$ref": "#/components/schemas/AggregatePrefixFilter"
},
{
"$ref": "#/components/schemas/AggregateRangeFilter"
}
]
},
"AssetAggregateBoolFilter": {
"description": "A query that matches items matching boolean combinations of other queries.\nIt's built using one or more boolean clauses of the following types: `and`, `or`, or `not`.\n",
"title": "AggregateBoolFilter",
"type": "object",
"oneOf": [
{
"type": "object",
"title": "and",
"required": [
"and"
],
"properties": {
"and": {
"description": "All of the sub-clauses in the query must appear in matching items.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
}
},
{
"type": "object",
"title": "or",
"required": [
"or"
],
"properties": {
"or": {
"description": "At least one of the sub-clauses in the query must appear in matching items.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/AssetAggregateFilter"
}
}
}
},
{
"type": "object",
"title": "not",
"required": [
"not"
],
"properties": {
"not": {
"title": "Filter DSL",
"description": "Sub-clauses in the query must not appear in matching items.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/AssetAggregateFilter"
}
]
}
}
}
]
},
"AssetAdvancedFilter": {
"type": "object",
"properties": {
"advancedFilter": {
"type": "object",
"description": "A filter DSL (Domain Specific Language) to define advanced filter queries.\n\nSee more information about filtering DSL [here](https://docs.cognite.com/dev/concepts/resource_filtering_dsl/ \"filtering DSL\").\n\nSupported properties:\n\n | Property | Type |\n |---------------------------------|-----------------------------------------|\n | `[\"labels\"]` | array of [string] |\n | `[\"createdTime\"]` | number |\n | `[\"dataSetId\"]` | number |\n | `[\"id\"]` | number |\n | `[\"lastUpdatedTime\"]` | number
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment