3D Model Revisions

List 3D revisions

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.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

query Parameters
cursor
string

Cursor for paging through results. In general, if a response contains a nextCursor property, it means that there may be more results, and you should pass that value as the cursor parameter in the next request.

Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.

Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

published
boolean

Filter based on published status.

Responses
200

A list of revisions of the model.

400

The response for a failed request.

get/3d/models/{modelId}/revisions
Request samples 
const revisions3D = await client.revisions3D.list(324566546546346);
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create 3D revisions

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.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

The revisions to create.

One of:
required
Array of objects (CreateRevision3D) [ 1 .. 1000 ] items
Responses
201

A list of created revisions.

400

The response for a failed request.

post/3d/models/{modelId}/revisions
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

Update 3D revisions

Required capabilities: threedAcl:UPDATE

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

List of changes.

One of:
required
Array of objects (UpdateRevision3D) [ 1 .. 1000 ] items
Responses
200

Corresponding revisions after applying the updates.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/update
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

Delete 3D revisions

Required capabilities: threedAcl:DELETE

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

Request Body schema: application/json
required

List of revisions ids to delete.

One of:
required
Array of objects (DataIdentifier) [ 1 .. 1000 ] items unique

List of ID objects

Responses
200

Empty response.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/delete
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{ }

Retrieve a 3D revision

Required capabilities: threedAcl:READ

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Responses
200

A revision object

get/3d/models/{modelId}/revisions/{revisionId}
Request samples 
const revisions3D = await client.revisions3D.retrieve(8252999965991682, 4190022127342195)
Response samples
application/json
{
  • "id": 1000,
  • "fileId": 1000,
  • "published": false,
  • "rotation": [
    ],
  • "scale": [
    ],
  • "translation": [
    ],
  • "camera": {
    },
  • "status": "Done",
  • "metadata": {
    },
  • "thumbnailThreedFileId": 1000,
  • "thumbnailURL": "https://api.cognitedata.com/api/v1/project/myproject/3d/files/1000",
  • "assetMappingCount": 0,
  • "createdTime": 0
}

List 3D revision logs

Required capabilities: threedAcl:READ

List log entries for the revision

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
severity
integer <int64>
Default: 5

Minimum severity to retrieve (3 = INFO, 5 = WARN, 7 = ERROR).

Responses
200

A list of log entries

400

The response for a failed request.

get/3d/models/{modelId}/revisions/{revisionId}/logs
Response samples
application/json
{
  • "items": [
    ]
}

Update 3D revision thumbnail

Required capabilities: threedAcl:UPDATE

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The request body containing the file ID of the thumbnail image (from Files API).

fileId
required
integer <int64>

File ID of thumbnail file in Files API. Only JPEG and PNG files are supported.

Responses
200

Empty response.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/{revisionId}/thumbnail
Request samples
application/json
{
  • "fileId": 0
}
Response samples
application/json
{ }

List available outputs

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.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
format
string

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.

Responses
200

Returns a list of outputs and available versions per output for the given revision.

get/3d/models/{modelId}/revisions/{revisionId}/outputs
Response samples
application/json
{
  • "items": [
    ]
}

List 3D nodes

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.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
partition
string

Splits the data set into N partitions. The attribute is specified as a "M/N" string, where M is a natural number in the interval of [1, N]. You need to follow the cursors within each partition in order to receive all the data.

To prevent unexpected problems and maximize read throughput, you should at most use 10 (N <= 10) partitions.

When using more than 10 partitions, CDF may reduce the number of partitions silently. For example, CDF may reduce the number of partitions to K = 10 so if you specify an X/N partition value where X = 8 and N = 20 - i.e. "partition": "8/20"- then CDF will change N to N = K = 10 and process the request. But if you specify the X/N partition value where X = 11 (X > K) and N = 20 - i.e. "partition": "11/20"- then CDF will reply with an empty result list and no cursor in the response.

In future releases of the resource APIs, Cognite may reject requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests will result in a 400 Bad Request status.

Example: partition=1/10
cursor
string

Cursor for paging through results. In general, if a response contains a nextCursor property, it means that there may be more results, and you should pass that value as the cursor parameter in the next request.

Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.

Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

depth
integer <int32>

Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.

nodeId
integer <int64>

ID of a node that are the root of the subtree you request (default is the root node).

sortByNodeId
boolean
Default: false

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.

properties
string <jsonObject(jsonObject(string))>

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.

Responses
200

A list of nodes of a revision.

400

The response for a failed request.

get/3d/models/{modelId}/revisions/{revisionId}/nodes
Request samples 
const nodes3d = await client.revisions3D.list3DNodes(8252999965991682, 4190022127342195);
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Filter 3D nodes

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.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json
required
One of:

Filter request for nodes. Filters nodes with properties matching ones in a list of alternatives.

object (Node3DPropertyFilter)

Filters used in the search.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
partition
string (Partition)

Splits the data set into N partitions. The attribute is specified as a "M/N" string, where M is a natural number in the interval of [1, N]. You need to follow the cursors within each partition in order to receive all the data.

To prevent unexpected problems and maximize read throughput, you should at most use 10 (N <= 10) partitions.

When using more than 10 partitions, CDF may reduce the number of partitions silently. For example, CDF may reduce the number of partitions to K = 10 so if you specify an X/N partition value where X = 8 and N = 20 - i.e. "partition": "8/20"- then CDF will change N to N = K = 10 and process the request. But if you specify the X/N partition value where X = 11 (X > K) and N = 20 - i.e. "partition": "11/20"- then CDF will reply with an empty result list and no cursor in the response.\

In future releases of the resource APIs, Cognite may reject requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests will result in a 400 Bad Request status.

Responses
200

A list of nodes satisfying the supplied node property filters.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/{revisionId}/nodes/list
Request samples
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get 3D nodes by ID

Required capabilities: threedAcl:READ

Retrieves specific nodes given by a list of IDs.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json
required

The request body containing the IDs of the nodes to retrieve. Will return error 400 if the revision is still being processed.

required
Array of objects (Node3DId) [ 1 .. 1000 ] items
Responses
200

A list of nodes.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/{revisionId}/nodes/byids
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

List 3D ancestor nodes

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.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

nodeId
required
integer <int64>

ID of the node to get the ancestors of.

query Parameters
cursor
string

Cursor for paging through results. In general, if a response contains a nextCursor property, it means that there may be more results, and you should pass that value as the cursor parameter in the next request.

Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.

Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses
200

A list of ancestor nodes.

400

The response for a failed request.

get/3d/models/{modelId}/revisions/{revisionId}/nodes/{nodeId}/ancestors
Request samples 
const nodes3d = await client.revisions3D.list3DNodeAncestors(8252999965991682, 4190022127342195, 572413075141081);
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}
➔ Next to 3D Files