Cognite 3D Model Revisions API
The 3D Model Revisions API from Cognite — 11 operation(s) for 3d model revisions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping 3D Model Revisions API
description: "# Introduction\nThis is the reference documentation for the Cognite API with\nan overview of all the available methods.\n\n# Postman\nSelect the **Download** button to download our OpenAPI specification to get started.\n\nTo import your data into Postman, select **Import**, and the Import modal opens.\nYou can import items by dragging or dropping files or folders. You can choose how to import your API and manage the import settings in **View Import Settings**.\n\nIn the Import Settings, set the **Folder organization** to **Tags**, select\n**Enable optional parameters** to turn off the settings, and select **Always inherit authentication** to turn on the settings. Select **Import**.\n\nSet the Authorization to **Oauth2.0**. By default, the settings are for Open Industrial Data. Navigate to [Cognite Hub](https://hub.cognite.com/open-industrial-data-211) to understand how to get the credentials for use in Postman.\n\nFor more information, see [Getting Started with Postman](https://developer.cognite.com/dev/guides/postman/).\n\n# Pagination\nMost resource types can be paginated, indicated by the field `nextCursor` in the response.\nBy passing the value of `nextCursor` as the cursor you will get the next page of `limit` results.\nNote that all parameters except `cursor` has to stay the same.\n\n# Parallel retrieval\nAs general guidance, Parallel Retrieval is a technique that should be used when due to query complexity, retrieval of data in a single request is significantly slower than it would otherwise be for a simple request. Parallel retrieval does not act as a speed multiplier on optimally running queries. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. \n\nCDF supports parallel retrieval through the `partition` parameter, which has the format `m/n` where `n` is the amount of partitions you would like to split the entire data set into.\nIf you want to download the entire data set by splitting it into 10 partitions, do the following in parallel with `m` running from 1 to 10:\n - Make a request to `/events` with `partition=m/10`.\n - Paginate through the response by following the cursor as explained above. Note that the `partition` parameter needs to be passed to all subqueries.\n\nProcessing of parallel retrieval requests is subject to concurrency quota availability. The request returns the `429` response upon exceeding concurrency limits. See the Request throttling chapter below.\n\nTo prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. \nSome CDF resources will automatically enforce a maximum of 10 partitions.\nFor more specific and detailed information, please read the ```partition``` attribute documentation for the CDF resource you're using. \n\n# Requests throttling\nCognite Data Fusion (CDF) returns the HTTP `429` (too many requests) response status code when project capacity exceeds the limit.\n\nThe throttling can happen:\n - If a user or a project sends too many (more than allocated) concurrent requests.\n - If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.\n\nCognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.\n\nCognite recommends using a reasonable number (up to 10) of `Parallel retrieval` partitions.\n\nFollowing these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.\n\nSee more [here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\n# API versions\n## Version headers\nThis API uses calendar versioning, and version names follow the `YYYYMMDD` format.\nYou can find the versions currently available by using the version selector at the top of this page.\n\nTo use a specific API version, you can pass the `cdf-version: $version` header along with your requests to the API.\n\n## Beta versions\nThe beta versions provide a preview of what the stable version will look like in the future.\nBeta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.\n\nBeta versions are indicated by a `-beta` suffix after the version name. For example, the beta version header for the\n2023-01-01 version is then `cdf-version: 20230101-beta`.\n\n## Alpha versions\nAlpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API.\nThis functionality presents no guarantee of service, so its use is subject to caution.\n\nAlpha versions are indicated by an `-alpha` suffix after the version name. For example, the alpha version header for\nthe 2023-01-01 version is then `cdf-version: 20230101-alpha`."
version: v1
contact:
name: Cognite Support
url: https://support.cognite.com
email: support@cognite.com
servers:
- url: https://{cluster}.cognitedata.com/api/v1/projects/{project}
description: The URL for the CDF cluster to connect to
variables:
cluster:
enum:
- api
- az-tyo-gp-001
- az-eastus-1
- az-power-no-northeurope
- westeurope-1
- asia-northeast1-1
- gc-dsm-gp-001
default: api
description: The CDF cluster to connect to
project:
default: publicdata
description: The CDF project name.
security:
- oidc-token:
- https://{cluster}.cognitedata.com/.default
- oauth2-client-credentials:
- https://{cluster}.cognitedata.com/.default
- oauth2-open-industrial-data:
- https://api.cognitedata.com/.default
- oauth2-auth-code:
- https://{cluster}.cognitedata.com/.default
tags:
- name: 3D Model Revisions
paths:
/3d/models/{modelId}/revisions:
get:
tags:
- 3D Model Revisions
summary: List 3D revisions
description: '
> **Required capabilities:** `threedAcl:READ`
Retrieves a list of all revisions of a model. This operation supports pagination. You can also filter revisions if they are marked as published or not by using the query param published.'
operationId: get3DRevisions
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: published
in: query
description: Filter based on published status.
schema:
type: boolean
responses:
'200':
description: A list of revisions of the model.
content:
application/json:
schema:
$ref: '#/components/schemas/Revision3DWithCursorResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: const revisions3D = await client.revisions3D.list(324566546546346);
- lang: Python
label: Python SDK
source: 'res = client.three_d.revisions.list(model_id=1, published=True, limit=100)
'
- 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
description: '
> **Required capabilities:** `threedAcl:CREATE`
Creates revision(s) and starts processing job(s).
Check beta API documentation for information about additional options.
Hybrid projects: Use the CreateRevision3DClassicAndHybridBody to create revisions.
DataModelOnly: Please use the 3d/jobs endpoint (Beta for now) to create the revision(s) and start jobs. CreateRevision3DDmsOnlyBody will eventually be deprecated.
'
operationId: create3DRevisions
parameters:
- $ref: '#/components/parameters/ModelId'
requestBody:
description: 'The revisions to create.
'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateRevision3DClassicAndHybridBody'
- $ref: '#/components/schemas/CreateRevision3DDmsOnlyBody'
responses:
'201':
description: A list of created revisions.
content:
application/json:
schema:
$ref: '#/components/schemas/Revision3DList'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:CREATE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const revisions = await client.revisions3D.create(4234325345643654, [{ fileId: 8252999965991682 }, { fileId: 6305529564379596 }]);'
- lang: Python
label: Python SDK
source: 'from cognite.client.data_classes import ThreeDModelRevisionWrite
my_revision = ThreeDModelRevisionWrite(file_id=1)
res = client.three_d.revisions.create(model_id=1, revision=my_revision)
'
- lang: Java
label: Java SDK
source: "Path fileAOriginal = Paths.get(\"./src/test/resources/csv-data.txt\"); \nList<FileContainer> fileContainerInput = new ArrayList<>(); \nFileMetadata fileMetadata = FileMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_file_.test\") \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .build(); \n\n FileContainer fileContainer = FileContainer.newBuilder() \n .setFileMetadata(fileMetadata) \n .setFileBinary(FileBinary.newBuilder() \n .setBinaryUri(fileAOriginal.toUri().toString())) \n .build(); \n fileContainerInput.add(fileContainer); \n\n List<FileMetadata> uploadFileResult = \n client.files().upload(fileContainerInput); \n\nThreeDModelRevision.Camera camera = ThreeDModelRevision.Camera.newBuilder() \n .addPosition(2.707411050796509).addPosition(-4.514726638793945).addPosition(1.5695604085922241) \n .addTarget(0.0).addTarget(-0.002374999923631549).addTarget(1.5695604085922241) \n.build(); \nThreeDModelRevision revision = ThreeDModelRevision.newBuilder() \n .setFileId(uploadFileResult.get(0).getId()).setCamera(camera).addRotation(new Random().nextInt(100) / 100.0) \n.build(); \nList<ThreeDModelRevision> listUpsert = \n client.threeD() \n .models() \n .revisions() \n .upsert(10L, List.of(revision)); \n\n"
/3d/models/{modelId}/revisions/update:
post:
tags:
- 3D Model Revisions
summary: Update 3D revisions
operationId: update3DRevisions
parameters:
- $ref: '#/components/parameters/ModelId'
requestBody:
description: List of changes.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UpdateRevision3DClassicBody'
- $ref: '#/components/schemas/UpdateRevision3DDmsOnlyBody'
responses:
'200':
description: Corresponding revisions after applying the updates.
content:
application/json:
schema:
$ref: '#/components/schemas/Revision3DList'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:UPDATE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: "const revisionsToUpdate = [{\n id: 6305529564379596,\n update: {\n rotation: {\n set: [1, 2, 3]\n },\n translation: {\n set: [4, 5, 6]\n },\n scale: {\n set: [0.5, 0.3, 0.2]\n }\n }\n}];\nconst updated = await client.revisions3D.update(8252999965991682, revisionsToUpdate);"
- lang: Python
label: Python SDK
source: 'revision = client.three_d.revisions.retrieve(model_id=1, id=1)
revision.status = "New Status"
res = client.three_d.revisions.update(model_id=1, item=revision)
from cognite.client.data_classes import ThreeDModelRevisionUpdate
my_update = ThreeDModelRevisionUpdate(id=1).published.set(False).metadata.add({"key": "value"})
res = client.three_d.revisions.update(model_id=1, item=my_update)
'
- 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"
description: '
> **Required capabilities:** `threedAcl:UPDATE`
'
/3d/models/{modelId}/revisions/delete:
post:
tags:
- 3D Model Revisions
summary: Delete 3D revisions
operationId: delete3DRevisions
parameters:
- $ref: '#/components/parameters/ModelId'
requestBody:
description: List of revisions ids to delete.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/DataIdentifiers'
- $ref: '#/components/schemas/OneDataDmsIdentifier'
required: true
responses:
'200':
$ref: '#/components/responses/EmptyResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:DELETE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'await client.revisions3D.delete(8252999965991682, [{ id: 4190022127342195 }]);'
- lang: Python
label: Python SDK
source: 'res = client.three_d.revisions.delete(model_id=1, id=1)
'
- 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"
description: '
> **Required capabilities:** `threedAcl:DELETE`
'
/3d/models/{modelId}/revisions/{revisionId}:
get:
tags:
- 3D Model Revisions
summary: Retrieve a 3D revision
operationId: get3DRevision
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
responses:
'200':
description: A revision object
content:
application/json:
schema:
$ref: '#/components/schemas/Revision3D'
x-capability:
- threedAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: const revisions3D = await client.revisions3D.retrieve(8252999965991682, 4190022127342195)
- lang: Python
label: Python SDK
source: 'res = client.three_d.revisions.retrieve(model_id=1, id=1)
'
- 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"
description: '
> **Required capabilities:** `threedAcl:READ`
'
/3d/models/{modelId}/revisions/{revisionId}/logs:
get:
tags:
- 3D Model Revisions
summary: List 3D revision logs
description: '
> **Required capabilities:** `threedAcl:READ`
List log entries for the revision'
operationId: get3DLogs
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
- name: severity
in: query
schema:
type: integer
format: int64
description: Minimum severity to retrieve (3 = INFO, 5 = WARN, 7 = ERROR).
default: 5
responses:
'200':
description: A list of log entries
content:
application/json:
schema:
$ref: '#/components/schemas/RevisionLog3DResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:READ
/3d/models/{modelId}/revisions/{revisionId}/thumbnail:
post:
tags:
- 3D Model Revisions
summary: Update 3D revision thumbnail
operationId: updateThumbnail
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
requestBody:
description: The request body containing the file ID of the thumbnail image (from Files API).
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRevision3DThumbnail'
responses:
'200':
$ref: '#/components/responses/EmptyResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:UPDATE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: await client.revisions3D.updateThumbnail(8252999965991682, 4190022127342195, 3243334242324);
- lang: Python
label: Python SDK
source: 'res = client.three_d.revisions.update_thumbnail(model_id=1, revision_id=1, file_id=1)
'
- 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"
description: '
> **Required capabilities:** `threedAcl:UPDATE`
'
/3d/models/{modelId}/revisions/{revisionId}/outputs:
get:
tags:
- 3D Model Revisions
summary: List available outputs
description: '
> **Required capabilities:** `threedAcl:READ`
Retrieve a list of available outputs for a processed 3D model. An output can be a format that can be consumed by a viewer (e.g. Reveal) or import in external tools. Each of the outputs will have an associated version which is used to identify the version of output format (not the revision of the processed output). Note that the structure of the outputs will vary and is not covered here.'
operationId: list3dModelOutputs
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
- name: format
in: query
description: 'Format identifier, e.g. ''ept-pointcloud'' (point cloud). Well known formats are:
''ept-pointcloud'' (point cloud data) or ''reveal-directory'' (output supported by Reveal).
''all-outputs'' can be used to retrieve all outputs for a 3D revision. Note that some of
the outputs are internal, where the format and availability might change without warning.
'
schema:
type: string
responses:
'200':
description: Returns a list of outputs and available versions per output for the given revision.
content:
application/json:
schema:
$ref: '#/components/schemas/Model3DOutputResponseList'
x-capability:
- threedAcl:READ
/3d/models/{modelId}/revisions/{revisionId}/nodes:
get:
tags:
- 3D Model Revisions
summary: List 3D nodes
description: '
> **Required capabilities:** `threedAcl:READ`
Retrieves a list of nodes from the hierarchy in the 3D model. You can also request a specific subtree with the ''nodeId'' query parameter and limit the depth of the resulting subtree with the ''depth'' query parameter. By default, nodes are returned in order of ascending treeIndex. We suggest trying to set the query parameter `sortByNodeId` to `true` to check whether it makes your use case faster. The `partition` parameter can only be used if `sortByNodeId` is set to `true`. This operation supports pagination. If the model revision is still being processed, you will get a HTTP status 400 when accessing nodes too early. Wait until the retrieve revision response returns "status":"Done" before calling nodes endpoints.'
operationId: get3DNodes
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
- $ref: '#/components/parameters/partition'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: depth
in: query
description: Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.
schema:
type: integer
format: int32
- name: nodeId
in: query
description: ID of a node that are the root of the subtree you request (default is the root node).
schema:
type: integer
format: int64
- name: sortByNodeId
in: query
description: Enable sorting by nodeId. When this parameter is `true`, nodes will be listed in order of ascending nodeId. Enabling this option will likely result in faster response for many requests.
schema:
type: boolean
default: false
- name: properties
in: query
description: 'Example: `{"category1":{"property1":"value1"}}`
Filter for node properties. Only nodes that match all the given properties exactly will be listed.
The filter must be a JSON object with the same format as the `properties` field.
'
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)
'
- lang: Java
label: Java SDK
source: "List<ThreeDModelRevision> listResults = new ArrayList<>(); \nclient.threeD() \n .models() \n .revisions() \n .nodes() \n .list(model.getId(), revision.getId()) \n .forEachRemaining(val -> listResults.addAll(val)); \n\n"
/3d/models/{modelId}/revisions/{revisionId}/nodes/list:
post:
tags:
- 3D Model Revisions
summary: Filter 3D nodes
description: '
> **Required capabilities:** `threedAcl:READ`
List nodes in a project, filtered by node names or node property values specified by supplied filters. This operation supports pagination and partitions. If the model revision is still being processed, you will get a HTTP status 400 when accessing nodes too early. Wait until the retrieve revision response returns "status":"Done" before calling nodes endpoints.'
operationId: filter3DNodes
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Node3DPropertyFilterBody'
- $ref: '#/components/schemas/Node3DNameFilterBody'
required: true
responses:
'200':
description: A list of nodes satisfying the supplied node property filters.
content:
application/json:
schema:
$ref: '#/components/schemas/Node3DWithCursorResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: "const query = {\n filter: {\n properties: {\n Items: {\n Type: [\"Cylinder\"]\n }\n }\n },\n partition: \"1/10\"\n};\nconst nodes3d = await client.revisions3D.filter3DNodes(8252999965991682, 4190022127342195, query);"
- lang: Python
label: Python SDK
source: 'res = client.three_d.revisions.filter_nodes(model_id=1, revision_id=1, properties={ "PDMS": { "Area": ["AB76", "AB77", "AB78"], "Type": ["PIPE", "BEND", "PIPESUP"] } }, limit=10)
'
- lang: Java
label: Java SDK
source: "//without parameters \nIterator<List<ThreeDNode>> itFilter = client.threeD() \n .models() \n .revisions() \n .nodes() \n .filter(model.getId(), revision.getId()); \n List<ThreeDNode> listResults = itFilter.next(); \n\n//with parameters \nRequest request = Request.create() \n .withFilterParameter(\"properties\", createFilterPropertiesWithCategories()); \n\nList<ThreeDNode> listResults = new ArrayList<>(); \nclient.threeD() \n .models() \n .revisions() \n .nodes() \n .filter(model.getId(), revision.getId(), request) \n .forEachRemaining(val -> listResults.addAll(val)); \n\nprivate ThreeDNode.PropertiesFilter createFilterPropertiesWithCategories() { \n ThreeDNode.PropertiesFilter.Categories.CategoriesValues.Builder catValBuilder = \n ThreeDNode.PropertiesFilter.Categories.CategoriesValues.newBuilder(); \n catValBuilder.addValuesString(\"Box\"); \n ThreeDNode.PropertiesFilter.Categories.Builder catBuilder = \n ThreeDNode.PropertiesFilter.Categories.newBuilder(); \n catBuilder.setName(\"Item\"); \n catBuilder.putValues(\"Type\", catValBuilder.build()); \n ThreeDNode.PropertiesFilter.Builder propsBuilder = \n ThreeDNode.PropertiesFilter.newBuilder(); \n propsBuilder.addCategories(catBuilder.build()); \n return propsBuilder.build(); \n } \n\n"
/3d/models/{modelId}/revisions/{revisionId}/nodes/byids:
post:
tags:
- 3D Model Revisions
summary: Get 3D nodes by ID
description: '
> **Required capabilities:** `threedAcl:READ`
Retrieves specific nodes given by a list of IDs.'
operationId: get3DNodesById
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
requestBody:
description: The request body containing the IDs of the nodes to retrieve. Will return error 400 if the revision is still being processed.
content:
application/json:
schema:
$ref: '#/components/schemas/Node3DIds'
required: true
responses:
'200':
description: A list of nodes.
content:
application/json:
schema:
$ref: '#/components/schemas/Node3DList'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const nodes3d = await client.revisions3D.retrieve3DNodes(8252999965991682, 4190022127342195, [{id: 123}, {id: 456}]);'
- lang: Java
label: Java SDK
source: "List<Item> byInternalIds = List.of(Item.newBuilder().setId(10).build()); \nList<ThreeDNode> nodesByIds = client.threeD() \n .models() \n .revisions() \n .nodes() \n .retrieve(model.getId(), revision.getId(), byInternalIds); \n\nList<Item> byExternalIds = List.of(Item.newBuilder().setExternalId(\"10\").build()); \n List<ThreeDNode> nodesByIds = client.threeD() \n .models() \n .revisions() \n .nodes() \n .retrieve(model.getId(), revision.getId(), byExternalIds); \n\n"
/3d/models/{modelId}/revisions/{revisionId}/nodes/{nodeId}/ancestors:
get:
tags:
- 3D Model Revisions
summary: List 3D ancestor nodes
description: '
> **Required capabilities:** `threedAcl:READ`
Retrieves a list of ancestor nodes of a given node, including itself, in the hierarchy of the 3D model. This operation supports pagination. Will return error 400 if the revision is still being processed.'
operationId: get3DNodeAncestors
parameters:
- $ref: '#/components/parameters/ModelId'
- $ref: '#/components/parameters/RevisionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: nodeId
in: path
description: ID of the node to get the ancestors of.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: A list of ancestor nodes.
content:
application/json:
schema:
$ref: '#/components/schemas/Node3DWithCursorResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- threedAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: const nodes3d = await client.revisions3D.list3DNodeAncestors(8252999965991682, 4190022127342195, 572413075141081);
- lang: Python
label: Python SDK
source: 'res = client.three_d.revisions.list_ancestor_nodes(model_id=1, revision_id=1, node_id=5, limit=10)
'
- 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"
components:
schemas:
NextCursor:
type: string
description: Cursor to get the next page of results (if available).
Revision3DList:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Revision3D'
Revision3DWithCursorResponse:
allOf:
- $ref: '#/components/schemas/Revision3DList'
- $ref: '#/components/schemas/NextCursorData'
Node3DNameFilterBody:
description: Filter request for nodes. Filters nodes with properties matching ones in a list of alternatives.
allOf:
- type: object
properties:
filter:
$ref: '#/components/schemas/Node3DNameFilter'
- $ref: '#/components/schemas/Limit'
- $ref: '#/components/schemas/Cursor'
- $ref: '#/components/schemas/PartitionObject'
TreeIndex:
type: integer
minimum: 0
description: The index of the node in the 3D model hierarchy, starting from 0. The tree is traversed in a depth-first order.
format: int64
example: 3
CogniteInstanceId:
description: The ID of an [instance in Cognite Data Models](https://docs.cognite.com/cdf/dm/dm_concepts/dm_spaces_instances#instance).
type: object
required:
- space
- externalId
properties:
space:
type: string
minLength: 1
maxLength: 43
externalId:
type: string
minLength: 1
max
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-3d-model-revisions-api-openapi.yml