Get started with Reality Management API

Introduction

The Reality Management API provides you the ability to manage and share reality models. This tutorial will help you get started using the Reality Management API.

This tutorial will guide you through:

Creating, modifying and deleting reality data.
Associating and dissociating a reality data to a iTwin.
Uploading and downloading reality models to reality data.

Prerequisites

A reality model, such as a .3mx file.
iTwin created.
- To learn more, see the create and query iTwins guide.
  The created iTwin must have a role that contains the RDS_ASSIGN, RDS_CREATE, RDS_MANAGE and RDS_USE permissions, assigned to yourself. A iTwin created through the iTwins API should give you the necessary permissions automatically. For more information on managing iTwins, you may consult the [iTwins API](/apis/itwins/overview/).

Info

Skill level:

Basic

Duration:

30 minutes

To test the REST API calls directly, use Postman or any other solution capable of sending HTTP requests. If you do it this way, you will require an authorization token for the requests to work. See the Get a token section below for more information.

Postman

1. Register an Application

You will need to register an application to use the iTwin Platform APIs. For this tutorial, a Desktop/Mobile Application is recommended. You can use the Register button to automatically create your first Desktop/Mobile application. This allows you to configure Authorization Code Flow for your Desktop/Mobile application and get the correct access token.

Once generated, a few lines of code is displayed under the button.

IMJS_AUTH_CLIENT_CLIENT_ID - the unique identifier for your application. It is displayed on application details page as Client ID.
IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. It is displayed on application details page as one of Redirect URIs.
IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where to return users after logging out. It is displayed on the application details page as one of Post logout redirect URIs.
IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. It is displayed on the application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial. Select the Digital Twin Management and Visualization API associations and verify that the following scopes are present under Allowed scopes : realitydata:read realitydata:modify

2. Get a Token

To make request to the API, a user token is needed. There are several ways to get it. You can consult the Authorization API documentation here, and you can use a sample powershell script here to use in your app.

3. Create a Reality Data

Reality data properties represent the descriptive data related to a reality data. In addition to this, reality data content is stored as files and folders within a blob container uniquely associated to this reality data. Individual files and folders follow, from the root of the reality data, a normal file tree structure.

Use a POST https://api.bentley.com/reality-management/reality-data HTTP request to create a reality data.

Currently, the required properties for creating a reality data are:

DisplayName : Name of the reality data
Type e.g. “3mx”

Upon successfully creating a reality data, the id property will be generated, and it is used as it’s unique identifier.

Example HTTP Request for POST Reality Data Operation

HTTP

POST https://api.bentley.com/reality-management/reality-data HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

 {
  "iTwinId": "d8414d06-560e-49da-81a5-f7204fa4457b",
  "displayName": "Name of the reality data to create",
  "classification": "Model",
  "type": "3mx",
  "description": "Description of the reality data",
  "tags": [
    "tag"
  ],
  "dataset": "Dataset",
  "rootDocument": "Models/Scene/myModel.3mx",
  "group": "GroupId",
  "authoring": true,
  "acquisition": {
    "startDateTime": "2023-05-18T11:43:05.094Z",
    "endDateTime": "2023-05-18T11:43:05.094Z",
    "acquirer": "Acquirer"
  },
  "extent": {
    "southWest": {
      "latitude": 90,
      "longitude": 180
    },
    "northEast": {
      "latitude": 90,
      "longitude": 180
    }
  }
}
}

Example Response Headers

HTTP

HTTP/1.1 201 Created
Content-Length: 112
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 2b59e2ac-3e89-42bf-9678-2717b395c5bf
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 20:51:49 GMT

Example Response Body

JSON

