Create scene - Scenes | iTwin Platform

Scenes

Download API definition:

This API is a Technical Preview and is available for testing purposes only. Do not use in production.

post https://dev-api.bentley.com/scenes/?iTwinId

Creates a scene associated with the specified iTwin.

You can provide metadata only or include up to 100 objects via the sceneData.objects array. More objects can be added incrementally using the Create scene objects endpoint.

Scene data will be validated based on user permissions and supported object types. See Scene Object Schemas Documentation for a full list of available object schemas.

Request parameters

iTwinId

Yes

Primary iTwin Id associated with the scene

Request headers

x-correlation-id

Activity id used for tracking request

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

SceneCreateDTO

Uuid

Optional identifier for the scene object (must be globally unique)

tagIds

String[]

Optional list of tag ids to apply to this scene. Tags must exist within the same iTwin.

parentId

Uuid

Optional parent Id for the scene

sceneData

All of: SceneDataCreateDTO

Scene informational objects

description

String

Optional detailed description of the scene

displayName

String

Yes

User defined display name of the scene

Example

json

{
    "id": "eda9e67f-24a3-4bd5-aeca-981d2abdb610",
    "displayName": "Construction Site Overview",
    "description": "Bridge construction site showing pier placement and equipment staging areas.",
    "parentId": "d21dd09b-bb38-483a-b34f-5d3d7b3e1bd2",
    "tagIds": ["5051ee31-9d3c-4c4c-bf5d-839f1983dcd8"],
    "sceneData": {
        "objects": [{
            "id": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
            "displayName": "Example Object",
            "order": 1,
            "displayOrder": 1,
            "visible": true,
            "version": "1.0.0",
            "kind": "RepositoryResource",
            "parentId": "d21dd09b-bb38-483a-b34f-5d3d7b3e1bd2",
            "relatedId": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
            "data": {
                "iTwinId": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
                "repositoryId": "imodels",
                "id": "97e0ed3a-9bd6-4668-af67-ae4cbe474fc9",
                "class": "iModels"
            }
        }]
    }
}

Response 201 Created

Created scene.

json

{
    "scene": {
        "id": "eda9e67f-24a3-4bd5-aeca-981d2abdb610",
        "displayName": "Construction Site Overview",
        "description": "Bridge construction site showing pier placement and equipment staging areas.",
        "iTwinId": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
        "sceneData": {
            "objects": [{
                "id": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
                "displayName": "Example Object",
                "visible": true,
                "kind": "RepositoryResource",
                "version": "1.0.0",
                "data": {
                    "iTwinId": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
                    "repositoryId": "imodels",
                    "id": "97e0ed3a-9bd6-4668-af67-ae4cbe474fc9",
                    "class": "iModels"
                }
            }]
        },
        "tags": [{
            "id": "5051ee31-9d3c-4c4c-bf5d-839f1983dcd8",
            "displayName": "Pier Area"
        }],
        "createdById": "37f457a6-25fd-4d4a-8947-974b690158be",
        "creationTime": "2025-05-04T04:14:08.0000000+00:00",
        "lastModified": "2025-05-07T01:15:25.0000000+00:00"
    }
}

Response 400 Bad Request

Unprocessable Entity

json

{
    "error": {
        "code": "InvalidScenesRequest",
        "message": "Cannot create scene.",
        "target": "scene",
        "details": [{
            "code": "InvalidRequestBody",
            "message": "ParentId must be a UUID.",
            "target": "parentId"
        }]
    }
}

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 403 Forbidden

Forbidden

json

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

Response 404 Not Found

Not Found

json

{
    "error": {
        "code": "SceneNotFound",
        "message": "Requested scene is not available.",
        "target": "scene"
    }
}

Response 409 Conflict

Conflict

json

{
    "error": {
        "code": "SceneExists",
        "message": "Scene with id already exists."
    }
}

Response 413 Request Entity Too Large

Payload Too Large

json

{
    "error": {
        "code": "RequestTooLarge",
        "message": "Request body is greater than the max size of 4.5MiB."
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

Error

Contains error information.

code

String

One of a server-defined set of error codes.

target

String, null

The target of the error.

message

String

A human-readable representation of the error.

json

{
    "type": "object",
    "required": [
        "code",
        "message"
    ],
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "target": {
            "type": "string",
            "nullable": true,
            "description": "The target of the error."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "description": "Contains error information.",
    "additionalProperties": true
}

Vector3d

Number

X coordinate.

Number

Y coordinate.

Number

Z coordinate.

json

{
    "type": "object",
    "required": [
        "x",
        "y",
        "z"
    ],
    "properties": {
        "x": {
            "type": "number",
            "description": "X coordinate."
        },
        "y": {
            "type": "number",
            "description": "Y coordinate."
        },
        "z": {
            "type": "number",
            "description": "Z coordinate."
        }
    },
    "additionalProperties": false
}

View3dData

Representation of a 3D view

All of: Vector3d

Defines 'up' direction relative to camera in the view

far

Number

Far plane distance

fov

Number

Angle of the field of view in radians for perspective views

near

Number

Near plane distance

width

Number

Width of the frustum in meters for orthographic views

position

All of: Vector3d

Location of the eye of the camera.

direction

All of: Vector3d

Direction the camera is pointing towards

aspectRatio

Number

Aspect ratio of the view

ecefTransform

Number[]

Array of 16 numbers representing a 4x4 matrix in row-major order

isOrthographic

Boolean

Whether the view is orthographic or perspective

json

{
    "type": "object",
    "required": [
        "position",
        "isOrthographic",
        "aspectRatio",
        "direction",
        "up",
        "near",
        "far",
        "ecefTransform"
    ],
    "properties": {
        "up": {
            "allOf": [
                {
                    "$ref": "#/components/schemas/Vector3d"
                }
            ],
            "description": "Defines 'up' direction relative to camera in the view"
        },
        "far": {
            "type": "number",
            "description": "Far plane distance"
        },
        "fov": {
            "type": "number",
            "description": "Angle of the field of view in radians for perspective views"
        },
        "near": {
            "type": "number",
            "description": "Near plane distance"
        },
        "width": {
            "type": "number",
            "description": "Width of the frustum in meters for orthographic views"
        },
        "position": {
            "allOf": [
                {
                    "$ref": "#/components/schemas/Vector3d"
                }
            ],
            "description": "Location of the eye of the camera."
        },
        "direction": {
            "allOf": [
                {
                    "$ref": "#/components/schemas/Vector3d"
                }
            ],
            "description": "Direction the camera is pointing towards"
        },
        "aspectRatio": {
            "type": "number",
            "description": "Aspect ratio of the view"
        },
        "ecefTransform": {
            "type": "array",
            "items": {
                "type": "number"
            },
            "maxItems": 16,
            "minItems": 16,
            "description": "Array of 16 numbers representing a 4x4 matrix in row-major order"
        },
        "isOrthographic": {
            "type": "boolean",
            "description": "Whether the view is orthographic or perspective"
        }
    },
    "description": "Representation of a 3D view",
    "additionalProperties": false
}

SceneDataDTO

objects

SceneObjectMinimalDTO[]

Scene informational objects

json

{
    "type": "object",
    "required": [
        "objects"
    ],
    "properties": {
        "objects": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/SceneObjectMinimalDTO"
            },
            "description": "Scene informational objects"
        }
    },
    "additionalProperties": false
}

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "$ref": "#/components/schemas/Error",
            "description": "Error information."
        }
    },
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "additionalProperties": false
}

TagMinimalDTO

Uuid

Globally unique identifier for the tag

displayName

String

User defined display name for the tag

json

{
    "type": "object",
    "required": [
        "id",
        "displayName"
    ],
    "properties": {
        "id": {
            "type": "string",
            "format": "UUID",
            "example": "5051ee31-9d3c-4c4c-bf5d-839f1983dcd8",
            "description": "Globally unique identifier for the tag"
        },
        "displayName": {
            "type": "string",
            "example": "Pier Area",
            "description": "User defined display name for the tag"
        }
    },
    "additionalProperties": false
}

