Skip to content

Instantly share code, notes, and snippets.

@ks93

ks93/az-eastus-1_20230101.json

Created April 27, 2023 15:06
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/feafa2a2bb8503a669515dfcae395935 to your computer and use it in GitHub Desktop.
Save ks93/feafa2a2bb8503a669515dfcae395935 to your computer and use it in GitHub Desktop.
Download ZIP
az-eastus-1_20230101.json
Raw
az-eastus-1_20230101.json
This file has been truncated, but you can view the full file.
{
"openapi": "3.0.1",
"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/v1.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://docs.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://docs.cognite.com/dev/concepts/request_throttling/ \"requests throttling\").\n",
"version": "v1",
"contact": {
"name": "Cognite Support",
"url": "https://support.cognite.com",
"email": "support@cognite.com"
}
},
"servers": [
{
"url": "https://az-eastus-1.cognitedata.com"
}
],
"paths": {
"/api/v1/token/inspect": {
"get": {
"security": [
{
"oidc-token": []
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/assets": {
"get": {
"tags": [
"Assets"
],
"summary": "List assets",
"description": "List all assets, or only the assets matching the specified query.",
"operationId": "getAssets",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/assets/list": {
"post": {
"tags": [
"Assets"
],
"summary": "Filter assets",
"operationId": "listAssets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
],
"description": "Use filtering options to find assets.",
"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"
}
]
}
},
"/api/v1/projects/{project}/assets/aggregate": {
"post": {
"tags": [
"Assets"
],
"summary": "Aggregate assets",
"operationId": "aggregateAssets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
],
"description": "The aggregation API lets you compute aggregated results on assets, \nsuch as getting the count of all assets in a project or checking\ndifferent names and descriptions of assets in your project, etc.\nFilters behave the same way as for the `Filter assets` endpoint.\nIn text properties, the values are aggregated in a case-insensitive manner.",
"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\"})\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "Aggregate aggregateResult = client.assets() \n .aggregate(Request.create().withFilterParameter(\"source\", \"\")); \n\n"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/assets/update": {
"post": {
"tags": [
"Assets"
],
"summary": "Update assets",
"description": "Update the attributes of assets.",
"operationId": "updateAssets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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.",
"operationId": "searchAssets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
}
}
},
"get": {
"tags": [
"Spaces"
],
"summary": "List spaces defined in the project",
"description": "List spaces defined in the current project.",
"operationId": "listSpacesV3",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$ref": "#/components/parameters/ReducedLimit"
},
{
"$ref": "#/components/parameters/Cursor"
}
],
"x-capability": [
"DataModelsAclAdmin:READ"
],
"responses": {
"200": {
"$ref": "#/components/responses/SpaceCollectionResponseWithCursor"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
}
}
},
"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/project"
},
{
"$ref": "#/components/parameters/ReducedLimit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"$ref": "#/components/parameters/InlineViews"
},
{
"$ref": "#/components/parameters/Space"
},
{
"$ref": "#/components/parameters/AllVersions"
}
],
"x-capability": [
"DataModelsAcl:READ"
],
"responses": {
"200": {
"$ref": "#/components/responses/DataModelCollectionResponseWithCursor"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
}
}
},
"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/project"
},
{
"$ref": "#/components/parameters/ReducedLimit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"$ref": "#/components/parameters/Space"
},
{
"$ref": "#/components/parameters/IncludeInheritedProperties"
},
{
"$ref": "#/components/parameters/AllVersions"
}
],
"x-capability": [
"DataModelsAcl:READ"
],
"responses": {
"200": {
"$ref": "#/components/responses/ViewCollectionResponseWithCursor"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
}
}
},
"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/project"
},
{
"$ref": "#/components/parameters/ReducedLimit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"$ref": "#/components/parameters/Space"
}
],
"x-capability": [
"DataModelsAcl:READ"
],
"responses": {
"200": {
"$ref": "#/components/responses/ContainerCollectionResponseWithCursor"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/models/instances": {
"post": {
"tags": [
"Instances"
],
"summary": "Create or update nodes/edges",
"description": "Create or update nodes and edges in a transaction. This operation is currently limited to 1000\nnodes and/or edges at a time.\n\nAdds a new node/edge and populates its properties when the data container does not exist for the node.\nTo add a node/edge, the user must have capabilities to access (write to) both the view and the container.\n\nReplaces all matching properties for an existing node/edge when the referenced and populated view, with \nits backing data container, exists. Or, the whole node/edge gets replaced when the ```replace``` \nparameter is ```true```.\n\nIf you use a writable view to update properties, you must have write access to the view and all its \ncontainers.\n\nWhen a node/edge has no changes, and the supplied values are equal, the node/edge will stay unchanged. \nAdditionally, the operation will not change the ```lastUpdatedTime``` values for the included nodes/edges.\n",
"operationId": "applyNodeAndEdges",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
}
}
}
},
"/api/v1/projects/{project}/models/instances/list": {
"post": {
"tags": [
"Instances"
],
"summary": "Filter nodes/edges",
"description": "Filter the instances - nodes and edges - in a project.",
"operationId": "advancedListInstance",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/models/instances/delete": {
"post": {
"tags": [
"Instances"
],
"summary": "Delete nodes/edges",
"description": "Delete nodes and edges in a transaction. Currently limited to 1000 nodes/edges at a time.\n\n\nWhen you select a node for deletion, you also delete any incoming or outgoing edges pointing to/from it. ",
"operationId": "deleteBulk",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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 traversel, 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 dervive 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- `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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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",
"operationId": "listEvents",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/events/{id}": {
"get": {
"tags": [
"Events"
],
"summary": "Receive an event by its ID",
"operationId": "getEventByInternalId",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/events/list": {
"post": {
"tags": [
"Events"
],
"summary": "Filter events",
"operationId": "advancedListEvents",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
],
"description": "Retrieve a list of all events in the same project. This operation\nsupports pagination by cursor. Criteria can be applied to select a\nsubset of events.\n",
"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"
}
]
}
},
"/api/v1/projects/{project}/events/aggregate": {
"post": {
"tags": [
"Events"
],
"summary": "Aggregate events",
"operationId": "aggregateEvents",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventAggregateRequest"
},
"examples": {
"aggregate": {
"value": {
"filter": {
"type": "type_1"
},
"aggregate": "uniqueValues",
"fields": [
"subtype"
]
}
},
"default": {
"value": {
"filter": {
"type": "type_1"
}
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/AggregateResponse"
},
"400": {
"$ref": "#/components/responses/400ErrorResponse"
},
"429": {
"$ref": "#/components/responses/429ErrorResponse"
}
},
"x-capability": [
"eventsAcl:READ"
],
"description": "The aggregation API lets you compute aggregated results on events, \nsuch as getting the count of all events in a project, checking\ndifferent types and subtypes of events in your project, and\nthe count of events in each of those aggregations. By specifying an additional \nfilter, you can also aggregate only among events matching the specified filter.\n\nWhen you don't specify \nthe `aggregate` field in the request body, the default behavior is to return the count \nof events.\n\nSetting `aggregate` to `uniqueValues` will return all unique values (up to a \nmaximum of 1000), and the count of each value specified in \n`fields: []`. Note that, currently, you can only request for unique \nvalues on a single field. Also, in text fields, the values are \naggregated in a case-insensitive manner. For example:\n\n```\n{\n \"aggregate\": \"uniqueValues\",\n \"fields\": [ \"type\" ]\n}\n```\n\nwill return all unique 'types' in the events in your project.\n\nSimilarly,\n\n```\n{\n \"aggregate\": \"uniqueValues\",\n \"fields\": [ \"dataSetId\" ],\n \"filter\": {\n \"subType\": \"subtype_1\"\n }\n}\n```\nwill return all unique dataSetIds in events of subtype 'subtype_1'",
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/events/search": {
"post": {
"tags": [
"Events"
],
"summary": "Search events",
"operationId": "searchEvents",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/files/{id}": {
"get": {
"tags": [
"Files"
],
"summary": "Retrieve a file by its ID",
"description": "Returns file info for the file ID",
"operationId": "getFileByInternalId",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions": {
"get": {
"tags": [
"Functions"
],
"summary": "List functions",
"operationId": "getFunctions",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/limits": {
"get": {
"tags": [
"Functions"
],
"summary": "Functions limits",
"description": "Service limits for the associated project.",
"operationId": "functionsLimits",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/list": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/delete": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/{functionId}/call": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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": "client.ll = client.functions.call(id=1)\n\nfunc = client.functions.retrieve(id=1)\nclient.ll = func.call()\n"
}
]
}
},
"/api/v1/projects/{project}/functions/{functionId}/calls": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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\nclient.ll = client.functions.calls.retrieve(call_id=2, function_id=1)\nlogs = client.ll.get_logs()\n"
}
]
}
},
"/api/v1/projects/{project}/functions/{functionId}/calls/byids": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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": "client.ll = client.functions.calls.retrieve(call_id=2, function_id=1)\n\nfunc = client.functions.retrieve(id=1)\nclient.ll = func.retrieve_call(id=2)\n"
}
]
}
},
"/api/v1/projects/{project}/functions/{functionId}/calls/{callId}": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
}
}
},
"/api/v1/projects/{project}/functions/{functionId}/calls/{callId}/logs": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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."
}
},
"/api/v1/projects/{project}/functions/{functionId}": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
}
}
},
"/api/v1/projects/{project}/functions/byids": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/status": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
},
"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"
]
}
},
"/api/v1/projects/{project}/functions/schedules": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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": "schedule = client.functions.schedules.create(\n name= \"My schedule\",\n function_id=123,\n cron_expression=\"*/5 * * * *\",\n client_credentials={\"client_id\": \"...\", \"client_secret\": \"...\"},\n description=\"This schedule does magic stuff.\"\n)\n"
}
]
}
},
"/api/v1/projects/{project}/functions/schedules/list": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/schedules/{scheduleId}": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
}
}
},
"/api/v1/projects/{project}/functions/schedules/byids": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/schedules/delete": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/functions/schedules/{scheduleId}/input_data": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/functions/{functionId}/calls/{callId}/response": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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\nclient.ll = client.functions.calls.retrieve(call_id=2, function_id=1)\nresponse = client.ll.get_response()\n"
}
]
}
},
"/api/v1/projects/{project}/functions/{functionId}/calls/list": {
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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": "client.lls = client.functions.calls.list(function_id=1)\n\nfunc = client.functions.retrieve(id=1)\nclient.lls = func.list_calls()\n"
}
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/3d/models/update": {
"post": {
"tags": [
"3D Models"
],
"summary": "Update 3D models",
"operationId": "update3DModels",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/3d/models/delete": {
"post": {
"tags": [
"3D Models"
],
"summary": "Delete 3D models",
"operationId": "delete3DModels",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/3d/models/{modelId}": {
"get": {
"tags": [
"3D Models"
],
"summary": "Retrieve a 3D model",
"operationId": "get3DModel",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/3d/models/{modelId}/revisions/update": {
"post": {
"tags": [
"3D Model Revisions"
],
"summary": "Update 3D revisions",
"operationId": "update3DRevisions",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/3d/models/{modelId}/revisions/delete": {
"post": {
"tags": [
"3D Model Revisions"
],
"summary": "Delete 3D revisions",
"operationId": "delete3DRevisions",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/3d/models/{modelId}/revisions/{revisionId}": {
"get": {
"tags": [
"3D Model Revisions"
],
"summary": "Retrieve a 3D revision",
"operationId": "get3DRevision",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/3d/models/{modelId}/revisions/{revisionId}/thumbnail": {
"post": {
"tags": [
"3D Model Revisions"
],
"summary": "Update 3D revision thumbnail",
"operationId": "updateThumbnail",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/timeseries": {
"get": {
"tags": [
"Time series"
],
"summary": "List time series",
"description": "List time series. Use nextCursor to paginate through the results.",
"operationId": "getTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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": "Get 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 include 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": "Create one or more time series.",
"operationId": "postTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "The time series created.",
"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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/byids": {
"post": {
"tags": [
"Time series"
],
"summary": "Retrieve time series",
"description": "Retrieve one or more time series by ID or external ID. The time series are returned in the same order as in the request.",
"operationId": "getTimeSeriesByIds",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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": "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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/list": {
"post": {
"tags": [
"Time series"
],
"summary": "Filter time series",
"operationId": "listTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesListDTO"
}
}
}
},
"responses": {
"200": {
"description": "List for time series.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataWithCursorGetTimeSeriesMetadataDTO"
}
}
}
}
},
"x-capability": [
"timeSeriesAcl:READ"
],
"description": "Retrieves a list of time series matching the specified criteria. This operation supports pagination by cursor. Criteria can be applied to select a subset of time series.",
"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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/aggregate": {
"post": {
"tags": [
"Time series"
],
"summary": "Aggregate time series",
"operationId": "aggregateTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"x-capability": [
"timeSeriesAcl:READ"
],
"description": "Count the number of time series that match the given filter.",
"requestBody": {
"description": "Retrieves the count of time series matching the given criteria.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesAggregateDTO"
}
}
}
},
"responses": {
"200": {
"description": "The number of time series that match the filters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesCountAggregateResponse"
}
}
}
},
"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\"));"
}
]
}
},
"/api/v1/projects/{project}/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\nordering may change over time. Additional filters can also be\nspecified. This operation does not support pagination.",
"operationId": "searchTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/update": {
"post": {
"tags": [
"Time series"
],
"summary": "Update time series",
"description": "Updates one or more time series. Fields that are not included in the request, are not changed.\n\nFor primitive fields (String, Long Int), use 'set': 'value' to 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 update the value; use 'add': [v1, v2] to add values; use 'remove': [v1, v2] to remove values.",
"operationId": "alterTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "List of changes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "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 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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/delete": {
"post": {
"tags": [
"Time series"
],
"summary": "Delete time series",
"description": "Deletes the time series with the specified IDs and their datapoints.",
"operationId": "deleteTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/data": {
"post": {
"tags": [
"Time series"
],
"summary": "Insert data points",
"description": "Insert datapoints into a time series. You can do this for multiple time series.\nIf you insert a datapoint with a timestamp that already exists, it will be overwritten with the new value.",
"operationId": "postMultiTimeSeriesDatapoints",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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 serialised payload, based on 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": "datapoints = []\ndatapoints.append({\"id\": 1, \"datapoints\": [(datetime(2018,1,1), 1000), (datetime(2018,1,2), 2000)]})\ndatapoints.append({\"externalId\": 1, \"datapoints\": [(150000000000, 1000), (160000000000, 2000)]})\n\nclient.datapoints.insert_multiple(datapoints)\n\ndatapoints = []\ndatapoints.append({\"externalId\": \"1\", \"datapoints\": [{\"timestamp\": datetime(2018,1,1), \"value\": 1000},\n {\"timestamp\": datetime(2018,1,2), \"value\": 2000}]})\ndatapoints.append({\"id\": 1, \"datapoints\": [{\"timestamp\": 150000000000, \"value\": 1000},\n {\"timestamp\": 160000000000, \"value\": 2000}]})\n\nclient.datapoints.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"
}
]
}
},
"/api/v1/projects/{project}/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.\nA detailed description of how aggregates work can be found at [our concept guide for aggregation](<https://docs.cognite.com/dev/concepts/aggregation/>).\n\nNote: when the 'start' is not specified neither in top level and for individual item it will default to epoch 0 which is Jan 1st, 1970 thus,\nexcluding potential existent datapoints before 1970. 'start' needs to be specified to get datapoints before 1970.",
"operationId": "getMultiTimeSeriesDatapoints",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "Specify parameters to query for multiple datapoints. If you omit fields in individual datapoint 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 datapoints for the specified queries.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatapointsOrAggregatesResponse"
}
},
"application/protobuf": {
"schema": {
"type": "string",
"format": "binary",
"description": "Return protocol buffer serialised 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.datapoints.retrieve(id=1, start=\"2w-ago\", end=\"now\")\n\ndps = client.datapoints.retrieve(external_id=[\"abc\", \"def\"],\n start=datetime(2018,1,1),\n end=datetime(2019,1,1),\n aggregates=[\"average\"],\n granularity=\"1d\")\n\ndps = client.datapoints.retrieve(id=[{\"id\": 1, \"aggregates\": [\"average\"]},\n {\"id\": 1, \"aggregates\": [\"min\"]}],\n external_id={\"externalId\": \"1\", \"aggregates\": [\"max\"]},\n start=\"1d-ago\", end=\"now\", granularity=\"1h\")\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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/data/latest": {
"post": {
"tags": [
"Time series"
],
"summary": "Retrieve latest data point",
"description": "Retrieves the latest data point in a time series.",
"operationId": "getLatest",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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 datapoint, or an empty list if no datapoints are found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatapointsResponse"
}
}
}
},
"400": {
"description": "The time series does not 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.datapoints.retrieve_latest(id=1)[0]\n\nres = client.datapoints.retrieve_latest(id=1, before=\"2d-ago\")[0]\n\nres = client.datapoints.retrieve_latest(external_id=[\"abc\", \"def\"])\nlatest_abc = res[0][0]\nlatest_def = res[1][0]\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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/data/delete": {
"post": {
"tags": [
"Time series"
],
"summary": "Delete datapoints",
"description": "Delete datapoints from time series.",
"operationId": "deleteDatapoints",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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 {\"externalId\": \"abc\", \"start\": \"2d-ago\", \"end\": \"now\"}]\nclient.datapoints.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"
}
]
}
},
"/api/v1/projects/{project}/timeseries/synthetic/query": {
"post": {
"tags": [
"Synthetic Time Series"
],
"summary": "Synthetic query",
"description": "Execute an on-the-fly synthetic query",
"operationId": "querySyntheticTimeseries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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.datapoints.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.datapoints.synthetic.query(expressions=\"A+B\", start=\"2w-ago\", end=\"now\", variables=vars)\n\nfrom sympy import symbols, cos, sin\na = symbols('a')\ndps = client.datapoints.synthetic.query([sin(a), cos(a)], start=\"2w-ago\", end=\"now\", variables={\"a\": \"my_ts_external_id\"}, aggregate='interpolation', granularity='1m')\n"
}
]
}
},
"/api/v1/projects/{project}/raw/dbs": {
"get": {
"tags": [
"Raw"
],
"summary": "List databases",
"operationId": "getDBs",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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);"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/raw/dbs/{dbName}/tables": {
"get": {
"tags": [
"Raw"
],
"summary": "List tables in a database",
"operationId": "getTables",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/raw/dbs/{dbName}/tables/delete": {
"post": {
"tags": [
"Raw"
],
"summary": "Delete tables in a database",
"operationId": "deleteTables",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
]
}
},
"/api/v1/projects/{project}/raw/dbs/{dbName}/tables/{tableName}/rows": {
"get": {
"tags": [
"Raw"
],
"summary": "Retrieve rows from a table",
"operationId": "getRows",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/raw/dbs/{dbName}/tables/{tableName}/rows/{rowKey}": {
"get": {
"tags": [
"Raw"
],
"summary": "Retrieve row by key",
"operationId": "getRow",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/raw/dbs/{dbName}/tables/{tableName}/rows/delete": {
"post": {
"tags": [
"Raw"
],
"summary": "Delete rows in a table",
"operationId": "deleteRows",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
}
]
}
},
"/api/v1/projects/{project}/groups": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/groups/delete": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects": {
"get": {
"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"
}
}
}
},
"/api/v1/projects/{project}": {
"get": {
"tags": [
"Projects"
],
"summary": "Retrieve a project",
"description": "Retrieves information about a project given the project URL name.",
"operationId": "getProject",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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');"
}
]
}
},
"/api/v1/projects/{project}/update": {
"post": {
"tags": [
"Projects"
],
"summary": "Update a project",
"description": "Updates the project configuration.\n\n**Warning**: Updating a project will invalidate active [sessions](#tag/Sessions) within that project.\n",
"operationId": "updateProject",
"parameters": [
{
"name": "project",
"in": "path",
"description": "Project url name",
"required": true,
"schema": {
"type": "string"
}
}
],
"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"
]
}
},
"/api/v1/projects/{project}/securitycategories": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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 "
}
]
}
},
"/api/v1/projects/{project}/securitycategories/delete": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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 "
}
]
}
},
"/api/v1/projects/{project}/datasets": {
"post": {
"tags": [
"Data sets"
],
"summary": "Create data sets",
"description": "You can create a maximum of 10 data sets per request.",
"operationId": "createDataSets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/datasets/list": {
"post": {
"tags": [
"Data sets"
],
"summary": "Filter data sets",
"description": "Use advanced filtering options to find data sets.",
"operationId": "listDataSets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/datasets/byids": {
"post": {
"tags": [
"Data sets"
],
"summary": "Retrieve data sets",
"description": "Retrieve data sets by IDs or external IDs.",
"operationId": "getDataSets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/datasets/update": {
"post": {
"tags": [
"Data sets"
],
"summary": "Update data sets.",
"operationId": "updateDataSets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/sequences": {
"get": {
"tags": [
"Sequences"
],
"summary": "List sequences",
"operationId": "listSequences",
"description": "List sequences. Use nextCursor to paginate through the results.",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"$ref": "#/components/parameters/partition"
},
{
"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": 25,
"minimum": 1,
"maximum": 1000
}
}
],
"responses": {
"200": {
"description": "Paged response with 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"
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"responses": {
"201": {
"description": "Created object",
"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\nclient.lumn_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"
}
]
}
},
"/api/v1/projects/{project}/sequences/list": {
"post": {
"tags": [
"Sequences"
],
"summary": "Filter sequences",
"operationId": "advancedListSequences",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "Retrieves a list of sequences matching the given criteria.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequencesAdvancedListDTO"
}
}
}
},
"responses": {
"200": {
"description": "Listing sequences.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequenceWithCursorResponse"
}
}
}
}
},
"x-capability": [
"sequencesAcl:READ"
],
"description": "Retrieves a list of sequences matching the given criteria.",
"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"
}
]
}
},
"/api/v1/projects/{project}/sequences/aggregate": {
"post": {
"tags": [
"Sequences"
],
"summary": "Aggregate sequences",
"operationId": "aggregateSequences",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"x-capability": [
"sequencesAcl:READ"
],
"description": "Count the number of sequences that match the given filter.",
"requestBody": {
"description": "Retrieves the count of sequences matching the given criteria.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequencesAggregateDTO"
}
}
}
},
"responses": {
"200": {
"description": "The number of sequences that match the filters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequencesCountAggregateResponse"
}
}
}
},
"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"
}
]
}
},
"/api/v1/projects/{project}/sequences/byids": {
"post": {
"tags": [
"Sequences"
],
"summary": "Retrieve sequences",
"description": "Retrieve one or more sequences by ID or external ID. The sequences are returned in the same order as in the request.",
"operationId": "getSequenceById",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "Ids of the sequences",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataResourceIdsWithIgnoreUnknownIds"
}
}
}
},
"responses": {
"200": {
"description": "Object found",
"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"
}
]
}
},
"/api/v1/projects/{project}/sequences/search": {
"post": {
"tags": [
"Sequences"
],
"summary": "Search sequences",
"description": "Retrieves a list of sequences matching the given criteria. This operation does not support pagination.",
"operationId": "searchSequences",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "Retrieves a list of sequences matching the given criteria. This operation does not support pagination.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequencesSearchDTO"
}
}
}
},
"responses": {
"200": {
"description": "Search on sequences.",
"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"
}
]
}
},
"/api/v1/projects/{project}/sequences/update": {
"post": {
"tags": [
"Sequences"
],
"summary": "Update sequences",
"description": "Update one or more sequences. Fields that are not included in the request, are not changed.",
"operationId": "updateSequences",
"requestBody": {
"description": "Patch definition",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataSequenceChange"
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"responses": {
"200": {
"description": "The modified 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\nclient.lumn_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\nclient.lumn_updates = [ SequenceColumnUpdate(external_id=\"col_external_id_1\").external_id.set(\"new_col_external_id\"), SequenceColumnUpdate(external_id=\"col_external_id_2\").description.set(\"my new description\"), ]\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"
}
]
}
},
"/api/v1/projects/{project}/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, ignoreUnknownIds 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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/sequences/data/list": {
"post": {
"tags": [
"Sequences"
],
"summary": "Retrieve rows",
"description": "Processes data requests, and returns the result. NB - 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"
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"responses": {
"200": {
"description": "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,\nclient.l = 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"
}
]
}
},
"/api/v1/projects/{project}/sequences/data/latest": {
"post": {
"tags": [
"Sequences"
],
"summary": "Retrieve latest row",
"description": "Retrieves the last row (i.e the row with the highest row number) in a sequence.",
"operationId": "getLatestSequenceRow",
"requestBody": {
"description": "Description of data requested",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequenceLatestDataRequest"
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"responses": {
"200": {
"description": "Sequence data found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequenceGetData"
}
}
}
}
},
"x-capability": [
"sequencesAcl:READ"
]
}
},
"/api/v1/projects/{project}/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"
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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);"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/labels/list": {
"post": {
"tags": [
"Labels"
],
"summary": "Filter labels",
"description": "Use advanced filtering options to find label definitions.",
"operationId": "listLabels",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/relationships": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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(external_id=\"flow_1\", source_external_id=\"source_ext_id\", source_type=\"asset\", target_external_id=\"target_ext_id\", target_type=\"event\", confidence=0.1, data_set_id=1234)\nflowrel2 = Relationship(external_id=\"flow_2\", source_external_id=\"source_ext_id\", source_type=\"asset\", target_external_id=\"target_ext_id\", target_type=\"event\", confidence=0.1, data_set_id=1234)\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"
]
}
},
"/api/v1/projects/{project}/relationships/update": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/relationships/delete": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/relationships/byids": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/relationships/list": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/context/entitymatching/": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/context/entitymatching/byids": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Retrieve entity matching models",
"description": "Retrieve entity matching models by IDs or external IDs.",
"operationId": "entityMatchingRetrieve",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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' }]);"
}
]
}
},
"/api/v1/projects/{project}/context/entitymatching/list": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Filter models",
"description": "Use filtering options to find entity matcher models.",
"operationId": "entityMatchingFilter",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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' }});"
}
]
}
},
"/api/v1/projects/{project}/context/entitymatching/update": {
"post": {
"tags": [
"Entity matching"
],
"summary": "Update entity matching models",
"description": "Update entity matching models by IDs or external IDs.",
"operationId": "entityMatchingUpdate",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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}]);"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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' }]);"
}
]
}
},
"/api/v1/projects/{project}/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 `/api/v1/projects/{project}/context/entitymatching/jobs/{jobId}` without requiring 'assetsAcl:READ'. ",
"operationId": "entityMatchingPredict",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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 `/api/v1/projects/{project}/context/entitymatching/predict`",
"operationId": "entityMatchingPredictResults",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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});"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$ref": "#/components/parameters/cdfversionheader"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/VisionExtractPostRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/VisionExtractPostResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const job = await client.vision.extract(['TextDetection', 'AssetTagDetection', 'PeopleDetection'], [{ fileId: 1234 }]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.experimental.data_classes.vision import VisionFeature\n\nextract_job = client.vision.extract(features=[VisionFeature.TEXT_DETECTION, VisionFeature.ASSET_TAG_DETECTION, VisionFeature.PEOPLE_DETECTION], file_ids=[1234])"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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})"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "# Get an existing job, wait for completion and then get the parsed results\nextract_job = client.vision.get_extract_job(job_id=1)\nextract_job.wait_for_completion()\nfor item in extract_job.items:\n predictions = item.predictions\n # do something with the predictions"
}
]
}
},
"/api/v1/projects/{project}/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 signifies an AND operation, and the `|` symbol signifies 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, like so: `lorem ipsum`, will\nmatch documents containing both the words \"lorem\" and \"ipsum\" in the filename or content.\n\nTo exclude documents containing a specific word, you can use the operator `-`.\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, we try to return the most relevant documents first, and 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 that contain all the terms are considered more relevant than documents\n that only contain some of the terms.\n- Matches of the terms in the filename field of the document, count for more than matches in the content of the\n document.\n\n#### Examples\n\n```json\n{\n \"search\": {\n \"query\": \"cognite \\\"lorem ipsum\\\"\"\n }\n}\n ```\n\nThis request will return documents matching the search query, where the query behaves as described above.\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\nThis example combines a query with a filter.\nThis search request will return documents matching the search query, and where `externalId` starts with \"1\".\nThe results will be ordered by how well they match the query string.\n\n### Highlights\nWhen you enable highlights for your search query, the response contains an additional highlight field for each\nsearch hit that includes the highlighted fragments for your query matches. However, this is a costly operation, and we therefore\nlimit the results to 20 documents.\n\n### Filtering\n\nFiltering is done by using a special JSON filtering language.\nIt is 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 whose geoshape intersect 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 whose 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 whose geoshape fall 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 that have a related asset in a subtree rooted at any of the 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\nBelow is an overview of all the properties that can be filtered on, and which filters are applicable to each 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```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\nSearch results are by default ordered by relevance, meaning how well they match the given query string.\nHowever, it is possible to specify a different property to sort by.\nSorting can be ascending or descending. The default sort order is ascending, in case none is specified.\n\n#### Properties\nBelow is an overview of all the 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```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"
]
}
},
"/api/v1/projects/{project}/documents/aggregate": {
"post": {
"tags": [
"Documents"
],
"summary": "Aggregate documents",
"description": "The aggregation API allows you to compute aggregated results on documents\nlike getting the count of all documents in a project or checking what are all the\ndifferent authors of documents in a project, along with the count of documents in\neach of those aggregations. By specifying an additional filter or search, you can\nalso aggregate only among documents matching the specified filter or search.\n\nThe default behavior, when you do not specify the `aggregate` field in the request\nbody, 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</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, <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<tr>\n<td> <code>allUniqueValues</code> </td> <td> Returns all unique values\nand the count of each. The response contains a cursor that must be used\nto fetch all pages of data. The data is not ordered by the count. This\nallows to retrieve all unique values for more than 10000 items. </td> <td> \n\n```json\n{\n \"aggregate\":\"allUniqueValues\",\n \"properties\":[\n {\n \"property\":[\n \"author\"\n ]\n }\n ]\n}\n```\n\n</td>\n</tr>\n\n<tr>\n<td> <code>allUniqueProperties</code> </td> <td> Returns all unique properties values\nand the count of each. The response contains a cursor that must be used\nto fetch all pages of data. The data is not ordered by the count. This\nallows to retrieve all unique properties values for more than 10000 items.\n\nCurrently, <code>allUniqueProperties</code> aggregate is only supported for property\n<code>[\"sourceFile\", \"metadata\"]</code>.\n </td> <td> \n\n```json\n{\n \"aggregate\":\"allUniqueProperties\",\n \"properties\":[\n {\n \"property\":[\n \"sourceFile\",\n \"metadata\"\n ]\n }\n ]\n}\n```\n\n</td>\n</tr>\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</table>\n\n<!---\n### Metadata aggregation\n\nAggregation on metadata behaves differently. Supported aggregate operations:\n\n| Property | Applicable aggregation |\n|-------------------------------------|--------------------------------------|\n| `[\"sourceFile\", \"metadata\", <key>]` | uniqueValues, cardinalityValues, |\n| `[\"sourceFile\", \"metadata\"]` | uniqueProperties |\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--->\n",
"operationId": "documentsAggregate",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/DocumentsAggregateCountRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateUniqueValuesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateUniquePropertiesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateAllUniquePropertiesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateAllUniqueValuesRequest"
},
{
"$ref": "#/components/schemas/DocumentsAggregateCardinalityValuesRequest"
}
]
},
"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"
]
}
},
"/api/v1/projects/{project}/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 is not 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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/geospatial/crs/byids": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Get Coordinate Reference Systems",
"description": "Get Coordinate Reference Systems by their Spatial Reference IDs",
"operationId": "getCoordinateReferenceSystem",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/geospatial/crs/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete Coordinate Reference Systems",
"description": "Delete custom Coordinate Reference Systems.",
"operationId": "deleteGeospatialCoordinateReferenceSystems",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/geospatial/featuretypes": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Create feature types",
"description": "Creates feature types. Each tenant can have up to 100 feature types.",
"operationId": "createFeatureTypes",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/geospatial/featuretypes/list": {
"post": {
"tags": [
"Geospatial"
],
"summary": "List feature types",
"description": "List all feature types",
"operationId": "listFeatureTypes",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GeospatialFeatureTypesResponse"
},
"400": {
"$ref": "#/components/responses/GeospatialErrorResponse"
}
},
"x-capability": [
"geospatialAcl:READ"
]
}
},
"/api/v1/projects/{project}/geospatial/featuretypes/update": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Update feature types",
"description": "Update one or more feature types",
"operationId": "updateFeatureTypes",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/geospatial/featuretypes/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete feature types",
"description": "Delete feature types.",
"operationId": "GeospatialDeleteFeatureTypes",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Create features",
"description": "Create features",
"operationId": "createFeatures",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/delete": {
"post": {
"tags": [
"Geospatial"
],
"summary": "Delete features",
"description": "Delete features.",
"operationId": "deleteFeatures",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
]
}
},
"/api/v1/projects/{project}/sessions": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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",
"security": [
{
"oidc-token": []
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/sessions/byids": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
}
}
},
"/api/v1/projects/{project}/sessions/revoke": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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": 0
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/extpipes/list": {
"post": {
"tags": [
"Extraction Pipelines"
],
"summary": "Filter extraction pipelines",
"description": "Use advanced filtering options to find extraction pipelines.",
"operationId": "filterExtPipes",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
}
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/extpipes/config/revisions": {
"get": {
"tags": [
"Extraction Pipelines Config"
],
"summary": "List configuration revisions",
"description": "Lists configuration revisions for the given extraction pipeline.",
"operationId": "listExtPipeConfigRevisions",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"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"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
},
"/api/v1/projects/{project}/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": [
{
"$ref": "#/components/parameters/project"
},
{
"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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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_pipeline_runs.create(ExtractionPipelineRun(status=\"success\", 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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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_pipeline_runs.list(external_id=\"test ext id\", limit=5)\n\nrunsList = client.extraction_pipeline_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"
}
]
}
},
"/api/v1/projects/{project}/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\ntransformations = [\n Transformation(\n name=\"transformation1\",\n destination=TransformationDestination.assets()\n ),\n Transformation(\n name=\"transformation2\",\n destination=TransformationDestination.raw(\"myDatabase\", \"myTable\"),\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"
}
]
}
},
"/api/v1/projects/{project}/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);"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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);"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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);"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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.update(transformation)\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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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"
}
},
"/api/v1/projects/{project}/transformations/schema/instances": {
"get": {
"tags": [
"Schema"
],
"summary": "Get Data Model Instance schema",
"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.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "viewExternalId",
"in": "query",
"description": "External id of the View. Not required if isConnectionDefinition is true.",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "viewVersion",
"in": "query",
"description": "Version of the View. Not required if isConnectionDefinition is true.",
"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": "Space where the instances(nodes/edges) will be created, is specified 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"
}
}
],
"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"
}
},
"/api/v1/projects/{project}/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\nclient.lumns = client.transformations.schema.retrieve(destination = TransformationDestination.assets())\n"
}
]
}
},
"/api/v1/projects/{project}/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"
}
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2CreateRequestSchema"
},
"responses": {
"201": {
"$ref": "#/components/responses/AnnotationsV2CreateResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2SuggestRequestSchema"
},
"responses": {
"201": {
"$ref": "#/components/responses/AnnotationsV2CreateResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:SUGGEST"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$ref": "#/components/parameters/AnnotationId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2ResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ListRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2CursoredListResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ByIdsRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2ListResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
}
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2ByIdsRequestSchema"
},
"responses": {
"200": {
"description": "Successful deletion"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/AnnotationsV2UpdateRequestSchema"
},
"responses": {
"200": {
"$ref": "#/components/responses/AnnotationsV2UpdateResponseSchema"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"annotationsAcl:WRITE"
]
}
},
"/api/v1/projects/{project}/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/project"
},
{
"$ref": "#/components/parameters/seismicId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DownloadSeismicResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"seismicAcl:READ"
]
}
},
"/api/v1/projects/{project}/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",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"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"
]
}
}
},
"components": {
"securitySchemes": {
"oidc-token": {
"type": "http",
"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'",
"scheme": "bearer"
},
"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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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"
}
]
}
}
},
"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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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\"]`.\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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\"]`.\nIn beta. Available only when the `cdf-version` header with `beta` suffix value is provided.\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\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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_\"]` |\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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`.",
"allOf": [
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetAggregateEnum"
},
{
"$ref": "#/components/schemas/AssetAggregateKeys"
}
]
},
"AssetCardinalityValuesAggregate": {
"allOf": [
{
"type": "object",
"title": "ApproximateCardinalityForValues",
"description": "Request values approximate cardinality aggregate on a specific property.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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.\n\nIn beta. Available only when the `cdf-version` header with `beta` suffix value is provided.",
"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.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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"
}
}
}
},
"AssetAggregateEnum": {
"type": "object",
"properties": {
"aggregate": {
"default": "count",
"description": "Type of aggregation to apply.\n`count`: Simple count of all assets permitted by the filter.\n`metadataKeys`: Get unique values (up to max 1000) of metadata keys ordered by frequency.\n`metadataValues`: Get unique values (up to max 1000) of values for a particular metadata key, ordered by frequency.\n",
"type": "string",
"enum": [
"metadataKeys",
"metadataValues",
"count"
]
}
}
},
"AssetListScope": {
"allOf": [
{
"$ref": "#/components/schemas/AssetFilter"
},
{},
{
"$ref": "#/components/schemas/AssetLimit"
},
{},
{
"$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\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"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\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.\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 |\n | `[\"parentId\"]` | number |\n | `[\"rootId\"]` | number |\n | `[\"description\"]` | string |\n | `[\"externalId\"]` | string |\n | `[\"metadata\"]` | string |\n | `[\"metadata\", \"someCustomKey\"]` | string |\n | `[\"name\"]` | string |\n | `[\"source\"]` | string |\n\n Note: Filtering on the `[\"metadata\"]` property has the following logic:\n If a value of any metadata keys in an asset matches the filter, the asset matches the filter.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"oneOf": [
{
"$ref": "#/components/schemas/AssetBoolFilter"
},
{
"$ref": "#/components/schemas/AssetLeafFilter"
}
],
"example": {
"or": [
{
"not": {
"and": [
{
"equals": {
"property": [
"metadata",
"asset_type"
],
"value": "gas pump"
}
},
{
"in": {
"property": [
"source"
],
"values": [
"blueprint",
"inventory"
]
}
},
{
"range": {
"property": [
"dataSetId"
],
"gte": 1,
"lt": 10
}
}
]
}
},
{
"and": [
{
"containsAny": {
"property": [
"labels"
],
"values": [
"pump",
"cooler"
]
}
},
{
"equals": {
"property": [
"parentId"
],
"value": 95867294876
}
}
]
},
{
"search": {
"property": [
"description"
],
"value": "My favorite pump"
}
}
]
}
}
}
},
"AssetLeafFilter": {
"description": "Leaf filter.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"title": "LeafFilter",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/EqualsFilter"
},
{
"$ref": "#/components/schemas/InFilter"
},
{
"$ref": "#/components/schemas/GenericRangeFilter"
},
{
"$ref": "#/components/schemas/PrefixFilter"
},
{
"$ref": "#/components/schemas/ExistsFilter"
},
{
"$ref": "#/components/schemas/ContainsAnyFilter"
},
{
"$ref": "#/components/schemas/ContainsAllFilter"
},
{
"$ref": "#/components/schemas/SearchFilter"
}
]
},
"AssetBoolFilter": {
"description": "A query that matches items matching boolean combinations of other queries.\nIt is built using one or more boolean clauses of the following types: `and`, `or`, or `not`.\n\nIn beta. Available only when the `cdf-version` header with the `beta` suffix value is provided.",
"title": "BoolFilter",
"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/AssetAdvancedFilter"
}
}
}
},
{
"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/AssetAdvancedFilter"
}
}
}
},
{
"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/AssetAdvancedFilter"
}
]
}
}
}
]
},
"AssetSearchFilter": {
"description": "Search request with filter capabilities.",
"example": {
"filter": {
"parentIds": [
1293812938,
293823982938
]
},
"search": {
"name": "flow",
"description": "upstream"
}
},
"allOf": [
{
"$ref": "#/components/schemas/AssetFilter"
},
{
"$ref": "#/components/schemas/AssetLimit"
},
{
"$ref": "#/components/schemas/AssetSearch"
}
]
},
"AssetSearch": {
"type": "object",
"properties": {
"search": {
"type": "object",
"title": "Search",
"description": "Fulltext search for assets. Primarily meant for for human-centric use-cases, not for programs. The query parameter uses a different search algorithm than the deprecated name and description parameters, and will generally give much better results.",
"properties": {
"name": {
"$ref": "#/components/schemas/AssetName"
},
"description": {
"$ref": "#/components/schemas/AssetDescription"
},
"query": {
"$ref": "#/components/schemas/AssetQuery"
}
}
}
}
},
"AssetChange": {
"oneOf": [
{
"$ref": "#/components/schemas/AssetChangeById"
},
{
"$ref": "#/components/schemas/AssetChangeByExternalId"
}
]
},
"AssetChangeById": {
"allOf": [
{
"$ref": "#/components/schemas/AssetPatch"
},
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CogniteInternalId"
}
}
}
]
},
"AssetChangeByExternalId": {
"allOf": [
{
"$ref": "#/components/schemas/AssetPatch"
},
{
"type": "object",
"required": [
"externalId"
],
"properties": {
"externalId": {
"$ref": "#/components/schemas/CogniteExternalId"
}
}
}
]
},
"AssetPatch": {
"type": "object",
"description": "Changes applied to asset",
"required": [
"update"
],
"properties": {
"update": {
"type": "object",
"properties": {
"externalId": {
"$ref": "#/components/schemas/SinglePatchExternalId"
},
"name": {
"$ref": "#/components/schemas/SinglePatchRequiredName"
},
"description": {
"$ref": "#/components/schemas/SinglePatchResourceDescription"
},
"dataSetId": {
"$ref": "#/components/schemas/SinglePatchLong"
},
"metadata": {
"$ref": "#/components/schemas/ObjectPatchAsset"
},
"source": {
"$ref": "#/components/schemas/SinglePatchAssetSource"
},
"parentId": {
"$ref": "#/components/schemas/SinglePatchRequiredInternalId"
},
"parentExternalId": {
"$ref": "#/components/schemas/SinglePatchRequiredParentExternalId"
},
"labels": {
"$ref": "#/components/schemas/LabelsPatch"
},
"geoLocation": {
"$ref": "#/components/schemas/SinglePatchGeoLocation"
}
}
}
}
},
"SinglePatchRequiredName": {
"title": "AssetName",
"type": "object",
"properties": {
"set": {
"$ref": "#/components/schemas/AssetName"
}
},
"description": "Set a new value for the asset name.",
"required": [
"set"
]
},
"SinglePatchAssetSource": {
"title": "Source",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SetAssetSource"
},
{
"$ref": "#/components/schemas/RemoveField"
}
],
"description": "Set a new value for the source, or remove the value."
},
"SinglePatchRequiredInternalId": {
"type": "object",
"properties": {
"set": {
"$ref": "#/components/schemas/CogniteInternalId"
}
},
"description": "Change the ID of the object.",
"required": [
"set"
]
},
"SinglePatchRequiredExternalId": {
"type": "object",
"properties": {
"set": {
"$ref": "#/components/schemas/CogniteExternalId"
}
},
"description": "Change the external ID of the object.",
"required": [
"set"
]
},
"SinglePatchRequiredParentExternalId": {
"type": "object",
"properties": {
"set": {
"$ref": "#/components/schemas/AssetParentExternalId"
}
},
"description": "Change the external ID of the object.",
"required": [
"set"
]
},
"NodeOrEdge": {
"oneOf": [
{
"$ref": "#/components/schemas/NodeDefinition"
},
{
"$ref": "#/components/schemas/EdgeDefinition"
}
]
},
"SlimNodeOrEdge": {
"oneOf": [
{
"$ref": "#/components/schemas/SlimNodeDefinition"
},
{
"$ref": "#/components/schemas/SlimEdgeDefinition"
}
]
},
"ViewPropertyReference": {
"type": "object",
"required": [
"view",
"identifier"
],
"properties": {
"view": {
"$ref": "#/components/schemas/ViewReference"
},
"identifier": {
"description": "The unique identifier, from the view, for the property",
"allOf": [
{
"$ref": "#/components/schemas/PropertyIdentifierV3"
}
]
}
}
},
"ViewReference": {
"type": "object",
"description": "Reference to a view",
"required": [
"type",
"space",
"externalId",
"version"
],
"properties": {
"type": {
"type": "string",
"enum": [
"view"
]
},
"space": {
"description": "Id of the space that the view belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "External-id of the view",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"version": {
"description": "Version of the view",
"allOf": [
{
"$ref": "#/components/schemas/DMSVersion"
}
]
}
}
},
"DataModelReference": {
"type": "object",
"description": "Data model reference",
"required": [
"space",
"externalId",
"version"
],
"properties": {
"space": {
"description": "Id of the space that the data model belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "External-id of the data model",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"version": {
"description": "Version of the data model",
"allOf": [
{
"$ref": "#/components/schemas/DMSVersion"
}
]
}
}
},
"CreateViewProperty": {
"type": "object",
"required": [
"container",
"containerPropertyIdentifier"
],
"properties": {
"name": {
"type": "string",
"description": "Readable property name.",
"maxLength": 255
},
"description": {
"type": "string",
"description": "Description of the content and suggested use for this property.",
"maxLength": 1024
},
"container": {
"$ref": "#/components/schemas/ContainerReference"
},
"containerPropertyIdentifier": {
"description": "The unique identifier for the property (Unique within the referenced container).",
"allOf": [
{
"$ref": "#/components/schemas/PropertyIdentifierV3"
}
]
},
"source": {
"description": "Indicates on what type a referenced direct relation is expected to be (although not required). Only applicable for direct relation properties.",
"allOf": [
{
"$ref": "#/components/schemas/ViewReference"
}
]
}
}
},
"ContainerReference": {
"type": "object",
"description": "Reference to an existing container",
"required": [
"type",
"space",
"externalId"
],
"properties": {
"type": {
"type": "string",
"enum": [
"container"
]
},
"space": {
"description": "Id of the space hosting (containing) the container",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "External-id of the container",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
}
}
},
"DataModelCore": {
"type": "object",
"required": [
"space",
"externalId",
"version"
],
"properties": {
"space": {
"description": "Id of the space that the data model belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "External id that uniquely identifies this data model",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"name": {
"type": "string",
"description": "Readable name meant for use in UIs",
"maxLength": 255
},
"description": {
"type": "string",
"description": "Description of the content and intended use of the data model",
"maxLength": 1024
},
"version": {
"type": "string",
"description": "Data model version (opaque string controlled by client applications)",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$",
"minLength": 1,
"maxLength": 43
}
}
},
"DataModel": {
"allOf": [
{
"$ref": "#/components/schemas/DataModelCore"
},
{
"type": "object",
"required": [
"createdTime",
"lastUpdatedTime"
],
"properties": {
"views": {
"type": "array",
"description": "List of views included in this data model. We can expand the views to use the full view definitions, \ni.e. with all the dependent views. \n\nUse the ```InlineViews``` query parameter to request expansion. If you do not set the \n```InlineViews``` query parameter, we will return the references to views instead.\n",
"items": {
"$ref": "#/components/schemas/DataModelProperty"
}
},
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
}
}
}
]
},
"DataModelProperty": {
"anyOf": [
{
"$ref": "#/components/schemas/ViewReference"
},
{
"$ref": "#/components/schemas/ViewDefinition"
}
]
},
"DataModelCreate": {
"allOf": [
{
"$ref": "#/components/schemas/DataModelCore"
},
{
"type": "object",
"properties": {
"views": {
"type": "array",
"description": "List of views included in this data model. You can use a reference to an existing view to specify the new view. Or you can create a new view/update an existing view by including an existing view specification.",
"items": {
"$ref": "#/components/schemas/DataModelCreateProperty"
}
}
}
}
]
},
"DataModelCreateProperty": {
"anyOf": [
{
"$ref": "#/components/schemas/ViewReference"
},
{
"$ref": "#/components/schemas/ViewCreateDefinition"
}
]
},
"ViewCreateDefinition": {
"allOf": [
{
"type": "object",
"required": [
"externalId"
],
"properties": {
"externalId": {
"description": "External id uniquely identifying this view. The values ```Query```, ```Mutation```, ```Subscription```, ```String```, ```Int32```, ```Int64```, ```Int```, ```Float32```, ```Float64```, ```Float```, ```Timestamp```, ```JSONObject```, ```Date```, ```Numeric```, ```Boolean```, ```PageInfo``` and ```TimeSeries``` are reserved.",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
}
}
},
{
"$ref": "#/components/schemas/ViewCommon"
},
{
"type": "object",
"properties": {
"properties": {
"type": "object",
"description": "View with included properties and expected edges, indexed by a unique space-local identifier. The view identifier has to have a length of between 1 and 255 characters. It must also match the pattern ```^[a-zA-Z0-9][a-zA-Z0-9_-]{0,253}[a-zA-Z0-9]?$```, and it cannot be any of the following reserved identifiers: ```space```, ```externalId```, ```createdTime```, ```lastUpdatedTime```, ```deletedTime```, ```edge_id```, ```node_id```, ```project_id```, ```property_group```, ```seq```, ```tg_table_name```, and ```extensions```.",
"maxProperties": 300,
"additionalProperties": {
"x-additionalPropertiesName": "property-identifier",
"allOf": [
{
"$ref": "#/components/schemas/ViewCreateDefinitionProperty"
}
]
}
}
}
}
]
},
"ViewCreateDefinitionProperty": {
"description": "A reference to a container property (ViewProperty) or a relation describing edges that are expected to\nexist (ConnectionDefinition).\n\nIf the referenced container property is a direct relation, a view of the node can be specified. The view is\na hint to the consumer on what type of data is expected to be of interest in the context of this view.\n\nA connection (in this case represented by a relation) describes the edges that are likely to exist to aid\nin discovery and documentation of the view. A listed edge is not required. i.e. It does not have to exist when\nincluded in this list. The target nodes of this relation will match the view specified in the source property.\nA relation has a max distance of one hop in the underlying graph.\n",
"oneOf": [
{
"$ref": "#/components/schemas/CreateViewProperty"
},
{
"$ref": "#/components/schemas/ConnectionDefinition"
}
]
},
"ViewDefinition": {
"allOf": [
{
"type": "object",
"required": [
"externalId"
],
"properties": {
"externalId": {
"description": "External id uniquely identifying this view",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
}
}
},
{
"$ref": "#/components/schemas/ViewCommon"
},
{
"type": "object",
"required": [
"createdTime",
"lastUpdatedTime",
"writable",
"properties",
"usedFor"
],
"properties": {
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"writable": {
"type": "boolean",
"description": "Does the view support write operations, i.e. is it ```writable```? You can write to a view if the view maps all non-nullable properties, and the view has no relations (filters)."
},
"usedFor": {
"$ref": "#/components/schemas/UsedFor"
},
"properties": {
"type": "object",
"description": "List of properties and relations included in this view. The view identifier has to have a length of between 1 and 255 characters. It must also match the pattern ```^[a-zA-Z0-9][a-zA-Z0-9_-]{0,253}[a-zA-Z0-9]?$```.",
"additionalProperties": {
"x-additionalPropertiesName": "view-or-relation-identifier",
"allOf": [
{
"$ref": "#/components/schemas/ViewDefinitionProperty"
}
]
}
}
}
}
]
},
"ViewDefinitionProperty": {
"oneOf": [
{
"$ref": "#/components/schemas/ViewPropertyDefinition"
},
{
"$ref": "#/components/schemas/ConnectionDefinition"
}
]
},
"ViewCommon": {
"type": "object",
"required": [
"space",
"version"
],
"properties": {
"space": {
"description": "Id of the space that the view belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"name": {
"type": "string",
"description": "Readable name, meant for use in UIs",
"maxLength": 255
},
"description": {
"type": "string",
"description": "Description. Intended to describe the content, and use, of this view.",
"maxLength": 1024
},
"filter": {
"$ref": "#/components/schemas/FilterDefinition"
},
"implements": {
"type": "array",
"description": "References to the views from where this view will inherit properties and edges.\n\n\nNote: The order you list the views in is significant. We use this order to deduce the priority when we encounter duplicate property references.\n\n\nIf you do not specify a view version, we will use the most recent version available at the time of creation. ",
"items": {
"$ref": "#/components/schemas/ViewReference"
}
},
"version": {
"$ref": "#/components/schemas/DMSVersion"
}
}
},
"ConnectionDefinition": {
"oneOf": [
{
"$ref": "#/components/schemas/Relation"
}
]
},
"Relation": {
"type": "object",
"required": [
"type",
"source"
],
"description": "Describes the edges that are likely to exist to aid in discovery and documentation of the view. A listed edge is not required. i.e. It does not have to exist when included in this list. The target nodes of this relation will match the view specified in the source property. The edges of this relation will match the view specified in the edgeSource property. A relation has a max distance of one hop.",
"properties": {
"name": {
"type": "string",
"description": "Readable property name.",
"maxLength": 255
},
"description": {
"type": "string",
"description": "Description of the content and suggested use for this property.",
"maxLength": 1024
},
"type": {
"$ref": "#/components/schemas/DirectRelationReference"
},
"source": {
"$ref": "#/components/schemas/ViewReference"
},
"edgeSource": {
"$ref": "#/components/schemas/ViewReference"
},
"direction": {
"type": "string",
"enum": [
"outwards",
"inwards"
],
"default": "outwards"
}
}
},
"ContainerDefinition": {
"required": [
"space",
"externalId",
"properties",
"usedFor",
"createdTime",
"lastUpdatedTime"
],
"allOf": [
{
"$ref": "#/components/schemas/ContainerCreateDefinition"
},
{
"type": "object",
"properties": {
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
}
}
}
]
},
"ContainerCreateDefinition": {
"type": "object",
"description": "Container for properties you can access through views. Container specifications give details about storage related details. For instance, how to index the data, and what constraints should be present. You can define a single container to only contain nodes (```node```), only contain edges (```edge```), or to contain both (```all```).",
"required": [
"space",
"externalId",
"properties"
],
"properties": {
"space": {
"description": "Id of the space the container belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "External-id of the container. The values ```Query```, ```Mutation```, ```Subscription```, ```String```, ```Int32```, ```Int64```, ```Int```, ```Float32```, ```Float64```, ```Float```, ```Timestamp```, ```JSONObject```, ```Date```, ```Numeric```, ```Boolean```, ```PageInfo``` are reserved.",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"name": {
"type": "string",
"description": "Readable name for container meant for use in UIs",
"maxLength": 255
},
"description": {
"type": "string",
"description": "Description of what the property contains, and how you intend to use it.",
"maxLength": 1024
},
"usedFor": {
"$ref": "#/components/schemas/UsedFor"
},
"properties": {
"type": "object",
"description": "We index the property by a local unique identifier. The identifier has to have a length of between 1 and 255 characters. It must also match the pattern ```^[a-zA-Z0-9][a-zA-Z0-9_-]{0,253}[a-zA-Z0-9]?$``` , and it cannot be any of the following reserved identifiers: ```space```, ```externalId```, ```createdTime```, ```lastUpdatedTime```, ```deletedTime```, ```edge_id```, ```node_id```, ```project_id```, ```property_group```, ```seq```, ```tg_table_name```, and ```extensions```.",
"minProperties": 1,
"maxProperties": 300,
"additionalProperties": {
"x-additionalPropertiesName": "containerPropertyIdentifier",
"allOf": [
{
"$ref": "#/components/schemas/ContainerPropertyDefinition"
}
]
}
},
"constraints": {
"type": "object",
"description": "Set of constraints to apply to the container",
"additionalProperties": {
"x-additionalPropertiesName": "constraint-identifier",
"allOf": [
{
"$ref": "#/components/schemas/ConstraintDefinition"
}
]
}
},
"indexes": {
"type": "object",
"description": "Set of indexes to apply to the container. Up to 10 indexes can be added on a container.",
"additionalProperties": {
"x-additionalPropertiesName": "index-identifier",
"allOf": [
{
"$ref": "#/components/schemas/IndexDefinition"
}
]
}
}
}
},
"ConstraintDefinition": {
"type": "object",
"description": "Defines a constraint across the properties you include.\n\n\nYou can use constraints to enforce that;\n * Certain properties must be present,\n * A value must be unique across a single or several properties.\n\nA 'uniqueness' constraint can only apply to properties that are in the same container. Up to 10 'uniqueness' constraints can be added per container. \n\n\nA 'requires' constraint can reference other containers. As a result, the properties in those other containers must then also be set. Up to 25 'requires' constraints can be added per container. ",
"oneOf": [
{
"$ref": "#/components/schemas/RequiresConstraintDefinition"
},
{
"$ref": "#/components/schemas/UniquenessConstraintDefinition"
}
]
},
"UniquenessConstraintDefinition": {
"type": "object",
"required": [
"properties"
],
"properties": {
"constraintType": {
"type": "string",
"enum": [
"uniqueness"
],
"default": "uniqueness"
},
"properties": {
"type": "array",
"description": "List of properties included in the constraint. The order you list the properties in is significant.",
"items": {
"type": "string"
}
}
}
},
"RequiresConstraintDefinition": {
"type": "object",
"required": [
"require"
],
"properties": {
"constraintType": {
"type": "string",
"enum": [
"requires"
],
"default": "requires"
},
"require": {
"$ref": "#/components/schemas/ContainerReference"
}
}
},
"IndexDefinition": {
"type": "object",
"required": [
"properties"
],
"description": "You can optimize query performance by defining an index to apply to a container. You can only create an index across properties belonging to the same container.\n\n\nOrdering of the properties included in the index definition list is significant. The order should match the queries you expect. Once we create an index, you may only change its description. We do not currently support removal of an index.\n\n\nWe support the default index type (B-tree). The B-tree index supports the following operations;\n\n * less than,\n * less than or equal,\n * equality (is equal),\n * larger than or equal, and\n * larger than.\n\n\nIndexes have different requirements for the different property data types. As a result, the create index operation will fail if you specify an invalid combination. ",
"properties": {
"properties": {
"type": "array",
"description": "List of properties to define the index across",
"items": {
"type": "string"
}
},
"indexType": {
"type": "string",
"description": "We currently support the B-tree index.",
"enum": [
"btree"
],
"default": "btree"
}
}
},
"ViewPropertyDefinition": {
"description": "Property definition",
"allOf": [
{
"$ref": "#/components/schemas/ViewCorePropertyDefinition"
},
{
"type": "object",
"required": [
"container",
"containerPropertyIdentifier"
],
"properties": {
"name": {
"type": "string",
"description": "Readable property name.",
"maxLength": 255
},
"description": {
"type": "string",
"description": "Description of the content and suggested use for this property.",
"maxLength": 1024
},
"container": {
"$ref": "#/components/schemas/ContainerReference"
},
"containerPropertyIdentifier": {
"description": "The unique identifier for the mapped property in the referenced container.",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
}
}
}
]
},
"ContainerPropertyDefinition": {
"description": "Defines a property of a container. You can reference this property in views.",
"allOf": [
{
"$ref": "#/components/schemas/ContainerCorePropertyDefinition"
}
]
},
"TypePropertyDefinition": {
"description": "Describes the type and configuration of a property included in the result.",
"allOf": [
{
"$ref": "#/components/schemas/ViewCorePropertyDefinition"
}
]
},
"ViewCorePropertyDefinition": {
"allOf": [
{
"$ref": "#/components/schemas/CorePropertyDefinition"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"description": "The data-type to use when storing the property. Supported storage types are;\n\n\n* single value,\n * lists of text (allows user control of collation),\n * boolean,\n * 32-bit, and 64-bit floats,\n * 32-bit, and 64-bit integers,\n * timestamps,\n * dates,\n * JSON fragments,\n * time series external-id reference,\n * direct relation to an existing node.\n\n\nThe JSON fragments have to be valid JSON objects. If JSON arrays are to be stored, these must be wrapped in a JSON object. JSON values (such as string, number, boolean) should use their respective primitive form instead. The maximum allowed size for a JSON object is 10240 bytes. The maximum allowed length of a key is 128, while the maximum allowed size of a value is 10240 bytes and you can have up to 256 key-value pairs.\nDirect relations use a space external-id, the external-id for an existing node, and the external-id for the data container. E.g. ```s-spaceExternalId.uniqueNodeExternalId.containerExternalId```. The ```view``` property on direct relation can optionally be set, and if it is set then this is a hint to the client on what kind of data is expected to exist.\nTimestamps must be a string in the format 'YYYY-MM-DDTHH:MM:SS[.millis][Z|time zone]' with optional milliseconds having precision of 1-3 decimal digits and optional timezone with format ±HH:MM, ±HHMM, ±HH or Z, where Z represents UTC, Year must be between 0001 and 9999.\nDates must be a date string in the format 'YYYY-MM-DD'. Year must be between 1 and 9999. ",
"oneOf": [
{
"$ref": "#/components/schemas/TextProperty"
},
{
"$ref": "#/components/schemas/PrimitiveProperty"
},
{
"$ref": "#/components/schemas/CDFExternalIdReference"
},
{
"$ref": "#/components/schemas/ViewDirectNodeRelation"
}
]
}
}
}
]
},
"ContainerCorePropertyDefinition": {
"allOf": [
{
"$ref": "#/components/schemas/CorePropertyDefinition"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"description": "The data-type to use when storing the property. Supported storage types are;\n\n\n* single value,\n * lists of text (allows user control of collation),\n * boolean,\n * 32-bit, and 64-bit floats,\n * 32-bit, and 64-bit integers,\n * timestamps,\n * dates,\n * JSON fragments,\n * time series external-id reference,\n * direct relation to an existing node.\n\n\nThe JSON fragments have to be valid JSON objects. If JSON arrays are to be stored, these must be wrapped in a JSON object. JSON values (such as string, number, boolean) should use their respective primitive form instead. The maximum allowed size for a JSON object is 10240 bytes. The maximum allowed length of a key is 128, while the maximum allowed size of a value is 10240 bytes and you can have up to 256 key-value pairs.\nDirect relations use a space external-id, the external-id for an existing node, and the external-id for the data container. E.g. ```s-spaceExternalId.uniqueNodeExternalId.containerExternalId```\nTimestamps must be a string in the format 'YYYY-MM-DDTHH:MM:SS[.millis][Z|time zone]' with optional milliseconds having precision of 1-3 decimal digits and optional timezone with format ±HH:MM, ±HHMM, ±HH or Z, where Z represents UTC, Year must be between 0001 and 9999.\nDates must be a date string in the format 'YYYY-MM-DD'. Year must be between 1 and 9999. ",
"oneOf": [
{
"$ref": "#/components/schemas/TextProperty"
},
{
"$ref": "#/components/schemas/PrimitiveProperty"
},
{
"$ref": "#/components/schemas/CDFExternalIdReference"
},
{
"$ref": "#/components/schemas/DirectNodeRelation"
}
]
}
}
}
]
},
"CorePropertyDefinition": {
"type": "object",
"properties": {
"nullable": {
"type": "boolean",
"description": "Does this property need to be set to a value, or not?",
"default": true
},
"autoIncrement": {
"type": "boolean",
"description": "When set to ```true```, the API will increment the property based on its highest current value (max value). You can only use this functionality to increment properties of type `int32` or `int64`. If the property has a different data type, the API will return an error.",
"default": false
},
"defaultValue": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "object"
}
],
"description": "Default value to use when you do not specify a value for the property. The default value must be of the same type as what you defined for the property itself. \n\n\nWe do not currently support using default values for array/list types. "
},
"description": {
"type": "string",
"description": "Description of the content and suggested use for this property.",
"maxLength": 1024
},
"name": {
"type": "string",
"description": "Readable property name.",
"maxLength": 255
}
}
},
"IncludeTyping": {
"type": "boolean",
"description": "Should we return property type information as part of the result?",
"default": false
},
"RawPropertyValueV3": {
"description": "A value matching the data type of the defined property",
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "array",
"items": {
"type": "boolean"
}
},
{
"type": "array",
"items": {
"type": "number"
}
},
{
"type": "array",
"items": {
"type": "object"
}
}
]
},
"RawPropertyValueListV3": {
"description": "A list of values",
"type": "array",
"items": {
"description": "A value describing the type of the defined property",
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "object"
}
]
}
},
"ParameterizedPropertyValueV3": {
"description": "A parameterized value",
"type": "object",
"required": [
"parameter"
],
"properties": {
"parameter": {
"type": "string"
}
}
},
"ReferencedPropertyValueV3": {
"description": "A property reference value",
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 3
}
}
},
"PropertyValueGroupV3": {
"type": "object",
"description": "Group of property values indexed by a local unique identifier. The identifier has to have a length of between 1 and 255 characters. It must also match the pattern ```^[a-zA-Z0-9][a-zA-Z0-9_-]{0,253}[a-zA-Z0-9]?$``` , and it cannot be any of the following reserved identifiers: ```space```, ```externalId```, ```createdTime```, ```lastUpdatedTime```, ```deletedTime```, and ```extensions```.",
"minProperties": 1,
"maxProperties": 300,
"additionalProperties": {
"x-additionalPropertiesName": "property-identifier",
"allOf": [
{
"$ref": "#/components/schemas/RawPropertyValueV3"
}
]
}
},
"NodeDefinition": {
"type": "object",
"description": "Node",
"required": [
"instanceType",
"space",
"externalId",
"createdTime",
"lastUpdatedTime",
"version"
],
"properties": {
"instanceType": {
"type": "string",
"enum": [
"node"
]
},
"version": {
"description": "Current version of the node",
"type": "integer"
},
"space": {
"description": "Id of the space that the node belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "Unique identifier for the node",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"deletedTime": {
"description": "Timestamp when the node was soft deleted. Note that deleted nodes are filtered out of query results, but present in sync results. This means that this value will only be present in sync results.",
"allOf": [
{
"$ref": "#/components/schemas/EpochTimestamp"
}
]
},
"properties": {
"type": "object",
"description": "Spaces for the requested view and its containers",
"additionalProperties": {
"x-additionalPropertiesName": "space-name",
"allOf": [
{
"$ref": "#/components/schemas/ViewOrContainer"
}
]
}
}
}
},
"SlimNodeDefinition": {
"type": "object",
"description": "Node",
"required": [
"instanceType",
"space",
"externalId",
"wasModified",
"version"
],
"properties": {
"instanceType": {
"type": "string",
"enum": [
"node"
]
},
"version": {
"description": "Current version of the node",
"type": "integer"
},
"wasModified": {
"description": "Whether or not the node was modified by this ingestion. We only update the nodes if the input differs from the existing state.",
"type": "boolean"
},
"space": {
"description": "Id of the space that the node belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "Unique identifier for the node",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
}
}
},
"NodeWrite": {
"description": "Node to create or update",
"type": "object",
"required": [
"instanceType",
"space",
"externalId"
],
"properties": {
"instanceType": {
"type": "string",
"enum": [
"node"
],
"default": "node"
},
"existingVersion": {
"description": "Fail the ingestion request if the node's version is greater than or equal to this value. If no existingVersion is specified, the ingestion will always overwrite any existing data for the edge (for the specified container or view). If existingVersion is set to 0, the upsert will behave as an insert, so it will fail the bulk if the item already exists. If skipOnVersionConflict is set on the ingestion request, then the item will be skipped instead of failing the ingestion request.",
"type": "integer"
},
"space": {
"description": "Id of the space that the node belongs to. This space-id cannot be updated.",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "Unique identifier for the node",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"sources": {
"type": "array",
"description": "List of source properties to write. The properties are from the view and/or the container(s) making up this node.",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/EdgeOrNodeData"
}
}
}
},
"EdgeOrNodeData": {
"type": "object",
"description": "Property values for the identified/specified view or container",
"properties": {
"source": {
"$ref": "#/components/schemas/SourceReference"
},
"properties": {
"$ref": "#/components/schemas/PropertyValueGroupV3"
}
},
"required": [
"source"
]
},
"EdgeDefinition": {
"type": "object",
"description": "Edge",
"required": [
"instanceType",
"type",
"space",
"externalId",
"createdTime",
"lastUpdatedTime",
"startNode",
"endNode",
"version"
],
"properties": {
"instanceType": {
"type": "string",
"enum": [
"edge"
]
},
"version": {
"description": "Current version of the edge",
"type": "integer"
},
"type": {
"description": "Edge relationship type",
"allOf": [
{
"$ref": "#/components/schemas/DirectRelationReference"
}
]
},
"space": {
"description": "Id of the space the edge belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "Unique identifier for the edge. Can also be a null character.",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"deletedTime": {
"description": "Timestamp when the edge was soft deleted. Note that deleted edges are filtered out of query results, but present in sync results. This means that this value will only be present in sync results.",
"allOf": [
{
"$ref": "#/components/schemas/EpochTimestamp"
}
]
},
"properties": {
"type": "object",
"description": "Spaces for the requested view and its containers",
"additionalProperties": {
"$ref": "#/components/schemas/ViewOrContainer"
}
},
"startNode": {
"$ref": "#/components/schemas/DirectRelationReference"
},
"endNode": {
"$ref": "#/components/schemas/DirectRelationReference"
}
}
},
"NodeReference": {
"type": "object",
"description": "Node reference",
"required": [
"space",
"externalId"
],
"properties": {
"space": {
"description": "Id for the space of the node referenced",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "External-id for the node referenced. Can also be a null character.",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
}
}
},
"SlimEdgeDefinition": {
"type": "object",
"description": "Edge",
"required": [
"instanceType",
"space",
"externalId",
"wasModified",
"version"
],
"properties": {
"instanceType": {
"type": "string",
"enum": [
"edge"
]
},
"version": {
"description": "Current version of the edge",
"type": "integer"
},
"wasModified": {
"description": "Whether or not the edge was modified by this ingestion. We only update the edges if the input differs from the existing state.",
"type": "boolean"
},
"space": {
"description": "Id of the space that the edge belongs to",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "Unique alphanumeric identifier for the edge",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
}
}
},
"EdgeWrite": {
"description": "Edge to create or update",
"type": "object",
"required": [
"instanceType",
"space",
"externalId",
"startNode",
"endNode",
"type"
],
"properties": {
"instanceType": {
"type": "string",
"enum": [
"edge"
],
"default": "edge"
},
"existingVersion": {
"description": "Fail the ingestion request if the edge's version is greater than or equal to this value. If no existingVersion is specified, the ingestion will always overwrite any existing data for the edge (for the specified container or view). If existingVersion is set to 0, the upsert will behave as an insert, so it will fail the bulk if the item already exists. If skipOnVersionConflict is set on the ingestion request, then the item will be skipped instead of failing the ingestion request.",
"type": "integer"
},
"type": {
"description": "Edge type (direct relation)",
"allOf": [
{
"$ref": "#/components/schemas/DirectRelationReference"
}
]
},
"space": {
"description": "Id of the space that the edge belongs to. This id cannot be updated.",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"externalId": {
"description": "Unique alphanumeric identifier for the edge",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"startNode": {
"$ref": "#/components/schemas/DirectRelationReference"
},
"endNode": {
"$ref": "#/components/schemas/DirectRelationReference"
},
"sources": {
"type": "array",
"description": "Properties to write to in a view or container, for the edge.",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/EdgeOrNodeData"
}
}
}
},
"FilterDefinition": {
"type": "object",
"description": "A filter Domain Specific Language (DSL) used to create advanced filter queries.",
"oneOf": [
{
"$ref": "#/components/schemas/DataModelsBoolFilter"
},
{
"$ref": "#/components/schemas/DataModelsLeafFilter"
}
],
"example": {
"and": [
{
"in": {
"property": [
"tag"
],
"values": [
"1001_1",
"1001_1"
]
}
},
{
"range": {
"property": [
"weight"
],
"gte": 0
}
}
]
}
},
"TableExpressionFilterDefinition": {
"type": "object",
"description": "A filter Domain Specific Language (DSL) used to create advanced filter queries.",
"oneOf": [
{
"$ref": "#/components/schemas/TableExpressionDataModelsBoolFilter"
},
{
"$ref": "#/components/schemas/TableExpressionLeafFilter"
}
],
"example": {
"and": [
{
"in": {
"property": [
"tag"
],
"values": [
"1001_1",
"1001_1"
]
}
},
{
"range": {
"property": [
"weight"
],
"gte": 0
}
}
]
}
},
"DataModelsBoolFilter": {
"title": "BoolFilter",
"description": "Build a new query by combining other queries, using boolean operators. We support the `and`, `or`, and\n`not` boolean operators.\n",
"type": "object",
"oneOf": [
{
"type": "object",
"title": "and",
"required": [
"and"
],
"properties": {
"and": {
"description": "All the sub-clauses in the query must return a matching item.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/FilterDefinition"
}
}
}
},
{
"type": "object",
"title": "or",
"required": [
"or"
],
"properties": {
"or": {
"description": "One or more of the sub-clauses in the query must return a matching item.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/FilterDefinition"
}
}
}
},
{
"type": "object",
"title": "not",
"required": [
"not"
],
"properties": {
"not": {
"title": "Filter DSL",
"description": "None of the sub-clauses in the query can return a matching item.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/FilterDefinition"
}
]
}
}
}
]
},
"TableExpressionDataModelsBoolFilter": {
"title": "BoolFilter",
"description": "Build a new query by combining other queries, using boolean operators. We support the `and`, `or`, and\n`not` boolean operators.\n",
"type": "object",
"oneOf": [
{
"type": "object",
"title": "and",
"required": [
"and"
],
"properties": {
"and": {
"description": "All the sub-clauses in the query must return a matching item.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
}
}
}
},
{
"type": "object",
"title": "or",
"required": [
"or"
],
"properties": {
"or": {
"description": "One or more of the sub-clauses in the query must return a matching item.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
}
}
}
},
{
"type": "object",
"title": "not",
"required": [
"not"
],
"properties": {
"not": {
"title": "Filter DSL",
"description": "None of the sub-clauses in the query can return a matching item.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
}
]
}
}
}
]
},
"DataModelsLeafFilter": {
"description": "Leaf filter",
"title": "LeafFilter",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/EqualsFilterV3"
},
{
"$ref": "#/components/schemas/InFilterV3"
},
{
"$ref": "#/components/schemas/RangeFilterV3"
},
{
"$ref": "#/components/schemas/PrefixFilterV3"
},
{
"$ref": "#/components/schemas/ExistsFilter"
},
{
"$ref": "#/components/schemas/ContainsAnyFilterV3"
},
{
"$ref": "#/components/schemas/ContainsAllFilterV3"
},
{
"$ref": "#/components/schemas/MatchAllFilter"
},
{
"$ref": "#/components/schemas/DataModelsNestedFilter"
},
{
"$ref": "#/components/schemas/OverlapsFilterV3"
},
{
"$ref": "#/components/schemas/HasExistingDataFilterV3"
}
]
},
"TableExpressionLeafFilter": {
"description": "Leaf filter",
"title": "LeafFilter",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/TableExpressionEqualsFilterV3"
},
{
"$ref": "#/components/schemas/TableExpressionInFilterV3"
},
{
"$ref": "#/components/schemas/TableExpressionRangeFilterV3"
},
{
"$ref": "#/components/schemas/TableExpressionPrefixFilterV3"
},
{
"$ref": "#/components/schemas/ExistsFilter"
},
{
"$ref": "#/components/schemas/TableExpressionContainsAnyFilterV3"
},
{
"$ref": "#/components/schemas/TableExpressionContainsAllFilterV3"
},
{
"$ref": "#/components/schemas/MatchAllFilter"
},
{
"$ref": "#/components/schemas/DataModelsNestedFilter"
},
{
"$ref": "#/components/schemas/TableExpressionOverlapsFilterV3"
},
{
"$ref": "#/components/schemas/HasExistingDataFilterV3"
}
]
},
"NodeOrEdgeDeleteRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "object",
"required": [
"instanceType",
"space",
"externalId"
],
"properties": {
"instanceType": {
"description": "Is the item to delete a node, or an edge",
"type": "string",
"enum": [
"node",
"edge"
]
},
"externalId": {
"description": "External id for the node or edge (item) you want to delete.",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"space": {
"description": "Space that the described node or edge (item) belongs to.",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
}
}
}
}
}
},
"NodeOrEdgeListRequestV3": {
"allOf": [
{
"type": "object",
"properties": {
"includeTyping": {
"$ref": "#/components/schemas/IncludeTyping"
},
"sources": {
"$ref": "#/components/schemas/SourceSelectorWithoutPropertiesV3"
},
"instanceType": {
"description": "The type of instance you are querying for; an edge or a node. If the instance type isn't specified, we list nodes.",
"default": "node",
"allOf": [
{
"$ref": "#/components/schemas/InstanceType"
}
]
}
}
},
{
"$ref": "#/components/schemas/Cursor"
},
{
"$ref": "#/components/schemas/LimitWithDefault1000"
},
{
"$ref": "#/components/schemas/SortV3"
},
{
"type": "object",
"properties": {
"filter": {
"$ref": "#/components/schemas/FilterDefinition"
}
}
}
]
},
"DataModelsListRequest": {
"allOf": [
{
"$ref": "#/components/schemas/Cursor"
},
{
"$ref": "#/components/schemas/ReducedLimit"
},
{
"type": "object",
"required": [
"filter"
],
"properties": {
"spaces": {
"type": "array",
"description": "List of spaces you want to use to limit the returned matches by",
"items": {
"$ref": "#/components/schemas/SpaceSpecification"
}
},
"filter": {
"$ref": "#/components/schemas/FilterDefinition"
},
"allVersions": {
"$ref": "#/components/schemas/AllVersionsFlag"
},
"sort": {
"description": "Specifies how you want to sort the data model information",
"type": "array",
"items": {
"$ref": "#/components/schemas/DataModelsSort"
}
}
}
}
]
},
"DataModelsSort": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"description": "The property we should base sorting on when we return ordered data",
"type": "string",
"enum": [
"space",
"externalId",
"name",
"description",
"version",
"createdTime",
"lastUpdatedTime"
]
},
"direction": {
"description": "The sort order for the returned information",
"type": "string",
"default": "ascending",
"enum": [
"ascending",
"descending"
]
},
"nullsFirst": {
"description": "Should we list nulls first, or last (default) in the returned dataset",
"type": "boolean",
"default": false
}
}
},
"QueryRequest": {
"type": "object",
"required": [
"with",
"select"
],
"properties": {
"with": {
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "result-expression-name",
"allOf": [
{
"$ref": "#/components/schemas/QueryTableExpressionV3"
}
]
}
},
"cursors": {
"description": "Cursors returned from the previous query request. These cursors match the result set expressions you specified in the ```with``` clause for the query.",
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "pagination cursor reference",
"allOf": [
{
"$ref": "#/components/schemas/NextCursorV3"
}
]
}
},
"select": {
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "result-expression-name",
"allOf": [
{
"$ref": "#/components/schemas/QuerySelectV3"
}
]
}
},
"parameters": {
"type": "object",
"description": "Values in filters can be parameterised. Parameters are provided as part of the query object, and referenced in the filter itself.",
"additionalProperties": {
"x-additionalPropertiesName": "parameter-identifier",
"allOf": [
{
"$ref": "#/components/schemas/RawPropertyValueV3"
}
]
}
}
}
},
"SyncRequest": {
"type": "object",
"required": [
"with",
"select"
],
"properties": {
"with": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/SyncTableExpressionV3"
}
},
"cursors": {
"description": "Cursors returned from the previous sync request. These cursors match the result set expressions you specified in the ```with``` clause for the sync.",
"type": "object",
"additionalProperties": {
"x-additionalPropertiesName": "sync cursor reference",
"allOf": [
{
"$ref": "#/components/schemas/NextCursorV3"
}
]
}
},
"select": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/SyncSelectV3"
}
},
"parameters": {
"type": "object",
"description": "Parameters to return",
"additionalProperties": {
"x-additionalPropertiesName": "parameter-identifier",
"allOf": [
{
"$ref": "#/components/schemas/RawPropertyValueV3"
}
]
}
}
}
},
"AggregationRequest": {
"oneOf": [
{
"$ref": "#/components/schemas/ViewAggregationRequest"
}
]
},
"ViewAggregationRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CommonAggregationRequest"
},
{
"type": "object",
"required": [
"view"
],
"properties": {
"instanceType": {
"$ref": "#/components/schemas/InstanceType"
},
"view": {
"$ref": "#/components/schemas/ViewReference"
}
}
}
]
},
"ContainerAggregationRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CommonAggregationRequest"
},
{
"type": "object",
"required": [
"container",
"instanceType"
],
"properties": {
"instanceType": {
"$ref": "#/components/schemas/InstanceType"
},
"container": {
"$ref": "#/components/schemas/ContainerReference"
}
}
}
]
},
"CommonAggregationRequest": {
"description": "Defines an aggregation request. This will let you group, and aggregate supported data types. The request supports filters, and allows optional search matching.",
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Optional query string. The API will parse the query string, and use it to match the text properties on elements to use for the aggregate(s)."
},
"properties": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"description": "Optional list (array) of properties you want to apply the query above to. If you do not list any properties, you search through text fields by default.",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer",
"description": "Limit the number of results returned. The default limit is currently at 100 items.",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"cursor": {
"description": "A cursor value. Use the cursor to page through the returned data.",
"type": "string",
"example": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
},
"aggregates": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/AggregationDefinition"
}
},
"groupBy": {
"type": "array",
"description": "The selection of fields to group the results by when doing aggregations. You can specify up to 5 items \nto group by.\n\nWhen you do not specify any aggregates, the fields listed in the `groupBy` clause will return the unique \nvalues stored for each field.\n",
"minItems": 1,
"maxItems": 5,
"items": {
"type": "string"
}
},
"filter": {
"$ref": "#/components/schemas/FilterDefinition"
}
}
},
"AggregatedResultItemCollection": {
"required": [
"items",
"properties"
],
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AggregatedResultItem"
}
}
}
},
"AggregatedResultItem": {
"type": "object",
"required": [
"instanceType",
"aggregates"
],
"properties": {
"instanceType": {
"$ref": "#/components/schemas/InstanceType"
},
"group": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"example": {
"name": "PumpName1",
"tag": "tag01"
}
},
"aggregates": {
"type": "array",
"minItems": 1,
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/AggregatedValueItem"
}
}
}
},
"AggregatedValueItem": {
"oneOf": [
{
"$ref": "#/components/schemas/AggregatedNumberValue"
},
{
"$ref": "#/components/schemas/AggregatedHistogramValue"
}
]
},
"AggregatedNumberValue": {
"type": "object",
"required": [
"aggregate"
],
"properties": {
"aggregate": {
"type": "string",
"example": "avg",
"enum": [
"avg",
"min",
"max",
"count",
"sum"
]
},
"property": {
"description": "The property the aggregate was calculated from",
"type": "string",
"example": "duration"
},
"value": {
"type": "number",
"description": "Value returned by the aggregate function",
"example": 0.2
}
}
},
"AggregatedHistogramValue": {
"type": "object",
"required": [
"aggregate",
"interval",
"property",
"buckets"
],
"properties": {
"aggregate": {
"type": "string",
"enum": [
"histogram"
]
},
"interval": {
"type": "number",
"example": 50
},
"property": {
"type": "string",
"example": "duration"
},
"buckets": {
"type": "array",
"description": "List (array) of buckets to use for histogram aggregates.",
"items": {
"type": "object",
"required": [
"start",
"count"
],
"properties": {
"start": {
"description": "Start value for a histogram bucket",
"type": "number",
"example": 1050
},
"count": {
"description": "Number of items in the histogram bucket",
"type": "integer",
"example": 7
}
}
}
}
}
},
"NodeOrEdgeSearchRequest": {
"description": "Searching nodes or edges using properties from a view",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/SearchRequestV3"
}
]
},
"SearchRequestV3": {
"allOf": [
{
"type": "object",
"required": [
"view"
],
"properties": {
"view": {
"$ref": "#/components/schemas/ViewReference"
},
"query": {
"type": "string",
"description": "Query string that will be parsed and used for search."
},
"instanceType": {
"description": "Limit the search query to searching nodes or edges. Unless you set the item type to apply the search to, the service will default to searching nodes within the view.",
"allOf": [
{
"$ref": "#/components/schemas/InstanceType"
}
]
},
"properties": {
"type": "array",
"description": "Optional array of properties you want to search through. If you do not specify one or more properties, the service will search all text fields within the view.",
"items": {
"type": "string"
}
},
"filter": {
"$ref": "#/components/schemas/FilterDefinition"
}
}
},
{
"$ref": "#/components/schemas/LimitWithDefault1000"
}
]
},
"ViewCreateCollection": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "List of views to create/update",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/ViewCreateDefinition"
}
}
}
},
"ContainerCreateCollection": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "List of containers to create/update",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/ContainerCreateDefinition"
}
}
}
},
"DataModelCreateCollection": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "List of data models to create/update",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/DataModelCreate"
}
}
}
},
"NodeAndEdgeCreateCollection": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "List of nodes and edges to create/update",
"minItems": 1,
"maxItems": 1000,
"items": {
"$ref": "#/components/schemas/NodeOrEdgeCreate"
}
},
"autoCreateStartNodes": {
"type": "boolean",
"description": "Should we create missing start nodes for edges when ingesting? By default, the start node of an edge must exist before we can ingest the edge.",
"default": false
},
"autoCreateEndNodes": {
"type": "boolean",
"default": false,
"description": "Should we create missing end nodes for edges when ingesting? By default, the end node of an edge must exist before we can ingest the edge."
},
"skipOnVersionConflict": {
"type": "boolean",
"default": false,
"description": "If existingVersion is specified on any of the nodes/edges in the input, the default behaviour is that the entire ingestion will fail when version conflicts occur. If skipOnVersionConflict is set to true, items with version conflicts will be skipped instead. If no version is specified for nodes/edges, it will do the write directly."
},
"replace": {
"type": "boolean",
"description": "How do we behave when a property value exists? Do we replace all matching and existing values with the supplied values (`true`)? Or should we merge in new values for properties together with the existing values (`false`)? Note: This setting applies for all nodes or edges specified in the ingestion call.",
"default": false
}
}
},
"NodeOrEdgeCreate": {
"oneOf": [
{
"$ref": "#/components/schemas/NodeWrite"
},
{
"$ref": "#/components/schemas/EdgeWrite"
}
]
},
"SpaceCreateCollection": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "List of spaces to create/update",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/SpaceCreateDefinition"
}
}
}
},
"SpaceCreateDefinition": {
"type": "object",
"required": [
"space"
],
"properties": {
"space": {
"type": "string",
"description": "The Space identifier (id).\n\n\nNote that we have reserved the use of certain space ids. These reserved spaces are:\n * `space`\n * `cdf`\n * `dms`\n * `pg3`\n * `shared`\n * `system`\n * `node`\n * `edge`\n ",
"pattern": "(?!^(space|cdf|dms|pg3|shared|system|node|edge)$)(^[a-zA-Z][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$)",
"minLength": 1,
"maxLength": 43
},
"description": {
"type": "string",
"description": "Used to describe the space you're defining.",
"maxLength": 1024
},
"name": {
"type": "string",
"description": "Human-readable name for the space.",
"maxLength": 255
}
}
},
"SpaceDefinition": {
"allOf": [
{
"$ref": "#/components/schemas/SpaceCreateDefinition"
},
{
"type": "object",
"required": [
"createdTime",
"lastUpdatedTime"
],
"properties": {
"createdTime": {
"$ref": "#/components/schemas/EpochTimestamp"
},
"lastUpdatedTime": {
"$ref": "#/components/schemas/EpochTimestamp"
}
}
}
]
},
"UpsertConflict": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"description": "Details about the error caused by the upsert/update.",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"description": "The HTTP status code returned",
"format": "int32",
"example": 409
},
"message": {
"type": "string",
"description": "The error message returned from the service."
}
}
}
}
},
"ListOfSpaceIdsRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"space"
],
"properties": {
"space": {
"description": "Ids for the spaces to perform operations on",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
}
}
}
}
}
},
"ListOfSpaceExternalIdsRequest": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"space",
"externalId"
],
"properties": {
"externalId": {
"description": "External ids for the requested items",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"space": {
"$ref": "#/components/schemas/SpaceSpecification"
}
}
}
}
}
},
"ListOfSpaceExternalIdsRequestWithTyping": {
"type": "object",
"required": [
"items"
],
"properties": {
"sources": {
"$ref": "#/components/schemas/SourceSelectorWithoutPropertiesV3"
},
"items": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "object",
"required": [
"instanceType",
"space",
"externalId"
],
"properties": {
"sources": {
"type": "array",
"description": "This field is deprecated and will be removed before GA. Use the `sources` field at the request-level instead.",
"deprecated": true,
"maxItems": 10,
"items": {
"type": "object",
"required": [
"source"
],
"properties": {
"source": {
"$ref": "#/components/schemas/ViewReference"
}
}
}
},
"instanceType": {
"description": "The type of instance being returned, an edge or a node.",
"allOf": [
{
"$ref": "#/components/schemas/InstanceType"
}
]
},
"externalId": {
"description": "External ids for the requested items",
"allOf": [
{
"$ref": "#/components/schemas/NodeOrEdgeExternalId"
}
]
},
"space": {
"$ref": "#/components/schemas/SpaceSpecification"
}
}
}
},
"includeTyping": {
"$ref": "#/components/schemas/IncludeTyping"
}
}
},
"ListOfVersionReferences": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"space",
"externalId",
"version"
],
"properties": {
"externalId": {
"description": "External id for the requested item",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"space": {
"description": "Space id for the requested item",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"version": {
"description": "Version of the requested item",
"allOf": [
{
"$ref": "#/components/schemas/DMSVersion"
}
]
}
}
}
}
}
},
"ListOfAllVersionsReferences": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"space",
"externalId"
],
"properties": {
"externalId": {
"description": "External id for the requested item",
"allOf": [
{
"$ref": "#/components/schemas/DMSExternalId"
}
]
},
"space": {
"description": "Space id for the requested item",
"allOf": [
{
"$ref": "#/components/schemas/SpaceSpecification"
}
]
},
"version": {
"description": "Version of the requested item",
"allOf": [
{
"$ref": "#/components/schemas/DMSVersion"
}
]
}
}
}
}
}
},
"NextCursorV3": {
"description": "The cursor value used to return (paginate to) the next page of results, when more data is available.",
"type": "string"
},
"MultiNextCursorV3": {
"description": "Cursors to paginate to the next page of results. The cursor applies to each result set expression. We only provide a cursor when more data is available.",
"type": "object",
"properties": {
"additionalProperties": {
"x-additionalPropertiesName": "cursor-name",
"allOf": [
{
"$ref": "#/components/schemas/NextCursorV3"
}
]
}
}
},
"AggregationDefinition": {
"type": "object",
"description": "An aggregate. It consists of a name, an aggregator function, and the field to use for the function.",
"oneOf": [
{
"$ref": "#/components/schemas/AvgAggregateFunctionV3"
},
{
"$ref": "#/components/schemas/CountAggregateFunctionV3"
},
{
"$ref": "#/components/schemas/MinAggregateFunctionV3"
},
{
"$ref": "#/components/schemas/MaxAggregateFunctionV3"
},
{
"$ref": "#/components/schemas/SumAggregateFunctionV3"
},
{
"$ref": "#/components/schemas/HistogramAggregateFunctionV3"
}
]
},
"CountAggregateFunctionV3": {
"title": "count",
"type": "object",
"description": "Counts the number of items. When you specify a property, it returns the number of non-null values for that property.",
"required": [
"count"
],
"properties": {
"count": {
"type": "object",
"properties": {
"property": {
"type": "string",
"description": "The property to count. If specified, counts all non-null values for the specified property."
}
}
}
}
},
"AvgAggregateFunctionV3": {
"type": "object",
"title": "avg",
"description": "Calculates the average from the data stored by the specified property. This aggregation uses an average mean calculation, and not an integral mean.",
"required": [
"avg"
],
"properties": {
"avg": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "string",
"description": "The property who's data we use to calculate the average from. This property needs to be a defined-as-numerical property."
}
}
}
}
},
"MaxAggregateFunctionV3": {
"type": "object",
"title": "max",
"description": "The function will calculate, and return, the highest - max - value for the property.",
"required": [
"max"
],
"properties": {
"max": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "string",
"description": "The property who's data we use to generate the max value from. This property needs to be a defined-as-numerical property."
}
}
}
}
},
"MinAggregateFunctionV3": {
"type": "object",
"title": "min",
"description": "The function will calculate, and return, the lowest - min - value for a property.",
"required": [
"min"
],
"properties": {
"min": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "string",
"description": "The property who's data we use to generate the min value from. This property needs to be a defined-as-numerical property."
}
}
}
}
},
"HistogramAggregateFunctionV3": {
"type": "object",
"title": "histogram",
"description": "A histogram aggregator function. This function will generate a histogram from the values of the specified property. It uses the specified interval as defined in your `interval` argument.",
"required": [
"histogram"
],
"properties": {
"histogram": {
"type": "object",
"required": [
"property",
"interval"
],
"properties": {
"property": {
"type": "string",
"description": "The property who's data we use to generate the histogram. This property needs to be a defined-as-numerical property."
},
"interval": {
"type": "number",
"description": "The interval between each bucket."
}
}
}
}
},
"SumAggregateFunctionV3": {
"type": "object",
"title": "sum",
"description": "Calculates the sum from the values of the specified property.",
"required": [
"sum"
],
"properties": {
"sum": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"type": "string",
"description": "The property who's data we use to calculate the sum of. This property needs to be a defined-as-numerical property."
}
}
}
}
},
"SyncTableExpressionV3": {
"oneOf": [
{
"$ref": "#/components/schemas/SyncNodeTableExpressionV3"
},
{
"$ref": "#/components/schemas/SyncEdgeTableExpressionV3"
}
]
},
"SyncNodeTableExpressionV3": {
"type": "object",
"required": [
"nodes"
],
"description": "The synchronization query to use when we listen for changes to nodes. The nodes must also match the specified filter.",
"properties": {
"limit": {
"type": "integer"
},
"nodes": {
"type": "object",
"properties": {
"from": {
"description": "Chain your result expression from the specified view, or container.",
"type": "string"
},
"through": {
"$ref": "#/components/schemas/ViewPropertyReference"
},
"filter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
}
}
}
}
},
"SyncEdgeTableExpressionV3": {
"type": "object",
"required": [
"edges"
],
"description": "The synchronization query to use when we listen for changes to edges. The edges must also match the specified filter.",
"properties": {
"limit": {
"type": "integer"
},
"edges": {
"type": "object",
"properties": {
"from": {
"description": "Chain your result expression from this query.",
"type": "string"
},
"maxDistance": {
"description": "The largest - max - number of levels to traverse when resolving the query.",
"type": "integer"
},
"direction": {
"description": "The direction to use when traversing.",
"type": "string",
"enum": [
"outwards",
"inwards"
]
},
"filter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
},
"nodeFilter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
},
"terminationFilter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
}
}
}
}
},
"QueryTableExpressionV3": {
"oneOf": [
{
"$ref": "#/components/schemas/QueryNodeTableExpressionV3"
},
{
"$ref": "#/components/schemas/QueryEdgeTableExpressionV3"
},
{
"$ref": "#/components/schemas/QuerySetOperationTableExpressionV3"
}
],
"type": "object"
},
"QueryNodeTableExpressionV3": {
"type": "object",
"required": [
"nodes"
],
"properties": {
"sort": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/PropertySortV3"
}
},
"limit": {
"type": "integer"
},
"nodes": {
"type": "object",
"properties": {
"from": {
"description": "Chain your result-expression based on this view.",
"type": "string"
},
"through": {
"$ref": "#/components/schemas/ViewPropertyReference"
},
"filter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
}
}
}
}
},
"QueryEdgeTableExpressionV3": {
"type": "object",
"required": [
"edges"
],
"properties": {
"sort": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/PropertySortV3"
}
},
"postSort": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/PropertySortV3"
}
},
"limit": {
"type": "integer"
},
"edges": {
"type": "object",
"properties": {
"from": {
"description": "Chain your result expression from this edge.",
"type": "string"
},
"maxDistance": {
"description": "The largest - max - number of levels to traverse.",
"type": "integer"
},
"direction": {
"description": "The direction to use when traversing.",
"type": "string",
"default": "outwards",
"enum": [
"outwards",
"inwards"
]
},
"filter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
},
"nodeFilter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
},
"terminationFilter": {
"$ref": "#/components/schemas/TableExpressionFilterDefinition"
},
"limitEach": {
"type": "integer",
"description": "Limit the number of returned edges for each of the source nodes in the result set. The indicated uniform limit applies to the result set from the referenced `from`. `limitEach` only has meaning when you also specify `maxDistance=1` and `from`.",
"minimum": 1,
"maximum": 2000
}
}
}
}
},
"QuerySetOperationTableExpressionV3": {
"oneOf": [
{
"$ref": "#/components/schemas/QueryUnionAllTableExpressionV3"
},
{
"$ref": "#/components/schemas/QueryUnionTableExpressionV3"
},
{
"$ref": "#/components/schemas/QueryIntersectionTableExpressionV3"
}
],
"type": "object"
},
"QueryUnionAllTableExpressionV3": {
"type": "object",
"description": "Return the union of the specified result sets. We will remove the results that match the optional exception \nresult sets. Note: The operation may return duplicate results since we do not perform deduplication.\n",
"required": [
"unionAll"
],
"properties": {
"unionAll": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/QuerySetOperationTableExpressionV3"
},
{
"type": "string"
}
]
}
},
"except": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer"
}
}
},
"QueryUnionTableExpressionV3": {
"description": "Return the union of the specified result sets. We will remove the results that match the optional \nexception result sets. But this operation does not result in duplicate results as it performs \ndeduplication. \n\nNote: You should use the `unionAll` operation whenever possible. Using it enables a built-in optimization. \nI.e. `A unionAll B` with `limit: n` will execute set operation B, if and only if, A returns less than \nn records.\n",
"type": "object",
"required": [
"union"
],
"properties": {
"union": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/QuerySetOperationTableExpressionV3"
},
{
"type": "string"
}
]
}
},
"except": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer"
}
}
},
"QueryIntersectionTableExpressionV3": {
"type": "object",
"description": "Find the common elements in the returned result set. Excludes the elements from the optional `except` result set.",
"required": [
"intersection"
],
"properties": {
"intersection": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/QuerySetOperationTableExpressionV3"
},
{
"type": "string"
}
]
}
},
"except": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer"
}
}
},
"SortV3": {
"type": "object",
"properties": {
"sort": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/PropertySortV3"
}
}
}
},
"PropertySortV3": {
"type": "object",
"required": [
"property"
],
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"direction": {
"type": "string",
"default": "ascending",
"enum": [
"ascending",
"descending"
]
},
"nullsFirst": {
"type": "boolean",
"default": false
}
}
},
"SourceSelectorWithoutPropertiesV3": {
"type": "array",
"description": "Retrieve properties from the listed - by reference - views.",
"maxItems": 10,
"items": {
"type": "object",
"required": [
"source"
],
"properties": {
"source": {
"$ref": "#/components/schemas/ViewReference"
}
}
}
},
"SourceSelectorV3": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"required": [
"source",
"properties"
],
"properties": {
"source": {
"$ref": "#/components/schemas/ViewReference"
},
"properties": {
"type": "array",
"description": "Regex patterns we will use to select the properties to return from the view.",
"items": {
"type": "string"
}
}
}
}
},
"QuerySelectV3": {
"type": "object",
"description": "Define which view to return properties for, and the properties to return. Up to 10 views can be specified per query.",
"properties": {
"sources": {
"$ref": "#/components/schemas/SourceSelectorV3"
},
"sort": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PropertySortV3"
}
},
"limit": {
"type": "integer"
}
}
},
"SyncSelectV3": {
"type": "object",
"description": "Specify the container or view to return properties for. Also specify the properties for those containers/views to return. Up to 10 views can be specified.",
"properties": {
"sources": {
"$ref": "#/components/schemas/SourceSelectorV3"
}
}
},
"SourceReference": {
"description": "Reference to a view, or a container",
"oneOf": [
{
"$ref": "#/components/schemas/ViewReference"
},
{
"$ref": "#/components/schemas/ContainerReference"
}
],
"discriminator": {
"propertyName": "type"
}
},
"FilterValue": {
"oneOf": [
{
"$ref": "#/components/schemas/RawPropertyValueV3"
},
{
"$ref": "#/components/schemas/ReferencedPropertyValueV3"
}
]
},
"TableExpressionFilterValue": {
"oneOf": [
{
"$ref": "#/components/schemas/RawPropertyValueV3"
},
{
"$ref": "#/components/schemas/ParameterizedPropertyValueV3"
},
{
"$ref": "#/components/schemas/ReferencedPropertyValueV3"
}
]
},
"FilterValueList": {
"oneOf": [
{
"$ref": "#/components/schemas/RawPropertyValueListV3"
},
{
"$ref": "#/components/schemas/ReferencedPropertyValueV3"
}
]
},
"TableExpressionFilterValueList": {
"oneOf": [
{
"$ref": "#/components/schemas/RawPropertyValueListV3"
},
{
"$ref": "#/components/schemas/ParameterizedPropertyValueV3"
},
{
"$ref": "#/components/schemas/ReferencedPropertyValueV3"
}
]
},
"FilterValueRange": {
"oneOf": [
{
"$ref": "#/components/schemas/RangeValue"
},
{
"$ref": "#/components/schemas/ReferencedPropertyValueV3"
}
]
},
"TableExpressionFilterValueRange": {
"oneOf": [
{
"$ref": "#/components/schemas/RangeValue"
},
{
"$ref": "#/components/schemas/ParameterizedPropertyValueV3"
},
{
"$ref": "#/components/schemas/ReferencedPropertyValueV3"
}
]
},
"DataModelsNestedFilter": {
"type": "object",
"title": "nested",
"required": [
"nested"
],
"properties": {
"nested": {
"required": [
"scope",
"filter"
],
"description": "Use `nested` to apply the properties of the direct relation as the filter. `scope` specifies the direct \nrelation property you want use as the filtering property.\n\nExample:\n```\n {\n \"nested\": {\n \"scope\": [\"some\", \"direct_relation\", \"property\"],\n \"filter\": {\n \"equals\": {\n \"property\": [\"node\", \"name\"],\n \"value\": \"ACME\"\n }\n }\n }\n }\n```\n",
"type": "object",
"properties": {
"scope": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"items": {
"type": "string"
}
},
"filter": {
"$ref": "#/components/schemas/FilterDefinition"
}
}
}
}
},
"HasExistingDataFilterV3": {
"type": "object",
"title": "hasData",
"required": [
"hasData"
],
"properties": {
"hasData": {
"type": "array",
"description": "Matches items where data is present in the referenced views, or containers.",
"items": {
"$ref": "#/components/schemas/SourceReference"
}
}
}
},
"OverlapsFilterV3": {
"type": "object",
"title": "overlaps",
"required": [
"overlaps"
],
"properties": {
"overlaps": {
"type": "object",
"description": "Matches items where the range made up of the two properties overlap with the provided range.",
"required": [
"startProperty",
"endProperty"
],
"properties": {
"startProperty": {
"$ref": "#/components/schemas/FilterProperty"
},
"endProperty": {
"$ref": "#/components/schemas/FilterProperty"
},
"gte": {
"$ref": "#/components/schemas/FilterValueRange"
},
"gt": {
"$ref": "#/components/schemas/FilterValueRange"
},
"lte": {
"$ref": "#/components/schemas/FilterValueRange"
},
"lt": {
"$ref": "#/components/schemas/FilterValueRange"
}
}
}
}
},
"TableExpressionOverlapsFilterV3": {
"type": "object",
"title": "overlaps",
"required": [
"overlaps"
],
"properties": {
"overlaps": {
"type": "object",
"description": "Matches items where the range made up of the two properties overlap with the provided range.",
"required": [
"startProperty",
"endProperty"
],
"properties": {
"startProperty": {
"$ref": "#/components/schemas/FilterProperty"
},
"endProperty": {
"$ref": "#/components/schemas/FilterProperty"
},
"gte": {
"$ref": "#/components/schemas/TableExpressionFilterValueRange"
},
"gt": {
"$ref": "#/components/schemas/TableExpressionFilterValueRange"
},
"lte": {
"$ref": "#/components/schemas/TableExpressionFilterValueRange"
},
"lt": {
"$ref": "#/components/schemas/TableExpressionFilterValueRange"
}
}
}
}
},
"EqualsFilterV3": {
"type": "object",
"title": "equals",
"required": [
"equals"
],
"properties": {
"equals": {
"required": [
"property",
"value"
],
"description": "Matches items that contain the exact value in the provided property.",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"value": {
"$ref": "#/components/schemas/FilterValue"
}
}
}
}
},
"TableExpressionEqualsFilterV3": {
"type": "object",
"title": "equals",
"required": [
"equals"
],
"properties": {
"equals": {
"required": [
"property",
"value"
],
"description": "Matches items that contain the exact value in the provided property.",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"value": {
"$ref": "#/components/schemas/TableExpressionFilterValue"
}
}
}
}
},
"InFilterV3": {
"type": "object",
"title": "in",
"required": [
"in"
],
"properties": {
"in": {
"required": [
"property",
"values"
],
"description": "Matches items where the property **exactly** matches one of the given values. You can only apply this filter to properties containing a single value.",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"values": {
"$ref": "#/components/schemas/FilterValueList"
}
}
}
}
},
"TableExpressionInFilterV3": {
"type": "object",
"title": "in",
"required": [
"in"
],
"properties": {
"in": {
"required": [
"property",
"values"
],
"description": "Matches items where the property **exactly** matches one of the given values. You can only apply this filter to properties containing a single value.",
"type": "object",
"properties": {
"property": {
"$ref": "#/components/schemas/FilterProperty"
},
"values": {
"$ref": "#/components/schemas/TableExpressionFilterValueList"
}
}
}
}
},
"RangeFilterV3": {
"type": "object",
"title": "range",
"required": [
"range"
],
"properties": {
"range": {
"required": [
"property"
],
"description": "Matches items that contain terms within the provided range. \n\nThe range must include both an upper and a lower bound. It is not permitted to specify both inclusive \nand exclusive bounds together. E.g. `gte` and `gt`.\n\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/FilterValueRange"
},
"gt": {
"$ref": "#/components/schemas/FilterValueRange"
},
"lte": {
"$ref": "#/components/schemas/FilterValueRange"
},
"lt": {
"$ref": "#/components/schemas/FilterValueRange"
}
}
}
}
},
"TableExpressionRangeFilterV3": {
"type": "object",
"title": "range",
"required": [
"range"
],
"properties": {
"range": {
"required": [
"property"
],
"description": "Matches items that contain terms within the provided range.\n\nThe range must include both an upper and a lower bound. It is not permitted to specify both inclusive\nand exclusive bounds together. E.g. `gte` and `gt`.\n\n `gte`: Greater than or equal to.\n `gt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment