Update reality data - Reality Management

Reality Management

Download API definition:

patch https://dev-api.bentley.com/reality-management/reality-data/{id}

Updates the metadata of a reality data.

The iTwinId parameter is optional, but it is preferable to provide it, because the permissions used to allow the modification of the reality data are determined from the iTwin.

With no iTwin specified, it may be possible to modify the reality data (e.g. the caller is the owner), but more permissions may be granted when the iTwinId is provided.

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_manage 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

Request parameters

Yes

Id of reality data

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Request body

Reality Data (Update)

crs

Example

json

{
    "iTwinId": "8f70cca5-2122-4912-8713-49f6cd7f17b1",
    "displayName": "Name of the reality data to modify",
    "classification": "Model",
    "type": "LAS",
    "description": "Description of the reality data",
    "dataset": "Dataset",
    "group": "GroupId",
    "attribution": "Attribution of reality data",
    "termsOfUse": "Terms of use of reality data",
    "rootDocument": "Models/Scene/myModel.las",
    "tags": ["tag1", "tag2"],
    "acquisition": {
        "startDateTime": "2021-05-12T20:03:12.0000000+00:00",
        "endDateTime": "2021-05-15T22:07:18.0000000+00:00",
        "acquirer": "Data Acquisition Inc."
    },
    "extent": {
        "southWest": {
            "latitude": 40.0206,
            "longitude": -75.6355
        },
        "northEast": {
            "latitude": 40.0356,
            "longitude": -75.6059
        }
    },
    "crs": {
        "id": "EPSG:4326",
        "verticalId": "EPSG:5773"
    },
    "authoring": false
}

Response

Response 200 OK

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",
        "attribution": "Attribution of reality data",
        "termsOfUse": "Terms of use of reality data",
        "rootDocument": "Directory/SubDirectory/realityData.las",
        "size": 6521212,
        "classification": "Model",
        "type": "LAS",
        "tags": ["tag1", "tag2"],
        "acquisition": {
            "startDateTime": "2021-05-12T20:03:12.0000000+00:00",
            "endDateTime": "2021-05-15T22:07:18.0000000+00:00",
            "acquirer": "Data Acquisition Inc."
        },
        "extent": {
            "southWest": {
                "latitude": 38.0206,
                "longitude": -75.6355
            },
            "northEast": {
                "latitude": 38.0356,
                "longitude": -75.6059
            }
        },
        "crs": {
            "id": "EPSG:4326",
            "verticalId": "EPSG:5773"
        },
        "authoring": false,
        "dataCenterLocation": "North Europe",
        "modifiedDateTime": "2021-04-09T19:03:12.0000000+00:00",
        "lastAccessedDateTime": "2021-04-09T00:00:00.0000000+00:00",
        "createdDateTime": "2021-02-22T20:03:40.0000000+00:00",
        "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 update a reality data.

json

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

Response 404 Not Found

This response indicates that the specified reality data was not found.

json

{
    "error": {
        "code": "RealityDataNotFound",
        "message": "Requested reality data is not available."
    }
}

Response 422 Unprocessable Entity

Invalid request to update reality data

json

{
    "error": {
        "code": "InvalidRealityDataRequest",
        "message": "Invalid RealityData request.",
        "details": [{
            "code": "InvalidValue",
            "message": "The value 'fe9aac3a-2496-----' is not valid.",
            "target": "id"
        }]
    }
}

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

Crs

Details about the reality data's coordinate reference system.

String

Identifier of the coordinate reference system.

verticalId

String

Optional identifier of the vertical coordinate reference system.

json

{
    "type": "object",
    "title": "Crs",
    "properties": {
        "id": {
            "type": "string",
            "description": "Identifier of the coordinate reference system."
        },
        "verticalId": {
            "type": "string",
            "description": "Optional identifier of the vertical coordinate reference system."
        }
    },
    "description": "Details about the reality data's coordinate reference system.",
    "additionalProperties": false
}

tag

A string identifier.

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
}

Extent

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

northEast

coordinate

southWest

coordinate

json

{
    "type": "object",
    "title": "Extent",
    "properties": {
        "northEast": {
            "$ref": "#/components/schemas/coordinate"
        },
        "southWest": {
            "$ref": "#/components/schemas/coordinate"
        }
    },
    "description": "Extent of a reality data, delimited by southwest and northeast coordinates.",
    "additionalProperties": false
}

Coordinate

Coordinate used to define an extent.

latitude

Double

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

longitude

Double

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

json

{
    "type": "object",
    "title": "Coordinate",
    "properties": {
        "latitude": {
            "type": "number",
            "format": "double",
            "maximum": 90,
            "minimum": -90,
            "description": "Latitude. Latitude ranges between -90 and 90 degrees, inclusive."
        },
        "longitude": {
            "type": "number",
            "format": "double",
            "maximum": 180,
            "minimum": -180,
            "description": "Longitude. Longitude ranges between -180 and 180 degrees, inclusive."
        }
    },
    "description": "Coordinate used to define an extent.",
    "additionalProperties": false
}