{
  "realityData": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "displayName": "Name of the reality data to create",
    "classification": "Model",
    "type": "3mx",
    "description": "Description of the reality data",
    "tags": [
      "tag"
    ],
    "dataset": "Dataset",
    "rootDocument": "Models/Scene/myModel.3mx",
    "group": "GroupId",
    "dataCenterLocation": "North Europe",
    "authoring": true,
    "size": 0,
    "acquisition": {
      "startDateTime": "2023-05-18T11:43:05.096Z",
      "endDateTime": "2023-05-18T11:43:05.096Z",
      "acquirer": "Acquirer"
    },
    "extent": {
      "southWest": {
        "latitude": 90,
        "longitude": 180
      },
      "northEast": {
        "latitude": 90,
        "longitude": 180
      }
    },
    "modifiedDateTime": "2023-05-18T11:43:05.096Z",
    "lastAccessedDateTime": "2023-05-18T11:43:05.096Z",
    "createdDateTime": "2023-05-18T11:43:05.096Z"
  }
}

3.1 Upload a Reality Model

Once your reality data is created, you may attach a reality model. The GET https://api.bentley.com/reality-management/reality-data/{id}/writeaccess/?iTwinId={iTwinId} HTTP request will provide you with a SAS URL with write access.

In order to use this resource, consult the Microsoft Documentation

Alternatively, if you do not have a reality model yet and want to generate your own reality model, you may be interested in Reality Modeling

In order to visualize your Reality Model later on by using an iTwin Viewer, the created reality data must have a valid rootDocument value.

Example HTTP Request for Get Write Access To Reality Data Container Operation

HTTP

GET https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825/writeaccess/?iTwinId=615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 200 OK
Cache-Control: must-revalidate, no-cache, private
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Encoding: gzip
ETag: "KtH8hBTTkTuyVh8/AjJ/wdYPRZ4="
Vary: Accept-Encoding
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
Strict-Transport-Security: max-age=63072000
Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9
X-Correlation-ID: dfab9114-7a6c-4cfe-bed0-c03720278dd9
Mas-Request-Id: dfab9114-7a6c-4cfe-bed0-c03720278dd9
Set-Cookie: {...}
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 20:56:34 GMT

Example Response Body

JSON

{
        "type": "AzureBlobSasUrl",
        "permissions": "Write",
        "_links": {
            "containerUrl": {
                "href": "https://realityblobdeveussa01.blob.core.windows.net/69401bde-6200-4c6c-b783-046f1935e825?sv=2020-08-04&se=2021-09-09T07%3A45%3A15Z&sr=c&sp=rl&sig=FiYaKr5m%2FPlev%2FwsOIpopyyCbJC3lbRKwhA3be2SQh8%3D"
            }
        }
}

4. Get Reality Data

There are a few ways to query your reality data. Depending on the app you are developing, one might be more useful than another. You may want to get a single reality data or multiple ones.

Once you have created reality data, the GET https://api.bentley.com/reality-management/reality-data request will be the route to use in order to get your created reality data. Using this call as it will return the first 100 reality data that you have access to, relatively to your organization’s access rights.

The GET https://api.bentley.com/reality-management/reality-data/?iTwinId={iTwinId} request will return the first 100 reality data under the given iTwin, relatively to the iTwin’s access rights. provided you have access to it. A continuation token is provided for further querying.

The GET https://api.bentley.com/reality-management/reality-data/{id} request will only return the reality data with the given identifier, provided that you have access to it.

4.1 Tailoring Reality Data Requests

Optional parameters are available to customize reality data requests :

iTwinId : iTwin Identifier
continuationToken to get more reality data on the current query
$top to query a number of reality data to get in each page
extent to query reality data in a definite area to search.
$orderBy to query reality data by specific property in either ascending or descending order. default is ascending.
$search search reality data by any value.
types to query reality data by type of reality data.
acquisitionStartDateTime to query reality data by acquisition start date time.
acquisitionEndDateTime to query reality data by acquisition end date time.
tag to query reality data by tags assigned at creation time.

You may refer to the Reality Management API Documentation for more information on parameters described above.

