Table of contents
Reality Modeling

Jobs

Download API definition:

POST https://api.bentley.com/contextcapture/jobs

Create a new job

Authentication

Requires Authorization header with valid Bearer token for scope contextcapture:modify.

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 scope contextcapture:modify

Accept
Yes

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

Request body

Job Creation

Name
Type
Required?
Description
type
Object
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.

TableSchema
Name
Type
Description
No data.

Job quality

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

TableSchema
Name
Type
Description
No data.

Cost Estimation Parameters

Parameters to be used to estimate the cost of the job

TableSchema
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

TableSchema
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

TableSchema
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

TableSchema
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

Model for creating a new job

TableSchema
Name
Type
Description
type
Object

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

TableSchema
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

TableSchema
Name
Type
Description
submittedDateTime
Date-time

Submission time of the job

startedDateTime
Date-time

Start time of the job

endedDateTime
Date-time

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

TableSchema
Name
Type
Description
format

Output format

id
String,null

Reality Data Id of the output

Job Settings

High-level job settings

TableSchema
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

Job information

TableSchema
Name
Type
Description
id
String

Job unique id

name
String

Job name

type
Object

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

state
Object

Job current state

createdDateTime
Date-time

Creation time of the job

lastModifiedDateTime
Date-time

Last modification date of the job

location
Object

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

TableSchema
Name
Type
Description
job

Complete job details

DetailedError

Contains error information and an array of more specific errors.

TableSchema
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

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.

TableSchema
Name
Type
Description
error

Error Detailed information.

Error

Contains error information.

TableSchema
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

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.

TableSchema
Name
Type
Description
error

Error information.