Create a job - Reality Modeling

Reality Modeling

Download API definition:

Create a job

post https://dev-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

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Job Creation

name

String

Yes

Job name

Job Creation type

jobCreation-type

Yes

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

inputs

jobInput[]

Yes

List of inputs for the job

settings

jobCreateSettings

Yes

workspaceId

String

Yes

Workspace id relative to the job created

costEstimationParameters

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:55.0000000+00:00",
        "lastModifiedDateTime": "2020-09-14T14:29:55.0000000+00:00",
        "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
    }
}

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

Job type

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

Full

String

Calibration

String

Reconstruction

String

json

{
    "enum": [
        "Full",
        "Calibration",
        "Reconstruction"
    ],
    "description": "Job type among 'Full', 'Calibration' and 'Reconstruction'",
    "title": "Job type"
}

Job state

Job current state

unsubmitted

String

active

String

success

String

failed

String

cancelled

String

json

{
    "enum": [
        "unsubmitted",
        "active",
        "success",
        "failed",
        "cancelled"
    ],
    "description": "Job current state",
    "title": "Job state"
}

Job location

Datacenter location of the job

East US

String

North Europe

String

Southeast Asia

String

Australia East

String

UK South

String

Japan East

String

Canada Central

String

West Europe

String

json

{
    "enum": [
        "East US",
        "North Europe",
        "Southeast Asia",
        "Australia East",
        "UK South",
        "Japan East",
        "Canada Central",
        "West Europe"
    ],
    "description": "Datacenter location of the job",
    "title": "Job location"
}

Job

Job information

String

Job unique id

name

String

Job name

Job type

job-type

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

String

User email address

Job state

job-state

Job current state

inputs

jobInput[]

List of inputs for the job

iTwinId

String

Project Id

Job location

job-location

Datacenter location of the job

jobSettings

workspaceId

String

Workspace id relative to the job

estimatedCost

Number

Estimated Cost of the job using the CostEstimationParameters

createdDateTime

Date-time

Creation time of the job

executionInformation

execInfo

lastModifiedDateTime

Date-time

Last modification date of the job

costEstimationParameters

json

{
    "type": "object",
    "title": "Job",
    "required": [
        "id",
        "name",
        "type",
        "state",
        "createdDateTime",
        "lastModifiedDateTime",
        "location",
        "workspaceId",
        "email",
        "inputs",
        "jobSettings"
    ],
    "properties": {
        "id": {
            "type": "string",
            "description": "Job unique id"
        },
        "name": {
            "type": "string",
            "description": "Job name"
        },
        "type": {
            "enum": [
                "Full",
                "Calibration",
                "Reconstruction"
            ],
            "description": "Job type among 'Full', 'Calibration' and 'Reconstruction'",
            "title": "Job type",
            "$ref": "#/components/schemas/job-type"
        },
        "email": {
            "type": "string",
            "description": "User email address"
        },
        "state": {
            "enum": [
                "unsubmitted",
                "active",
                "success",
                "failed",
                "cancelled"
            ],
            "description": "Job current state",
            "title": "Job state",
            "$ref": "#/components/schemas/job-state"
        },
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobInput"
            },
            "description": "List of inputs for the job"
        },
        "iTwinId": {
            "type": "string",
            "description": "Project Id"
        },
        "location": {
            "enum": [
                "East US",
                "North Europe",
                "Southeast Asia",
                "Australia East",
                "UK South",
                "Japan East",
                "Canada Central",
                "West Europe"
            ],
            "description": "Datacenter location of the job",
            "title": "Job location",
            "$ref": "#/components/schemas/job-location"
        },
        "jobSettings": {
            "$ref": "#/components/schemas/jobSettings"
        },
        "workspaceId": {
            "type": "string",
            "description": "Workspace id relative to the job"
        },
        "estimatedCost": {
            "type": "number",
            "description": "Estimated Cost of the job using the CostEstimationParameters"
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time of the job"
        },
        "executionInformation": {
            "$ref": "#/components/schemas/execInfo"
        },
        "lastModifiedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Last modification date of the job"
        },
        "costEstimationParameters": {
            "$ref": "#/components/schemas/costEstimationParameters"
        }
    },
    "description": "Job information",
    "additionalProperties": false
}

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
}