When querying multiple realiy data, the Prefer: return=representation header will instruct the API to return all properties on every reality data. Otherwise, only minimal information will be returned, such as id, displayName and type.

Example HTTP Request for Get Reality Data Operation

HTTP

GET https://api.bentley.com/reality-management/reality-data?iTwinId=ec002f93-f0c1-4ab3-a407-351848eba233&$top=2 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Prefer: return=representation
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 200 OK
Cache-Control: must-revalidate, no-cache, private
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Encoding: gzip
ETag: "HwjuhwwP78X3/dL8Efxr36UHJPc="
Vary: Accept-Encoding
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
Strict-Transport-Security: max-age=63072000
Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9
X-Correlation-ID: c6c00c24-e37e-4b30-a070-bd7e8b6090b2
Mas-Request-Id: c6c00c24-e37e-4b30-a070-bd7e8b6090b2
Set-Cookie: {...}
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 21:01:28 GMT

Example Response Body

JSON

{
    "realityData": [
        {
            "id": "4cc193e4-07a7-4ec8-8750-93c68b34cb11",
            "displayName": "A random Reality Data Display Name",
            "dataset": "Dataset",
            "group": "xxx",
            "description": "Lorem ipsum...",
            "rootDocument": "Graz/Scene/Graz.3mx",
            "size": 444055,
            "classification": "Model",
            "type": "3mx",
            "extent": {
                "southWest": {
                    "latitude": 50.1171,
                    "longitude": -122.9543
                },
                "northEast": {
                    "latitude": 50.1172,
                    "longitude": -122.9543
                }
            },
            "acquisition": {},
            "dataCenterLocation": "North Europe",
            "modifiedDateTime": "2017-05-10T13:43:03Z",
            "lastAccessedDateTime": "2021-08-11T00:00:00Z",
            "createdDateTime": "2017-05-10T13:43:03Z"
        },
        {
            "id": "a649f5f9-4c2d-4b2d-8ac0-0ba38d53727c",
            "displayName": "A second Reality Data's Display Name",
            "dataset": "Dataset",
            "group": "xxx",
            "description": "Lorem ipsum...",
            "rootDocument": "Graz/Scene/Graz.3mx",
            "size": 739560,
            "classification": "Model",
            "type": "3mx",
            "extent": {
                "southWest": {
                    "latitude": 50.1171,
                    "longitude": -122.9543
                },
                "northEast": {
                    "latitude": 50.1172,
                    "longitude": -122.9543
                }
            },
            "acquisition": {},
            "dataCenterLocation": "North Europe",
            "modifiedDateTime": "2017-05-10T13:43:03Z",
            "lastAccessedDateTime": "2021-08-11T00:00:00Z",
            "createdDateTime": "2017-05-10T13:43:03Z"
        }
      ],
      "count": 4,
      "_links": {
        "next": {
            "href": "https://api.bentley.com/reality-management/reality-data?iTwinId=ec002f93-f0c1-4ab3-a407-351848eba233&continuationToken=eyJ0b3AiOjUwMCwic2tpcCI6NTAwfQ"
        }
    }
 }

4.2 Visualize your Reality Model

The GET https://api.bentley.com/reality-management/reality-data/{id}/readaccess/?iTwinId={iTwinId} request will provide you with a SAS URL with read access. This will let you download the content of your reality data.

You may want to consult this iTwinjs sample for a quick example to display your reality model.

Example HTTP Request for Get Reality Data Container Operation

HTTP

GET https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825/readaccess/?iTwinId=615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 200 OK
Cache-Control: must-revalidate, no-cache, private
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Encoding: gzip
ETag: "33/0jngG83tl3Zu9AbB+KRdpL34="
Vary: Accept-Encoding
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
Strict-Transport-Security: max-age=63072000
Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9
X-Correlation-ID: 81cc9899-faac-4d84-9149-6bcc26460e1d
Mas-Request-Id: 81cc9899-faac-4d84-9149-6bcc26460e1d
Set-Cookie: {...}
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 21:04:45 GMT

