Skip to content

Instantly share code, notes, and snippets.

@ks93

ks93/greenfield.json

Last active January 9, 2023 18:49
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/176eeeb4cbb60cf99ac584bf48cf8deb to your computer and use it in GitHub Desktop.
Save ks93/176eeeb4cbb60cf99ac584bf48cf8deb to your computer and use it in GitHub Desktop.
Download ZIP
Cognite OpenAPI spec, greenfield
Raw
greenfield.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, you would do the following in parallel with `m` running from 1 to 10:\n - Make a request to `/events` with `partition=m/10`.\n - Paginate through the response by following the cursor as explained above. Note that the `partition` parameter needs to be passed to all subqueries.\n",
"version": "v1",
"contact": {
"name": "Cognite Support",
"url": "https://support.cognite.com",
"email": "support@cognite.com"
}
},
"servers": [
{
"url": "https://greenfield.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/ErrorResponse"
}
},
"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/ErrorResponse"
}
},
"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/ErrorResponse"
}
},
"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/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ"
],
"description": "Use advanced 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",
"description": "Use advanced filtering options to agggregate assets.",
"operationId": "aggregateAssets",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssetAggregateRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/AssetAggregateResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"assetsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const aggregates = await client.assets.aggregate({ filter: { root: true } });\nconsole.log('Number of root assets: ', aggregates[0].count)"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "aggregate_by_prefix = client.assets.aggregate(filter={\"external_id_prefix\": \"prefix\"})\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/ErrorResponse"
}
},
"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 are not included in the request, are not changed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataAssetChange"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/AssetDataResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"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 does not 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/ErrorResponse"
}
},
"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/ErrorResponse"
}
},
"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}/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/ErrorResponse"
}
},
"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": "Filter 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 array of selected fields. Syntax: `[\"<fieldname>:asc|desc\"]`. Default sort order is `asc` with short syntax: `[\"<fieldname>\"]`.\nFilter accepts the following field names:\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 is 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/ErrorResponse"
}
},
"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 event by 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/ErrorResponse"
}
},
"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 all 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/ErrorResponse"
}
},
"x-capability": [
"eventsAcl:READ"
],
"description": "Retrieve a list of all events in the same project. This operation supports pagination by cursor. Criteria can be applied to select a subset of events.",
"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/ErrorResponse"
}
},
"x-capability": [
"eventsAcl:READ"
],
"description": "The aggregation API allows you to compute aggregated results on events \nlike getting the count of all events in a project or checking what are all the \ndifferent types and subtypes of events in your project, along with \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\nThe default behavior, when you do not specify \nthe `aggregate` field in the request body, 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 in the field specified in \n`fields: []`. Note that, currently, you can only request for unique \nvalues on a single field. Also, in the case of 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'\n",
"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/ErrorResponse"
}
},
"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/ErrorResponse"
}
},
"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 within 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/ErrorResponse"
}
},
"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 multiple 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/ErrorResponse"
}
},
"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/jpg'}, fileContent);\n\n// manual with uploadUrl:\nconst file2 = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpg'});\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 file by 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/jpg',\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 API key": {
"value": {
"items": [
{
"name": "My awesome function",
"fileId": 5467347282343,
"apiKey": "ABCMYKEY"
}
]
}
},
"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 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": {
"$ref": "#/components/schemas/Node3DFilterBody"
}
}
},
"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}/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",
"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.",
"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"
],
"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",
"description": "Count the number of time series that match the given filter",
"operationId": "aggregateTimeSeries",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "Retrieves the count of time series matching the given criteria",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesAggregateDTO"
}
}
}
},
"responses": {
"200": {
"description": "Count of time series",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimeSeriesAggregateResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"timeSeriesAcl:READ"
],
"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.",
"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"
}
]
}
},
"/login/status": {
"get": {
"tags": [
"Login"
],
"summary": "Verify login status",
"description": "Returns the authentication information about the asking entity.",
"operationId": "status",
"responses": {
"200": {
"$ref": "#/components/responses/LoginStatusResponse"
}
},
"security": [
{
"api-key": []
}
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const status = await client.login.status();\n// if status === null means you are not logged in"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "login_status = client.login.status()\nproject = login_status.project\n"
},
{
"lang": "Java",
"label": "Java SDK",
"source": "LoginStatus loginStatus = client.login().loginStatusByApiKey(); \n\n"
}
]
}
},
"/login/redirect": {
"get": {
"tags": [
"Login"
],
"summary": "Login with redirect",
"description": "Redirects to a login URL. This endpoint is typically used by front-end services acting on behalf of users to log them in.",
"operationId": "redirectUrl",
"parameters": [
{
"name": "project",
"in": "query",
"description": "The project to login to.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "redirectUrl",
"in": "query",
"description": "The url to send the user to after the login is successful.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "errorRedirectUrl",
"in": "query",
"description": "The url to send the user to if the login fails or is aborted. If this is not passed in, the value of the redirectUrl will be used.",
"schema": {
"type": "string"
}
}
],
"security": [],
"responses": {
"303": {
"description": "Redirection to the login url"
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "import { CogniteClient, REDIRECT } from '@cognite/sdk';\n\nconst client = new CogniteClient({ appId: '[YOUR APP NAME]' });\n\n// using Cognite authentication flow\nclient.loginWithOAuth({\n project: '[PROJECT]',\n onAuthenticate: REDIRECT // optional, REDIRECT is by default\n});\n\n// or you can sign in using AzureAD authentication flow (in case your projects supports it)\nclient.loginWithOAuth({\n cluster: '[CLUSTER]',\n clientId: '[CLIENT_ID]', // client id of your AzureAD application\n tenantId: '[TENANT_ID]', // tenant id of your AzureAD tenant. Will be set to 'common' if not provided\n});\n\n// you also have ability to sign in using ADFS\nclient.loginWithOAuth({\n authority: https://example.com/adfs/oauth2/authorize,\n requestParams: {\n cluster: 'cluster-name',\n clientId: 'adfs-client-id',\n },\n});\n\n// after sign in you can do calls with the client\n(async () => {\n await client.authenticate();\n client.setProject('project-name');\n const createdAsset = await client.assets.create([{ name: 'My first asset' }]);\n})();"
}
]
}
},
"/login/userinfo": {
"get": {
"tags": [
"Login"
],
"summary": "Obtain user information",
"operationId": "userinfo",
"description": "Ask this with any valid credentials to obtain information about the current authenticated entity. The response is a decoded ID token.",
"responses": {
"200": {
"description": "User information.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdToken"
}
}
}
}
},
"security": []
}
},
"/logout": {
"get": {
"tags": [
"Logout"
],
"summary": "Logout",
"description": "Invalidates a session and returns the authentication status of the asking entity.",
"operationId": "logout",
"responses": {
"200": {
"$ref": "#/components/responses/LoginStatusResponse"
}
},
"security": []
}
},
"/logout/url": {
"get": {
"tags": [
"Logout"
],
"summary": "Retrieve a logout url",
"description": "Get logout url of the given project.",
"operationId": "logoutUrl",
"parameters": [
{
"name": "redirectUrl",
"in": "query",
"description": "The url to send the user to after the logout is successful. If no url is passed, you will end up at the IdP's log out page.",
"schema": {
"type": "string"
},
"example": "https://mysite.com/loggedout"
}
],
"responses": {
"200": {
"description": "Logout URL.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"title": "URL Response",
"description": "Object containing the log out URL",
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"example": "https://accounts.google.com/logout",
"description": "The url to send the user to in order to log out"
}
}
}
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "// You can specify the url to send the user to after the logout is successful.\n// If no url is passed, you will end up at the IDPs log out page.\nconst logoutUrl = await client.logout.getUrl({ redirectUrl: '[url to redirect]' });"
}
]
}
},
"/api/v1/projects/{project}/groups": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"get": {
"tags": [
"Groups"
],
"summary": "List groups",
"description": "Retrieves a list of groups the asking service account is a member of. Service accounts 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/{project}/groups/{groupId}/serviceaccounts": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"get": {
"tags": [
"Groups"
],
"summary": "List service accounts in a group",
"description": "Retrieve a list of service accounts that are members of the group with the given ID.",
"operationId": "getMembersOfGroups",
"parameters": [
{
"name": "groupId",
"in": "path",
"description": "ID of the group",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/ServiceAccountResponse"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"groupsAcl:READ"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const serviceAccounts = await client.groups.listServiceAccounts(921923342342323);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.groups.list_service_accounts(1)\n"
}
]
},
"post": {
"tags": [
"Groups"
],
"summary": "Add service accounts to a group",
"description": "Grant the service accounts with the given IDs membership in a group.\nThis operation is not idempotent: if any of the given service accounts is already a member of the group, the operation will fail.\nNote that linking a service account to more than 20 groups is not supported and may result in login issues.\n",
"operationId": "addServiceAccountsToGroup",
"parameters": [
{
"name": "groupId",
"in": "path",
"description": "ID of the group",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"description": "IDs of service accounts to add",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataLong"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Empty response."
},
"400": {
"$ref": "#/components/responses/MissingField"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"groupsAcl:UPDATE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.groups.addServiceAccounts(921923342342323, [123312763989213, 23232789217132]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.groups.add_service_account(id=1, service_account_id=1)\n"
}
]
}
},
"/api/v1/projects/{project}/groups/{groupId}/serviceaccounts/remove": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"post": {
"tags": [
"Groups"
],
"summary": "Remove service accounts from a group",
"description": "Revoke membership in a group from the given service accounts.",
"operationId": "removeServiceAccountsFromGroup",
"parameters": [
{
"name": "groupId",
"in": "path",
"required": true,
"description": "ID of the group",
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"description": "List of service account IDs to remove",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataLong"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Empty response."
}
},
"x-capability": [
"groupsAcl:UPDATE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.groups.removeServiceAccounts(921923342342323, [123312763989213, 23232789217132]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.groups.remove_service_account(id=1, service_account_id=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}/serviceaccounts": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"get": {
"tags": [
"Service accounts"
],
"summary": "List service accounts",
"description": "Lists all the service accounts of the project.",
"operationId": "getServiceAccounts",
"responses": {
"200": {
"$ref": "#/components/responses/ServiceAccountResponse"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"usersAcl:LIST"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const serviceaccounts = await client.serviceAccounts.list();"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.service_accounts.list()\n"
}
]
},
"post": {
"tags": [
"Service accounts"
],
"summary": "Create service accounts",
"description": "Creates new service accounts with the given names and group memberships.\nThe names of the service accounts have to be unique.\nIf any of the provided group IDs are not valid group IDs, the request will fail and no service accounts will be created.\n",
"operationId": "createServiceAccounts",
"requestBody": {
"description": "List of service accounts to create.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceAccountInput"
}
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"$ref": "#/components/responses/ServiceAccountResponse"
},
"400": {
"$ref": "#/components/responses/MissingField"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"usersAcl:CREATE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const serviceAccounts = [\n { name: 'Data extractor' },\n { name: 'Monitor', groups: [123, 456] },\n];\nconst createdServiceAccounts = await client.serviceAccounts.create(serviceAccounts);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "from cognite.client.data_classes import ServiceAccount\nmy_account = ServiceAccount(name=\"my@service.com\", groups=[1, 2, 3])\nres = client.iam.service_accounts.create(my_account)\n"
}
]
}
},
"/api/v1/projects/{project}/serviceaccounts/delete": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"post": {
"tags": [
"Service accounts"
],
"summary": "Delete service accounts",
"description": "Deletes the service accounts identified by the given IDs.\nAPI keys associated with those service accounts will also be deleted.\nIf any of the provided IDs are not valid service account IDs, the request will fail and no resources will be deleted.\n",
"operationId": "deleteServiceAccounts",
"requestBody": {
"description": "List of service account IDs to delete",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataLong"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"usersAcl:DELETE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.serviceAccounts.delete([123, 456]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "client.iam.service_accounts.delete(1)\n"
}
]
}
},
"/api/v1/projects/{project}/apikeys": {
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"get": {
"tags": [
"API keys"
],
"summary": "List API keys",
"description": "Retrieves a list of all API keys connected to the current service account. Administrators can optionally list keys for all or individual service accounts that are not their own.",
"operationId": "getApiKeys",
"parameters": [
{
"name": "all",
"in": "query",
"description": "Only available with users:list ACL, returns all API keys for the project.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "serviceAccountId",
"in": "query",
"description": "Get API keys for a specific service account, only available to admin users.",
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "includeDeleted",
"in": "query",
"description": "Whether to include deleted API keys, or not.\nDeleted API keys can be listed for up to 90 days after deletion.\n",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "A list of API keys.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKeyResponse"
}
}
}
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"apikeysAcl:LIST"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const apiKeys = await client.apiKeys.list({ all: true });"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.api_keys.list()\n"
}
]
},
"post": {
"tags": [
"API keys"
],
"summary": "Create API keys",
"description": "Creates one API key for each service account.\nIf the ID of one service account appears multiple times in the request, then multiple API keys will be created for that service account.\n",
"operationId": "createApiKeys",
"requestBody": {
"description": "List of the service accounts to create API keys for.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataApiKeyRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "A list of the created API keys.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewApiKeyResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/MissingField"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"apikeysAcl:CREATE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "const createdApiKeys = await client.apiKeys.create([{ serviceAccountId: 123 }]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "res = client.iam.api_keys.create(1)\n"
}
]
}
},
"/api/v1/projects/{project}/apikeys/delete": {
"post": {
"tags": [
"API keys"
],
"summary": "Delete API keys",
"description": "Deletes one or more API keys with the specified API key IDs. The API key IDs were returned when the keys were\ncreated, or can be obtained by listing all API keys. Deleted API keys can be listed for up to 90 days after\ndeletion.\n",
"operationId": "deleteApiKeys",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "List of the IDs of the API keys to delete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataLong"
}
}
},
"required": true
},
"responses": {
"200": {
"$ref": "#/components/responses/EmptyResponse"
}
},
"security": [
{
"api-key": []
}
],
"x-capability": [
"apikeysAcl:DELETE"
],
"x-code-samples": [
{
"lang": "JavaScript",
"label": "JavaScript SDK",
"source": "await client.apiKeys.delete([123, 456]);"
},
{
"lang": "Python",
"label": "Python SDK",
"source": "client.iam.api_keys.delete(1)\n"
}
]
}
},
"/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 the attributes of 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",
"description": "Retrieves a list of sequences matching the given criteria.",
"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"
],
"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",
"description": "Count the number of sequences that match the given filter",
"operationId": "aggregateSequences",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"description": "Retrieves the count of sequences matching the given criteria.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequencesAggregateDTO"
}
}
}
},
"responses": {
"200": {
"description": "Count of sequences",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SequenceAggregateResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"sequencesAcl:READ"
],
"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/OneOfFileId"
}
},
"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/OneOfFileId"
}
},
"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": [
"assetsAcl:READ",
"entitymatchingAcl:READ"
]
},
"post": {
"tags": [
"Entity matching"
],
"summary": "Create entity matcher model",
"description": "Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint. 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": [
"assetsAcl:READ",
"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": [
"assetsAcl:READ",
"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": [
"assetsAcl:READ",
"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": [
"assetsAcl:READ",
"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": [
"assetsAcl:READ",
"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": [
"assetsAcl:READ",
"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": "Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint. Predicts entity matches using a trained model.",
"operationId": "entityMatchingPredict",
"parameters": [
{
"$ref": "#/components/parameters/project"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityMatchingPredictSchema"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"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": [
"assetsAcl:READ",
"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.",
"operationId": "entityMatchingPredictResults",
"parameters": [
{
"$ref": "#/components/parameters/project"
},
{
"$ref": "#/components/parameters/jobId"
}
],
"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": "Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint. 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": [
"assetsAcl:READ",
"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\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 content.\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 word \"ipsum\".\n\n#### Phrases\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\nTo search for the special characters (`+`, `|`, `-`, `\"`. `\\`), escape with a preceding backslash (\\).\n\n#### Ordering\nWhen you search for a term, we try to return the most relevant documents first, and less relevant documents further down the list.\nThere are a few factors that determine the relevance of a document:\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 of the terms are considered more relevant than documents 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 document.\n\n#### Examples\n```\n{\n \"search\": {\n \"query\": \"cognite \\\"lorem ipsum\\\"\"\n }\n}\n```\nThis request will return documents matching the search query, where the query behaves as described above.\n\n\n```\n{\n \"search\": {\n \"query\": \"cognite \\\"lorem ipsum\\\"\"\n },\n \"filter\": {\n \"prefix\": {\n \"property\": [\"externalId\"],\n \"value\": \"1\"\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### Filtering\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\ntogether arbitrarily using the boolean clauses `and`, `or` and `not`.\n\nThe available leaf filters are: `equals`, `in`, `containsAny`, `containsAll`, `range`, `prefix`, `exists`, `geojsonIntersects`, `geojsonDisjoint` and `geojsonWithin`.\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 |\n| `[\"assetExternalIds\"]` | array of strings | containsAny, containsAll, exists |\n| `[\"labels\"]` | array of Labels | containsAny, containsAll, exists |\n| `[\"sourceFile\", \"name\"]` | string | equals, in, prefix, exists |\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 |\n| `[\"sourceFile\", \"assetExternalIds\"]` | array of strings | containsAny, containsAll, exists |\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\", *]` | string | equals, in, prefix, exists |\n\nAll filtering is done in a case-sensitive manner against the resource data.\nNote that some properties holds normalized data. E.g. a document with source file name\n`FILE.PDF` will have the `extension` property be `pdf`. A filter for extension equals\nto `PDF` will not match this document, as it must be specified as `pdf`.\n\n#### Example\n```\n{\n \"filter\": {\n \"and\": [\n {\n \"or\": [\n {\n \"equals\": {\n \"property\": [\"type\"],\n \"value\": \"PDF\"\n }\n },\n {\n \"prefix\": {\n \"property\": [\"externalId\"],\n \"value\": \"hello\"\n }\n }\n ]\n },\n {\n \"range\": {\n \"property\": [\"createdTime\"],\n \"lte\": 1519862400000\n }\n },\n {\n \"not\": {\n \"in\": {\n \"property\": [\"sourceFile\", \"name\"],\n \"values\": [\"My Document.doc\", \"My Other Document.docx\"]\n }\n }\n }\n ]\n }\n}\n```\n\n### Aggregations\n> Deprecated: use the aggregates endpoint for aggregations instead.\n\nAggregations can help provide useful information about your search results and about your whole data set.\nThey can help answer questions such as *\"How many documents are there in total?\"* or *\"How many PDF documents matches my current query?\"*\n\nThe Documents API only supports one type of aggregation at the moment; the `count` aggregation.\nThe `count` aggregation can give you a count of how many documents exist for the different values of a given property.\nIf no property is given, the `count` aggregation gives you the total count of documents.\nMore aggregation types may be added in the future.\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#### Properties\nBelow is an overview of all the properties that can be aggregated on, and which aggregate is applicable to each property.\n\n| Property | Applicable aggregation |\n|------------------------------|------------------------|\n| `[\"mimeType\"]` | count |\n| `[\"pageCount\"]` | count |\n| `[\"type\"]` | count |\n| `[\"extension\"]` | count |\n| `[\"author\"]` | count |\n| `[\"language\"]` | count |\n| `[\"sourceFile\", \"source\"]` | count |\n| `[\"sourceFile\", \"mimeType\"]` | count |\n| `[\"sourceFile\", \"labels\"]` | count |\n\n#### Example\n```\n{\n \"aggregates\": [\n {\n \"name\": \"countPerType\",\n \"aggregate\": \"count\",\n \"groupBy\": [\n {\n \"property\": [\"type\"]\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```\n{\n \"sort\": [\n {\n \"property\": [\"createdTime\"],\n \"order\": \"asc\",\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\nSetting `aggregate` to `uniqueValues` will return top unique values (up to the\nrequested limit) and the count of each in the property specified in\n`properties`. The list will have the highest count first. For example:\n\n```\n{\n \"aggregate\": \"uniqueValues\",\n \"properties\": [\n {\n \"property\": [\"author\"]\n }\n ]\n}\n```\n\nwill return the top unique authors in the documents in your project.\nIf the number of unique authors is less than the requested limit you will\nbe receiving all unique authors ordered by the most frequent first.\n\nSimilarly,\n\n```\n{\n \"aggregate\": \"uniqueValues\",\n \"properties\": [\n {\n \"property\": [\"author\"]\n }\n ],\n \"filter\": {\n \"equals\": {\n \"property\": [\"type\"],\n \"value\": \"PDF\"\n }\n }\n}\n```\n\nwill return top unique authors in PDF documents.\n\nSetting `aggregate` to `allUniqueValues` will return 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.\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/DocumentsAggregateAllUniqueValuesRequest"
}
]
},
"examples": {
"unique-values": {
"value": {
"filter": {
"equals": {
"property": [
"type"
],
"value": "PDF"
}
},
"aggregate": "uniqueValues",
"properties": [
{
"property": [
"author"
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/DocumentsAggregateResponse"
},
"400": {
"$ref": "#/components/responses/ErrorResponse"
}
},
"x-capability": [
"filesAcl:READ"
]
}
},
"/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/DataLong"
}
}
}
},
"responses": {
"200": {
"description": "A list of sessions with the given ids",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionList"
},
"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/{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"
]
}
}
},
"components": {
"securitySchemes": {
"api-key": {
"type": "apiKey",
"description": "An admin can create API keys in the Cognite console.",
"name": "api-key",
"in": "header"
},
"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"
}
},
"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": "Users Capability",
"properties": {
"usersAcl": {
"$ref": "#/components/schemas/cogniteusers_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": "Api Keys Capability",
"properties": {
"apikeysAcl": {
"$ref": "#/components/schemas/cogniteapikeys_aclAcl"
}
}
},
{
"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
}
}
}
},
"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.\nYou need to follow the cursors within each partition in order to receive all the data.\nExample: 1/10\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",
"oneO
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment