Table of contents
Reality Management
Download API definition:
POST https://qa-api.bentley.com/reality-management/reality-data/

Creates a reality data.

As shown in the request section below, you must provide a request body.

You MUST provide the displayName and type properties.

The rootDocument property is not required but highly recommended. It is the entry point for consuming applications to read the content of the Reality Data. See RootDocument property

For more details on each property, see Reality Data Properties in documentation.

After creation, the reality data will be associated to the specified iTwin.

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

User must have the realitydata_create permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given iTwin.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit Rate limits and quotas page.

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with itwin-platform scope

Accept
Yes

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

Request body

Reality Data

Name
Type
Required?
Description
iTwinId
String
No

Id of associated iTwin.

displayName
String
Yes

Name of the reality data.

classification
String
No

Specific value constrained field that indicates the nature of the reality data. Allowed values: 'Terrain', 'Imagery', 'Pinned', 'Model', 'Undefined'

type
String
Yes

A key indicating the format of the data. Valid values include '3MX', 'PointCloud', RealityMesh3DTiles', … See documentation for an exhaustive list of registered reality data types.

description
String
No

Description of the reality data.

tags
Array
No

Any string identifier which you can assign to reality data to identify it.

dataset
String
No

This field can be used to define a loose grouping of reality data. This property may not contain any control sequence such as a URL or code.

group
String
No

The group can be used to define a second level of grouping. This property may not contain any control sequence such as a URL or code.

rootDocument
String
No

Used to indicate the root document of the reality data.

acquisition
No

Details about data acquisition.

extent
No

The rectangular area on the Earth which encloses the reality data.

authoring
Boolean
No

A boolean value that is true if the data is being created. It is false if the data has been completely uploaded.

ownerId
String
No

Identifier of the owner of the reality data.

Example

json
{
    "iTwinId": "8f70cca5-2122-4912-8713-49f6cd7f17b1",
    "displayName": "Name of the reality data to create",
    "classification": "Model",
    "type": "3mx",
    "description": "Description of the reality data",
    "dataset": "Dataset",
    "group": "GroupId",
    "rootDocument": "Models/Scene/myModel.3mx",
    "tags": ["tag1", "tag2"],
    "acquisition": {
        "startDateTime": "2021-05-12T20:03:12Z",
        "endDateTime": "2021-05-15T22:07:18Z",
        "acquirer": "Data Acquisition Inc."
    },
    "extent": {
        "southWest": {
            "latitude": 40.0206,
            "longitude": -75.6355
        },
        "northEast": {
            "latitude": 40.0356,
            "longitude": -75.6059
        }
    },
    "authoring": true
}

Response 201 Created

Reality data successfully created

json
{
    "realityData": {
        "id": "95d8dccd-d89e-4287-bb5f-3219acbc71ae",
        "displayName": "Name of reality data",
        "dataset": "Dataset",
        "group": "73d09423-28c3-4fdb-ab4a-03a47a5b04f8",
        "description": "Description of reality data",
        "rootDocument": "Directory/SubDirectory/realityData.3mx",
        "size": 6521212,
        "classification": "Model",
        "type": "3mx",
        "tags": ["tag1", "tag2"],
        "acquisition": {
            "startDateTime": "2021-05-12T20:03:12Z",
            "endDateTime": "2021-05-15T22:07:18Z",
            "acquirer": "Data Acquisition Inc."
        },
        "extent": {
            "southWest": {
                "latitude": 38.0206,
                "longitude": -75.6355
            },
            "northEast": {
                "latitude": 38.0356,
                "longitude": -75.6059
            }
        },
        "authoring": true,
        "dataCenterLocation": "North Europe",
        "modifiedDateTime": "2021-04-09T19:03:12Z",
        "lastAccessedDateTime": "2021-04-09T00:00:00Z",
        "createdDateTime": "2021-02-22T20:03:40Z",
        "ownerId": "f1d49cc7-f9b3-494f-9c67-563ea5597063"
    }
}

Response 401 Unauthorized

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

This response indicates that user does not have required permissions to create a reality data.

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

Response 422 Unprocessable Entity

Invalid request to create reality data. Please ensure that the request is valid.

json
{
    "error": {
        "code": "InvalidRealityDataRequest",
        "message": "Invalid request to create reality data. Can not create reality data.",
        "details": [{
            "code": "InvalidValue",
            "message": "Invalid parameter.",
            "target": "type"
        }]
    }
}

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

Name
Description
retry-after

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

Reality Data Details

Details for a reality data

Name
Type
Description
id
String

Identifier of the reality data. This identifier is assigned by the service at the creation of the reality data. It is also unique.