SceneCreateDTO

Uuid

Optional identifier for the scene object (must be globally unique)

tagIds

String[]

Optional list of tag ids to apply to this scene. Tags must exist within the same iTwin.

parentId

Uuid

Optional parent Id for the scene

sceneData

All of: SceneDataCreateDTO

Scene informational objects

description

String

Optional detailed description of the scene

displayName

String

User defined display name of the scene

json

{
    "type": "object",
    "required": [
        "displayName"
    ],
    "properties": {
        "id": {
            "type": "string",
            "format": "UUID",
            "example": "eda9e67f-24a3-4bd5-aeca-981d2abdb610",
            "description": "Optional identifier for the scene object (must be globally unique)"
        },
        "tagIds": {
            "type": "array",
            "items": {
                "type": "string",
                "format": "UUID"
            },
            "example": [
                "5051ee31-9d3c-4c4c-bf5d-839f1983dcd8"
            ],
            "description": "Optional list of tag ids to apply to this scene. Tags must exist within the same iTwin."
        },
        "parentId": {
            "type": "string",
            "format": "UUID",
            "example": "d21dd09b-bb38-483a-b34f-5d3d7b3e1bd2",
            "description": "Optional parent Id for the scene"
        },
        "sceneData": {
            "allOf": [
                {
                    "$ref": "#/components/schemas/SceneDataCreateDTO"
                }
            ],
            "description": "Scene informational objects"
        },
        "description": {
            "type": "string",
            "example": "Bridge construction site showing pier placement and equipment staging areas.",
            "description": "Optional detailed description of the scene"
        },
        "displayName": {
            "type": "string",
            "example": "Construction Site Overview",
            "description": "User defined display name of the scene"
        }
    },
    "additionalProperties": false
}

SceneDataCreateDTO

objects

SceneObjectCreateDTO[]

Array of scene objects to create (limit is 100).

json

{
    "type": "object",
    "required": [
        "objects"
    ],
    "properties": {
        "objects": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/SceneObjectCreateDTO"
            },
            "maxItems": 100,
            "description": "Array of scene objects to create (limit is 100)."
        }
    },
    "additionalProperties": false
}

SceneCreateResponse

scene

SceneWithObjectsDTO

json

{
    "type": "object",
    "required": [
        "scene"
    ],
    "properties": {
        "scene": {
            "$ref": "#/components/schemas/SceneWithObjectsDTO"
        }
    },
    "additionalProperties": false
}

SceneWithObjectsDTO

Uuid

Globally unique identifier for the scene

SceneObjectCreateDTO

Uuid

Optional identifier for the scene object (must be globally unique)

data

One of: RepositoryResourceData View3dData

Data for the scene object. The structure of this object must conform to the JSON schema specified by the 'kind' and 'version' fields. Common types include RepositoryResource and View3d, but other types are supported. See the Schemas documentation for the full list of available schemas and examples.

kind

String

Kind of the scene object. Maps to the name of the JSON schema this object conforms to

order

Number

Optional number for the scene object's order in lists.

version

Semver

Maps to the version of the JSON schema this object conforms to

visible

Boolean

Optional initial visibility state for the scene object

parentId

Uuid

Optional parent Id for the scene object

relatedId

Uuid

Id of the related scene object referencing the repository resource this styling object applies to. Only allowed (and required) for resource styling objects.

displayName

String

Optional display name for the scene object

displayOrder

Number

Optional stacking order for clients to control rendering sequence. Objects with lower values are typically drawn beneath objects with higher values.

json