Output format

Supported output formats

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

GaussianSplats

String

json

{
    "enum": [
        "CCOrientations",
        "3MX",
        "3SM",
        "WebReady ScalableMesh",
        "Cesium 3D Tiles",
        "POD",
        "Orthophoto/DSM",
        "LAS",
        "FBX",
        "OBJ",
        "ESRI i3s",
        "DGN",
        "LODTreeExport",
        "PLY",
        "OPC",
        "OMR",
        "ContextScene",
        "GaussianSplats"
    ],
    "title": "Output format",
    "description": "Supported output formats"
}

Job quality

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

Draft

String

Medium

String

Extra

String

json

{
    "enum": [
        "Draft",
        "Medium",
        "Extra"
    ],
    "title": "Job quality",
    "description": "Job quality among 'Draft', 'Medium' and 'Extra'"
}

Execution Info

Execution information relative to a job

errors

ErrorWarningMessages[], null

Errors, if any produced when processing the job

warnings

ErrorWarningMessages[], null

Warnings, if any produced when processing the job

endedDateTime

Date-time, null

End time of the job

estimatedUnits

Number, null

Estimated processing units cost

startedDateTime

Date-time, null

Start time of the job

submittedDateTime

Date-time

Submission time of the job

json

{
    "type": "object",
    "title": "Execution Info",
    "required": [
        "submittedDateTime"
    ],
    "properties": {
        "errors": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/ErrorWarningMessages"
            },
            "nullable": true,
            "description": "Errors, if any produced when processing the job"
        },
        "warnings": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/ErrorWarningMessages"
            },
            "nullable": true,
            "description": "Warnings, if any produced when processing the job"
        },
        "endedDateTime": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "End time of the job"
        },
        "estimatedUnits": {
            "type": "number",
            "nullable": true,
            "description": "Estimated processing units cost"
        },
        "startedDateTime": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Start time of the job"
        },
        "submittedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Submission time of the job"
        }
    },
    "description": "Execution information relative to a job",
    "additionalProperties": false
}

Job Input

Description of an input for a job

String

Context Share reality data id of the input

description

String

Description of the input

json

{
    "type": "object",
    "title": "Job Input",
    "required": [
        "id"
    ],
    "properties": {
        "id": {
            "type": "string",
            "description": "Context Share reality data id of the input"
        },
        "description": {
            "type": "string",
            "description": "Description of the input"
        }
    },
    "description": "Description of an input for a job",
    "additionalProperties": false
}

Job Output

Job output information

String, null

Reality Data Id of the output

format

json

{
    "type": "object",
    "title": "Job Output",
    "required": [
        "format"
    ],
    "properties": {
        "id": {
            "type": "string",
            "nullable": true,
            "description": "Reality Data Id of the output"
        },
        "format": {
            "$ref": "#/components/schemas/format"
        }
    },
    "description": "Job output information",
    "additionalProperties": false
}

Job Creation type

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

Full

String

Calibration

String

Reconstruction

String

json

{
    "enum": [
        "Full",
        "Calibration",
        "Reconstruction"
    ],
    "description": "Job type among 'Full', 'Calibration' and 'Reconstruction'",
    "title": "Job Creation type"
}

Job Creation

Model for creating a new job

name

String

Job name

Job Creation type

jobCreation-type

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

inputs

jobInput[]

List of inputs for the job

settings

jobCreateSettings

workspaceId

String

Workspace id relative to the job created

costEstimationParameters

json

{
    "type": "object",
    "title": "Job Creation",
    "required": [
        "type",
        "name",
        "workspaceId",
        "inputs",
        "settings"
    ],
    "properties": {
        "name": {
            "type": "string",
            "description": "Job name"
        },
        "type": {
            "enum": [
                "Full",
                "Calibration",
                "Reconstruction"
            ],
            "description": "Job type among 'Full', 'Calibration' and 'Reconstruction'",
            "title": "Job Creation type",
            "$ref": "#/components/schemas/jobCreation-type"
        },
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobInput"
            },
            "description": "List of inputs for the job"
        },
        "settings": {
            "$ref": "#/components/schemas/jobCreateSettings"
        },
        "workspaceId": {
            "type": "string",
            "description": "Workspace id relative to the job created"
        },
        "costEstimationParameters": {
            "$ref": "#/components/schemas/costEstimationParameters"
        }
    },
    "description": "Model for creating a new job",
    "additionalProperties": false
}