Example Response Body

JSON

{
    "container": {
        "type": "AzureBlobSasUrl",
        "permissions": "Read",
        "_links": {
            "containerUrl": {
                "href": "https://realityblobdeveussa01.blob.core.windows.net/69401bde-6200-4c6c-b783-046f1935e825?sv=2020-08-04&se=2021-09-09T07%3A45%3A15Z&sr=c&sp=rl&sig=FiYaKr5m%2FPlev%2FwsOIpopyyCbJC3lbRKwhA3be2SQh8%3D"
            }
        }
    }
}

5. Modify Reality Data

Reality data properties may be modified at will, provided you have sufficient permissions within the iTwin you are using or if you are the owner of the reality data. Use a PATCH https://api.bentley.com/reality-management/reality-data/{id} HTTP request to modify an existing reality data.

Refer to the Reality Data Properties page of the documentation for the detailed list of properties you can use and modify.

Example HTTP Request for PATCH Reality Data Operation

HTTP

PATCH https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

{
    "iTwinId" : "615f57e7-876e-46fc-ab11-79af30cae299",
    "displayName": "Modified displayname",
    "dataset": "Dataset",
    "group": "xxx",
    "description": "Lorem ipsum 2...",
    "classification": "Model",
    "type": "3mx"
}

Example Response Headers

HTTP

HTTP/1.1 200 OK
Cache-Control: must-revalidate, no-cache, private
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Encoding: gzip
Vary: Accept-Encoding
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
Strict-Transport-Security: max-age=63072000
Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9
X-Correlation-ID: 7c55d6fd-173d-4af5-a9cc-b488077442ae
Mas-Request-Id: 7c55d6fd-173d-4af5-a9cc-b488077442ae
Set-Cookie: {...}
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date:  Mon, 22 May 2023 21:40:30 GMT

Example Response Body

JSON

{
    "realityData": {
        "id": "69401bde-6200-4c6c-b783-046f1935e825",
        "displayName": "Modified displayname",
        "dataset": "Dataset",
        "group": "xxx",
        "description": "Lorem ipsum 2...",
        "size": 0,
        "classification": "Model",
        "type": "3mx",
        "authoring": false,
        "extent": {
            "southWest": {
                "latitude": 50.1171,
                "longitude": -122.9543
            },
            "northEast": {
                "latitude": 50.1172,
                "longitude": -122.9543
            }
        },
        "acquisition": {},
        "dataCenterLocation": "North Europe",
        "modifiedDateTime": "2021-09-08T18:00:47Z",
        "lastAccessedDateTime": "2021-09-08T14:32:14Z",
        "createdDateTime": "2021-09-08T14:32:14Z"
    }
}

5.1 Modify your Reality Model

You can refer to section 3.1 of this guide as it is the same operation, the GET https://api.bentley.com/reality-management/reality-data/{id}/writeaccess/?iTwinId={iTwinId} request will provide you with a SAS URL with write access. From there, you may change the content of the reality model.

Example HTTP Request for Get Reality Data Container Operation

HTTP

GET https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825/writeaccess/?iTwinId=615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 200 OK
Cache-Control: must-revalidate, no-cache, private
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Encoding: gzip
ETag: "33/0jngG83tl3Zu9AbB+KRdpL34="
Vary: Accept-Encoding
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
Strict-Transport-Security: max-age=63072000
Mas-Server: Bentley-WSG/4.0.13,Bentley-WebAPI/2.9
X-Correlation-ID: 81cc9899-faac-4d84-9149-6bcc26460e1d
Mas-Request-Id: 81cc9899-faac-4d84-9149-6bcc26460e1d
Set-Cookie: {...}
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 21:04:45 GMT

Example Response Body

JSON