{
    "type": "object",
    "required": [
        "version",
        "kind",
        "data"
    ],
    "properties": {
        "id": {
            "type": "string",
            "format": "UUID",
            "example": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
            "description": "Optional identifier for the scene object (must be globally unique)"
        },
        "data": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/RepositoryResourceData"
                },
                {
                    "$ref": "#/components/schemas/View3dData"
                }
            ],
            "example": {
                "id": "97e0ed3a-9bd6-4668-af67-ae4cbe474fc9",
                "class": "iModels",
                "iTwinId": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
                "repositoryId": "imodels"
            },
            "description": "Data for the scene object. The structure of this object must conform to the JSON schema specified by the 'kind' and 'version' fields. Common types include RepositoryResource and View3d, but other types are supported. See the [Schemas documentation](https://github.com/iTwin/scenes-client/tree/main/docs) for the full list of available schemas and examples."
        },
        "kind": {
            "type": "string",
            "example": "RepositoryResource",
            "description": "Kind of the scene object. Maps to the name of the JSON schema this object conforms to"
        },
        "order": {
            "type": "number",
            "example": 1,
            "description": "Optional number for the scene object's order in lists."
        },
        "version": {
            "type": "string",
            "format": "SemVer",
            "example": "1.0.0",
            "description": "Maps to the version of the JSON schema this object conforms to"
        },
        "visible": {
            "type": "boolean",
            "example": true,
            "description": "Optional initial visibility state for the scene object"
        },
        "parentId": {
            "type": "string",
            "format": "UUID",
            "example": "d21dd09b-bb38-483a-b34f-5d3d7b3e1bd2",
            "description": "Optional parent Id for the scene object"
        },
        "relatedId": {
            "type": "string",
            "format": "UUID",
            "example": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
            "description": "Id of the related scene object referencing the repository resource this styling object applies to. Only allowed (and required) for [resource styling objects](https://github.com/iTwin/scenes-client/tree/main/docs/schemas/resourceStyling)."
        },
        "displayName": {
            "type": "string",
            "example": "Example Object",
            "description": "Optional display name for the scene object"
        },
        "displayOrder": {
            "type": "number",
            "example": 1,
            "description": "Optional stacking order for clients to control rendering sequence. Objects with lower values are typically drawn beneath objects with higher values."
        }
    },
    "additionalProperties": false
}

SceneObjectMinimalDTO

Uuid

Globally unique identifier for the scene object

data

One of: RepositoryResourceData View3dData

Data for the scene object that conforms to the JSON schema specified by the 'kind' and 'version' fields. Common types include RepositoryResource and View3d, but other types are supported. See the Schemas documentation for the full list of available schemas and examples. ⚠️ Important: Treat all strings in this field as potentially untrusted input and always escape or sanitize before rendering.

kind

String

Kind of the scene object. Maps to the name of the JSON schema this object conforms to

order

Number

Optional number for the scene object's order in lists.

version

Semver

Maps to the version of the JSON schema this object conforms to

visible

Boolean

Optional initial visibility state for the scene object

parentId

Uuid

Optional parent Id for the scene object

relatedId

Uuid

Id of the related scene object referencing the repository resource this styling object applies to. Only allowed (and required) for resource styling objects.

displayName

String

Optional display name for the scene object

displayOrder

Number

Optional stacking order for clients to control rendering sequence. Objects with lower values are typically drawn beneath objects with higher values.

json

