Reality Modeling
Download API definition:
POST https://api.bentley.com/contextcapture/jobs

Create a new job

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.

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

Job Creation

Name
Type
Required?
Description
Job Creation type
Yes

Job type among 'Full', 'Calibration' and 'Reconstruction'

name
String
Yes

Job name

costEstimationParameters
No

Parameters to be used to estimate the cost of the job

workspaceId
String
Yes

Workspace id relative to the job created

inputs
Yes

List of inputs for the job

settings
Yes

Settings for this job

Example

json
{
    "type": "Full",
    "name": "My first Reality Modeling job",
    "costEstimationParameters": {
        "gigaPixels": 2.5,
        "megaPoints": 1.5,
        "meshQuality": "Extra"
    },
    "inputs": [{
            "id": "58e0c0ca-f730-4e5b-808d-1c8cacacb4d4",
            "description": "Drone ImageCollection"
        },
        {
            "id": "dc65ce7d-2598-422f-97a5-5ae8eb004b67",
            "description": "Drone CCOrientations"
        }
    ],
    "workspaceId": "6881117d-9fd2-4900-870b-9b721dc90f25",
    "settings": {
        "quality": "Extra",
        "processingEngines": 5,
        "outputs": [
            "OBJ", "3MX"
        ]
    }
}

Response 201 Created

Created

json
{
    "job": {
        "id": "cc3d35cc-416a-4262-9714-b359da70b419",
        "name": "My first Reality Modeling job",
        "type": "Full",
        "state": "unsubmitted",
        "createdDateTime": "2020-09-14T14:29:55Z",
        "lastModifiedDateTime": "2020-09-14T14:29:55Z",
        "iTwinId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "location": "East US",
        "email": "john.smith@example.com",
        "workspaceId": "6881117d-9fd2-4900-870b-9b721dc90f25",
        "inputs": [{
                "id": "58e0c0ca-f730-4e5b-808d-1c8cacacb4d4",
                "description": "Drone ImageCollection"
            },
            {
                "id": "dc65ce7d-2598-422f-97a5-5ae8eb004b67",
                "description": "Drone CCOrientations"
            }
        ],
        "jobSettings": {
            "quality": "Extra",
            "outputs": [{
                    "format": "OBJ",
                    "id": "3ddee08c-01e8-44a5-8e56-3879109f6728"
                },
                {
                    "format": "3MX",
                    "id": "f18fc6c3-2224-4d63-a04b-52bd18805d01"
                }
            ],
            "processingEngines": 5,
            "cacheSettings": {
                "createCache": true,
                "useCache": "799b11bd-71cf-481a-b284-bf48f672cd9a"
            }
        },
        "costEstimationParameters": {
            "gigaPixels": 2.1,
            "megaPoints": 1.5,
            "meshQuality": "Extra"
        },
        "estimatedCost": 3.5
    }
}

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 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

json
{
    "error": {
        "code": "InvalidContextCaptureRequest",
        "message": "Cannot create job.",
        "details": [{
            "code": "InvalidParameter",
            "message": "Invalid 'type' parameter."
        }]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json
{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

Name
Description
retry-after

The number of requests exceeds the rate-limit for the client subscription.

Output format

Output format among 'CCOrientations', '3MX', '3SM', 'WebReady ScalableMesh', 'Cesium 3D Tiles', 'POD', 'Orthophoto/DSM', 'LAS', 'FBX', 'OBJ', 'ESRI i3s', 'DGN', 'LODTreeExport', 'PLY', 'OPC', OMR and ContextScene.

Name
Type
Description
CCOrientations
String
3MX
String
3SM
String
WebReady ScalableMesh
String
Cesium 3D Tiles
String
POD
String
Orthophoto/DSM
String
LAS
String
FBX
String
OBJ
String
ESRI i3s
String
DGN
String
LODTreeExport
String
PLY
String
OPC
String
OMR
String
ContextScene
String

Job quality

Job quality among 'Draft', 'Medium' and 'Extra'

Name
Type
Description
Draft
String
Medium
String
Extra
String

Cost Estimation Parameters

Parameters to be used to estimate the cost of the job

Name
Type
Description
gigaPixels
Number

Gigapixels to be processed

megaPoints
Number

Megapoints to be processed

meshQuality

Quality of the job

Job Input

Description of an input for a job

Name
Type
Description
id
String

Context Share reality data id of the input

description
String

Description of the input

Cache settings

Describe how a job will use and create cache

Name
Type
Description
createCache
Boolean

Indicate if the job will produce a cache

useCache
String

Id of the previous job cache to be reused

Job Create Settings

Settings for job creation

Name
Type
Description
quality

Quality of the job

processingEngines
Integer

Number of engines to be used at most, between 0 and your engine limit. If set at 0, it will use your engine limit.

outputs

List of output formats to be produced

cacheSettings

Cache settings for the job

Job Creation type

Job type among 'Full', 'Calibration' and 'Reconstruction'

Name
Type
Description
Full
String
Calibration
String
Reconstruction
String

Job Creation

Model for creating a new job

Name
Type
Description
Job Creation type

Job type among 'Full', 'Calibration' and 'Reconstruction'

name
String

Job name

costEstimationParameters

Parameters to be used to estimate the cost of the job

workspaceId
String

Workspace id relative to the job created

inputs

List of inputs for the job

settings

Settings for this job

Error and Warning messages

Model for error and warning messages

Name
Type
Description
code
String

Error or warning message code

title
String

Error or warning message title

message
String

Error or warning message

params
Array

Error or warning message parameters

Execution Info

Execution information relative to a job

Name
Type
Description
submittedDateTime
Date-time

Submission time of the job

startedDateTime
Date-time, null

Start time of the job

endedDateTime
Date-time, null

End time of the job

estimatedUnits
Number, null

Estimated processing units cost

errors

Errors, if any produced when processing the job

warnings

Warnings, if any produced when processing the job

Job Output

Job output information

Name
Type
Description
format

Output format

id
String, null

Reality Data Id of the output

Job Settings

High-level job settings

Name
Type
Description
quality

Quality of the job

processingEngines
Integer

Maximum usable engines for the job

outputs

List of outputs of the job

cacheSettings

Cache settings for the job

Job type

Job type among 'Full', 'Calibration' and 'Reconstruction'

Name
Type
Description
Full
String
Calibration
String
Reconstruction
String

Job state

Job current state

Name
Type
Description
unsubmitted
String
active
String
success
String
failed
String
cancelled
String

Job location

Datacenter location of the job

Name
Type
Description
East US
String
North Europe
String
Southeast Asia
String
Australia East
String
UK South
String
Japan East
String

Job

Job information

Name
Type
Description
id
String

Job unique id

name
String

Job name

Job type

Job type among 'Full', 'Calibration' and 'Reconstruction'

Job state

Job current state

createdDateTime
Date-time

Creation time of the job

lastModifiedDateTime
Date-time

Last modification date of the job

Job location

Datacenter location of the job

iTwinId
String

Project Id

workspaceId
String

Workspace id relative to the job

email
String

User email address

executionInformation

Execution information relative to the job

inputs

List of inputs for the job

jobSettings

Job settings

costEstimationParameters

Parameters to be used to estimate the cost of the job

estimatedCost
Number

Estimated Cost of the job using the CostEstimationParameters

Job response

Name
Type
Description
job

Complete job details

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.