displayName
String

The name of the reality data. This property may not contain any control sequence such as a URL or code.

dataset
String

This field can be used to define a loose grouping of reality data. This property may not contain any control sequence such as a URL or code.

group
String

The group can be used to define a second level of grouping. This property may not contain any control sequence such as a URL or code.

description
String

A textual description of the reality data. This property may not contain any control sequence such as a URL or code.

tags
Array

Any string identifier which you can assign to reality data to identify it.

rootDocument
String

Used to indicate the root document of the reality data. The root document can be in a subfolder and is then specified as “Tile_Root.json” or “Folder1/SubFolder1/File.json” for example.

size
Int64

The size of the reality data in Kilobytes.

classification
String

Specific value constrained field that indicates the nature of the reality data. The following values are currently supported: Terrain, Imagery, Pinned, Model, Undefined.

type
String

A key indicating the format of the data. The type property should be a specific indication of the format of the reality data. Given a type, the consuming software should be able to determine if it has the capacity to open the reality data. Although the type field is a free string some specific values are reserved and other values should be selected judiciously. Look at the documentation for an exhaustive list of reserved reality data types.

acquisition

Provides information regarding the acquisition, such as dates and acquirer used.

extent

Contains the rectangular area on the Earth which encloses the reality data.

authoring
Boolean

A boolean value that is true if the data is being created. It is false if the data has been completely uploaded.

dataCenterLocation
String

Identifies the data center location used to store the reality data.

modifiedDateTime
Date-time

ISO-8601 compliant time (UTC) of last modification of the reality data. E.g. '2017–05–10T13:43:03Z'

lastAccessedDateTime
Date-time

ISO-8601 compliant time (UTC) of last access of the reality data. E.g. '2017–05–10T13:43:03Z'

createdDateTime
Date-time

ISO-8601 compliant time (UTC) of the creation of the reality data. E.g. '2017–05–10T13:43:03Z'

ownerId
String

Identifier of the owner of the reality data.

Reality Data Details Response

Reality data details response.

Name
Type
Description
realityData

Reality data details properties.

Acquisition

Details about data acquisition.

Name
Type
Description
startDateTime
Date-time

ISO-8601 compliant time (UTC) that indicates when the data acquisition started. E.g. '2017-05-10T13:43:03Z'

endDateTime
Date-time

ISO-8601 compliant time (UTC) that indicates when the data acquisition ended. E.g. '2017-05-10T13:43:03Z'

acquirer
String

Description of the acquirer.

Extent

Extent of a reality data, delimited by southwest and northeast coordinates.

Name
Type
Description
southWest

Extent's southwest coordinate.

northEast

Extent's northeast coordinate.

Coordinate

Coordinate used to define an extent.

Name
Type
Description
latitude
Double

Latitude. Latitude ranges between -90 and 90 degrees, inclusive.

longitude
Double

Longitude. Longitude ranges between -180 and 180 degrees, inclusive.

Reality Data

Request body for reality data creation.

Name
Type
Description
iTwinId
String

Id of associated iTwin.

displayName
String

Name of the reality data.

classification
String

Specific value constrained field that indicates the nature of the reality data. Allowed values: 'Terrain', 'Imagery', 'Pinned', 'Model', 'Undefined'

type
String

A key indicating the format of the data. Valid values include '3MX', 'PointCloud', RealityMesh3DTiles', … See documentation for an exhaustive list of registered reality data types.

description
String

Description of the reality data.

tags
Array

Any string identifier which you can assign to reality data to identify it.

dataset
String

This field can be used to define a loose grouping of reality data. This property may not contain any control sequence such as a URL or code.

group
String

The group can be used to define a second level of grouping. This property may not contain any control sequence such as a URL or code.

rootDocument
String

Used to indicate the root document of the reality data.

acquisition

Details about data acquisition.

extent

The rectangular area on the Earth which encloses the reality data.

authoring
Boolean

A boolean value that is true if the data is being created. It is false if the data has been completely uploaded.

ownerId
String

Identifier of the owner of the reality data.

DetailedError

Contains error information and an array of more specific errors.

Name
Type
Description
code
String

One of a server-defined set of error codes.

message
String

A human-readable representation of the error.

target
String, null

The target of the error.

details

Optional array of more specific errors.

Detailed 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.

Name
Type
Description
error

Error Detailed information.

Error

Contains error information.

Name
Type
Description
code
String

One of a server-defined set of error codes.

message
String

A human-readable representation of the error.

target
String, null

The target of the error.

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.

Name
Type
Description
error

Error information.