Acquisition

Details about data acquisition.

acquirer

String

Description of the acquirer.

endDateTime

Date-time

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

startDateTime

Date-time

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

json

{
    "type": "object",
    "title": "Acquisition",
    "properties": {
        "acquirer": {
            "type": "string",
            "description": "Description of the acquirer."
        },
        "endDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) that indicates when the data acquisition ended. E.g. '2017-05-10T13:43:03Z'"
        },
        "startDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) that indicates when the data acquisition started. E.g. '2017-05-10T13:43:03Z'"
        }
    },
    "description": "Details about data acquisition.",
    "additionalProperties": false
}

DetailedError

Contains error information and an array of more specific errors.

code

String

One of a server-defined set of error codes.

target

String, null

The target of the error.

details

Error[]

Optional array of more specific errors.

message

String

A human-readable representation of the error.

json

{
    "type": "object",
    "required": [
        "code",
        "message",
        "details"
    ],
    "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."
        },
        "details": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Error"
            },
            "description": "Optional array of more specific errors."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "description": "Contains error information and an array of more specific errors.",
    "additionalProperties": true
}

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
}

Reality Data (Update)

Request body for updating a reality data.

crs

Detailed Error Response

error

DetailedError

Error Detailed information.

json

{
    "type": "object",
    "title": "Detailed Error Response",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "$ref": "#/components/schemas/DetailedError",
            "description": "Error Detailed 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
}

Reality Data Details

Details for a reality data

String

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

crs

size

Int64

The size of the reality data in Kilobytes.

tags

tag[]

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.

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.

extent

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.

ownerId

String

Identifier of the owner of 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.

termsOfUse

String

acquisition

attribution

String

The attribution of the reality data.

description

String

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

displayName

String

The name of the reality data. 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. The root document can be in a subfolder and is then specified as “Tile_Root.json” or “Folder1/SubFolder1/File.json” for example.

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.

createdDateTime

Date-time

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

modifiedDateTime

Date-time

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

dataCenterLocation

String

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

lastAccessedDateTime

Date-time

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

json

{
    "type": "object",
    "title": "Reality Data Details",
    "properties": {
        "id": {
            "type": "string",
            "description": "Identifier of the reality data. This identifier is assigned by the service at the creation of the reality data. It is also unique."
        },
        "crs": {
            "$ref": "#/components/schemas/crs"
        },
        "size": {
            "type": "integer",
            "format": "int64",
            "description": "The size of the reality data in Kilobytes."
        },
        "tags": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/tag"
            },
            "description": "A string of lower case characters. Upper case characters will be accepted as input but will be transferred to lower case. Limits: 60 characters. 15 tags per reality data. Prohibited characters: \\ / : * ? , \" < > |"
        },
        "type": {
            "type": "string",
            "description": "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](/apis/reality-management/rm-rd-details/#types)."
        },
        "group": {
            "type": "string",
            "description": "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."
        },
        "extent": {
            "$ref": "#/components/schemas/extent"
        },
        "dataset": {
            "type": "string",
            "description": "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."
        },
        "ownerId": {
            "type": "string",
            "description": "Identifier of the owner of the reality data."
        },
        "authoring": {
            "type": "boolean",
            "description": "A boolean value that is true if the data is being created. It is false if the data has been completely uploaded."
        },
        "termsOfUse": {
            "type": "string",
            "description": "Terms of use of the reality data."
        },
        "acquisition": {
            "$ref": "#/components/schemas/acquisition"
        },
        "attribution": {
            "type": "string",
            "description": "The attribution of the reality data."
        },
        "description": {
            "type": "string",
            "description": "A textual description of the reality data. This property may not contain any control sequence such as a URL or code."
        },
        "displayName": {
            "type": "string",
            "description": "The name of the reality data. This property may not contain any control sequence such as a URL or code."
        },
        "rootDocument": {
            "type": "string",
            "description": "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."
        },
        "classification": {
            "type": "string",
            "description": "Specific value constrained field that indicates the nature of the reality data. The following values are currently supported: Terrain, Imagery, Pinned, Model, Undefined."
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) of the creation of the reality data. E.g. '2017–05–10T13:43:03Z'"
        },
        "modifiedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) of last modification of the reality data. E.g. '2017–05–10T13:43:03Z'"
        },
        "dataCenterLocation": {
            "type": "string",
            "description": "Identifies the data center location used to store the reality data."
        },
        "lastAccessedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 compliant time (UTC) of last access of the reality data. E.g. '2017–05–10T13:43:03Z'"
        }
    },
    "description": "Details for a reality data",
    "additionalProperties": false
}

Reality Data Metadata Response

Reality data metadata response.

realityData

reality-data-metadata

json

{
    "type": "object",
    "title": "Reality Data Metadata Response",
    "properties": {
        "realityData": {
            "$ref": "#/components/schemas/reality-data-metadata"
        }
    },
    "description": "Reality data metadata response.",
    "additionalProperties": false
}

Was this page helpful?