{
    "type": "object",
    "required": [
        "id",
        "version",
        "kind",
        "data"
    ],
    "properties": {
        "id": {
            "type": "string",
            "format": "UUID",
            "example": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
            "description": "Globally unique identifier for the scene object"
        },
        "data": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/RepositoryResourceData"
                },
                {
                    "$ref": "#/components/schemas/View3dData"
                }
            ],
            "example": {
                "id": "97e0ed3a-9bd6-4668-af67-ae4cbe474fc9",
                "class": "iModels",
                "iTwinId": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
                "repositoryId": "imodels"
            },
            "description": "Data for the scene object that conforms to the JSON schema specified by the 'kind' and 'version' fields. Common types include RepositoryResource and View3d, but other types are supported. See the [Schemas documentation](https://github.com/iTwin/scenes-client/tree/main/docs) for the full list of available schemas and examples. ⚠️ Important: Treat all strings in this field as potentially untrusted input and always escape or sanitize before rendering."
        },
        "kind": {
            "type": "string",
            "example": "RepositoryResource",
            "description": "Kind of the scene object. Maps to the name of the JSON schema this object conforms to"
        },
        "order": {
            "type": "number",
            "example": 1,
            "description": "Optional number for the scene object's order in lists."
        },
        "version": {
            "type": "string",
            "format": "SemVer",
            "example": "1.0.0",
            "description": "Maps to the version of the JSON schema this object conforms to"
        },
        "visible": {
            "type": "boolean",
            "example": true,
            "description": "Optional initial visibility state for the scene object"
        },
        "parentId": {
            "type": "string",
            "format": "UUID",
            "example": "d21dd09b-bb38-483a-b34f-5d3d7b3e1bd2",
            "description": "Optional parent Id for the scene object"
        },
        "relatedId": {
            "type": "string",
            "format": "UUID",
            "example": "1f0b88f0-9d0b-4fd2-88dc-390add547c7f",
            "description": "Id of the related scene object referencing the repository resource this styling object applies to. Only allowed (and required) for [resource styling objects](https://github.com/iTwin/scenes-client/tree/main/docs/schemas/resourceStyling)."
        },
        "displayName": {
            "type": "string",
            "example": "Example Object",
            "description": "Optional display name for the scene object"
        },
        "displayOrder": {
            "type": "number",
            "example": 1,
            "description": "Optional stacking order for clients to control rendering sequence. Objects with lower values are typically drawn beneath objects with higher values."
        }
    },
    "additionalProperties": false
}

RepositoryResourceData

Reference to a single repository resource.

String

Id of the individual resource. Format depends on the repository (may be a GUID or another string identifier).

class

String

Class of the repository containing this resource, e.g. iModels, RealityData, GeographicInformationSystem.

iTwinId

Uuid

Id of the iTwin this repository resource is associated with. Omit for global repository classes, e.g. Cesium.

version

String

Version of the resource, if the repository supports versioning, e.g. an iModel changesetId. If omitted, the latest resource version is used. Format depends on the repository.

subClass

String

SubClass of the repository type if applicable, e.g. WebMapTileService for GIS repositories.

repositoryId

String

Id of the repository that contains this resource. For Bentley repositories like iModels, this is the lowercase class. For external repositories, this is a unique identifier.

json

{
    "type": "object",
    "required": [
        "repositoryId",
        "id",
        "class"
    ],
    "properties": {
        "id": {
            "type": "string",
            "example": "97e0ed3a-9bd6-4668-af67-ae4cbe474fc9",
            "description": "Id of the individual resource. Format depends on the repository (may be a GUID or another string identifier)."
        },
        "class": {
            "type": "string",
            "example": "iModels",
            "description": "Class of the repository containing this resource, e.g. iModels, RealityData, GeographicInformationSystem."
        },
        "iTwinId": {
            "type": "string",
            "format": "UUID",
            "example": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
            "description": "Id of the iTwin this repository resource is associated with. Omit for global repository classes, e.g. Cesium."
        },
        "version": {
            "type": "string",
            "example": "1f2e04b666edce395e37a795e2231e995cbf8349",
            "description": "Version of the resource, if the repository supports versioning, e.g. an iModel changesetId. If omitted, the latest resource version is used. Format depends on the repository."
        },
        "subClass": {
            "type": "string",
            "example": "WebMapTileService",
            "description": "SubClass of the repository type if applicable, e.g. WebMapTileService for GIS repositories."
        },
        "repositoryId": {
            "type": "string",
            "example": "imodels",
            "description": "Id of the repository that contains this resource. For Bentley repositories like iModels, this is the lowercase class. For external repositories, this is a unique identifier."
        }
    },
    "description": "Reference to a single repository resource.",
    "additionalProperties": false
}

Was this page helpful?