{
    "container": {
        "type": "AzureBlobSasUrl",
        "permissions": "Write",
        "_links": {
            "containerUrl": {
                "href": "https://realityblobdeveussa01.blob.core.windows.net/69401bde-6200-4c6c-b783-046f1935e825?sv=2020-08-04&se=2021-09-09T07%3A45%3A15Z&sr=c&sp=rl&sig=FiYaKr5m%2FPlev%2FwsOIpopyyCbJC3lbRKwhA3be2SQh8%3D"
            }
        }
    }
}

6. Manage Reality Data Relations to Multiple iTwin

Depending on the purpose of your reality model, you may find useful to have your reality model, therefore it’s reality data, to be available across multiple iTwins. The Reality Management API leverages the strengths of the iTwins API to make your model available to others.

Two actions are possible:

Associating a reality data to a iTwin
Dissociating a reality data from a iTwin

6.1 Associate Reality Data to a iTwin

The POST https://api.bentley.com/reality-management/reality-data/{id}/iTwins/{iTwinId} http request will add an association to the desired iTwin, illustrated by iTwinAssociation.

Example HTTP Request for Associate Reality Data Operation

HTTP

POST https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825/iTwins/615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 200 OK
Content-Length: 112
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 2b59e2ac-3e89-42bf-9678-2717b395c5bf
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 20:51:49 GMT

Example Response Body

JSON

{
        "iTwinAssociation": 
        {
          "id": "69401bde-6200-4c6c-b783-046f1935e825",
          "iTwinId": "615f57e7-876e-46fc-ab11-79af30cae299"
        }
}

6.2 Dissociate Reality Data from a iTwin

The DELETE https://api.bentley.com/reality-management/reality-data/{id}/iTwins/{iTwinId} http request will remove an association from the desired iTwin.

Example HTTP Request for Dissociate Reality Data Operation

HTTP

DELETE https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825/iTwinss/615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 204 No Content
Content-Length: 0
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 07b4d6c4-6f05-492c-9b59-3bc382d4de76
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 14:57:12 GMT

7. Delete Reality Data

Once your reality data is no longer needed, you may delete it with the DELETE https://api.bentley.com/reality-management/reality-data/{id} HTTP request. Upon receiving a 204 No Content response, which indicates a successful deletion, the reality data resource along with it’s reality model will be deleted. There is no need to manually delete the reality model by using GET container http requests with the Write permission.

If your reality data is associated to more than one iTwin, you must first dissociate it from every iTwin, except one. See section 6.2. Note that you must have sufficient rights within the iTwin to delete reality data.

The Reality Management API does not support a 'recycle bin' feature. Deleting a reality data results in immediate deletion of the reality model and it cannot be recovered.

Example HTTP Request for Delete Reality Data Operation

HTTP

DELETE https://api.bentley.com/reality-management/reality-data/69401bde-6200-4c6c-b783-046f1935e825 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

Example Response Headers

HTTP

HTTP/1.1 204 No Content
Content-Length: 0
Request-Context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 8c9990c0-c305-42b3-bd44-db295c80dfbd
X-ITwinPlatform-Media-Type: bentley.itwin-platform.v1
X-ITwinPlatform-Region: East US
Date: Mon, 22 May 2023 14:59:32 GMT

Continue learning

Congratulations for completing the Reality Management API tutorial! You now have the necessary knowledge to use the Reality Management API. To go further and use the Reality Management API to its full potential, you can have a look at the following related tutorials.

Get started with Reality Modeling API

This tutorial is an introduction to Reality Modeling API, explaining the basic workflows.

Get started with Reality Analysis API

This tutorial is an introduction to Reality Analysis API, explaining the basic workflows.

Reality Data

Adding, removing, and modifying the display of reality data. Discovers available realitymodel and attaches the first one to the viewport.

More Resources that you may like

Reality Data API

Complete Reality Data API documentation.

Reality Data Client

Typescript Client provided by itwin.js to facilitate the use the Reality Data API.

Reality Data client Npm Package

Npm Package containing client wrappers for sending requests to the RealityData API.