Job Settings

High-level job settings

outputs

jobOutput[]

List of outputs of the job

quality

cacheSettings

processingEngines

Integer

Maximum usable engines for the job

json

{
    "type": "object",
    "title": "Job Settings",
    "properties": {
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobOutput"
            },
            "description": "List of outputs of the job"
        },
        "quality": {
            "$ref": "#/components/schemas/quality"
        },
        "cacheSettings": {
            "$ref": "#/components/schemas/cacheSettings"
        },
        "processingEngines": {
            "type": "integer",
            "description": "Maximum usable engines for the job"
        }
    },
    "description": "High-level job settings",
    "additionalProperties": false
}

Job response

job

json

{
    "type": "object",
    "title": "Job response",
    "required": [
        "job"
    ],
    "properties": {
        "job": {
            "$ref": "#/components/schemas/job"
        }
    },
    "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
}

Cache settings

Describe how a job will use and create cache

useCache

String

Id of the previous job cache to be reused

createCache

Boolean

Indicate if the job will produce a cache

json

{
    "type": "object",
    "title": "Cache settings",
    "properties": {
        "useCache": {
            "type": "string",
            "description": "Id of the previous job cache to be reused"
        },
        "createCache": {
            "type": "boolean",
            "description": "Indicate if the job will produce a cache"
        }
    },
    "description": "Describe how a job will use and create cache",
    "additionalProperties": false
}

Job Create Settings

Settings for job creation

outputs

format[]

List of output formats to be produced

quality

cacheSettings

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.

json

{
    "type": "object",
    "title": "Job Create Settings",
    "required": [
        "quality",
        "outputs"
    ],
    "properties": {
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/format"
            },
            "description": "List of output formats to be produced"
        },
        "quality": {
            "$ref": "#/components/schemas/quality"
        },
        "cacheSettings": {
            "$ref": "#/components/schemas/cacheSettings"
        },
        "processingEngines": {
            "type": "integer",
            "description": "Number of engines to be used at most, between 0 and your engine limit. If set at 0, it will use your engine limit."
        }
    },
    "description": "Settings for job creation",
    "additionalProperties": false
}

Error and Warning messages

Model for error and warning messages

code

String

Error or warning message code

title

String

Error or warning message title

params

Array

Error or warning message parameters

message

String

Error or warning message

json

{
    "type": "object",
    "title": "Error and Warning messages",
    "properties": {
        "code": {
            "type": "string",
            "description": "Error or warning message code"
        },
        "title": {
            "type": "string",
            "description": "Error or warning message title"
        },
        "params": {
            "type": "array",
            "description": "Error or warning message parameters"
        },
        "message": {
            "type": "string",
            "description": "Error or warning message"
        }
    },
    "description": "Model for error and warning messages",
    "additionalProperties": false
}

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
}

Cost Estimation Parameters

Parameters to be used to estimate the cost of the job

gigaPixels

Number

Gigapixels to be processed

megaPoints

Number

Megapoints to be processed

meshQuality

quality

json

{
    "type": "object",
    "title": "Cost Estimation Parameters",
    "properties": {
        "gigaPixels": {
            "type": "number",
            "description": "Gigapixels to be processed"
        },
        "megaPoints": {
            "type": "number",
            "description": "Megapoints to be processed"
        },
        "meshQuality": {
            "$ref": "#/components/schemas/quality"
        }
    },
    "description": "Parameters to be used to estimate the cost of the job",
    "additionalProperties": false
}

Was this page helpful?

Authentication

Request

Request headers

Request body

Job Creation

Example

Response

Response 201 Created

Response 401 Unauthorized

Response 422 Unprocessable Entity

Response 429 Too many requests

Response headers

Definitions

Job type

Job state

Job location

Job

Error

Output format

Job quality

Execution Info

Job Input

Job Output

Job Creation type

Job Creation

Job Settings

Job response

DetailedError

Error Response

Cache settings

Job Create Settings

Error and Warning messages

Detailed Error Response

Cost Estimation Parameters