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
OAuth access token with itwin-platform scope
Setting to application/vnd.bentley.itwin-platform.v2+json is recommended.
Request body
Job Creation
Name of the job.
iTwin Id for the job.
List of inputs, outputs and options for the job, must be in sync with type.
Example
{ "specifications": { "inputs": { "pointCloud": "df091f39-377c-48fb-a9c9-9fd0998e151a" }, "options": { "outputFormat": "3DTilesPnts" } }, "name": "My first PC Conversion job", "type": "PointCloudConversion", "iTwinId": "019b18b4-e4c1-4211-b8bb-1bd26b8e955e" }
Response 201 Created
Created
{ "job": { "id": "86e93558-7dbd-40da-8604-245ed345c57a", "state": "Active", "userId": "654e3c44-9a1a-4c72-8f8c-e1245bfcebf3", "executionInfo": { "createdDateTime": "2026-04-04T13:57:24.0000000+00:00" }, "specifications": { "inputs": { "pointCloud": "df091f39-377c-48fb-a9c9-9fd0998e151a" }, "output": "407f2733-75cf-4aa3-bd3d-3cb85221ac43", "options": { "outputFormat": "3DTilesPnts" } }, "name": "My first PC Conversion job", "type": "PointCloudConversion", "iTwinId": "019b18b4-e4c1-4211-b8bb-1bd26b8e955e" } }
Response 400 Bad Request
The 400 (Bad Request) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).
{ "error": { "code": "InvalidRealityConversionRequest", "message": "Invalid request to Reality Conversion.", "details": [{ "code": "InvalidProperty", "message": "Invalid value 'PCConversion' for property 'type', line 15, position 34.", "target": "type" }] } }
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.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
Response 404 Not Found
This response indicates that the requested operation or resource could not be found.
{ "error": { "code": "ResourceNotFound", "message": "The requested resource was not found. Verify the API URL and the Accept header.", "details": [{ "code": "OperationNotFound", "message": "Unable to match incoming request to an operation." }] } }
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.
{ "error": { "code": "RateLimitExceeded", "message": "The client sent more requests than allowed by this API for the current tier of the client." } }
Response headers
Number of seconds to wait until client is allowed to make more requests.
Job
Job information.
Unique id of the job.
Name of the job.
Identifier of the user that created the job.
iTwin Id for the job.
List of inputs, outputs and options for the job, must be in sync with the type.
{ "type": "object", "title": "Job", "required": [ "iTwinId", "specifications", "type", "executionInfo", "id", "state", "userId" ], "properties": { "id": { "type": "string", "description": "Unique id of the job." }, "name": { "type": "string", "default": null, "pattern": "^([^\"<>|:*?\\\\/\\u0000-\\u001f])+$", "nullable": true, "maxLength": 256, "minLength": 3, "description": "Name of the job." }, "type": { "$ref": "#/components/schemas/JobTypes" }, "state": { "$ref": "#/components/schemas/JobState" }, "userId": { "type": "string", "description": "Identifier of the user that created the job." }, "iTwinId": { "type": "string", "description": "iTwin Id for the job." }, "executionInfo": { "$ref": "#/components/schemas/ExecutionInformation" }, "specifications": { "anyOf": [ { "$ref": "#/components/schemas/PointCloudConversionSpecifications" }, { "$ref": "#/components/schemas/PointCloudOptimizationSpecifications" }, { "$ref": "#/components/schemas/TileMapOptimizationSpecifications" }, { "$ref": "#/components/schemas/VectorOptimizationSpecifications" }, { "$ref": "#/components/schemas/MeshSamplingSpecifications" }, { "$ref": "#/components/schemas/ContextSceneTilerSpecifications" } ], "description": "List of inputs, outputs and options for the job, must be in sync with the type." } }, "description": "Job information.", "additionalProperties": false }
Error
Contains error information.
One of a server-defined set of error codes.
The target of the error.
A human-readable representation of the error.
{ "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 }
CSObject
{ "enum": [ "Cameras", "TiePoints", "Annotations" ], "type": "string", "title": "CSObject" }
Job State
Job current state.
{ "enum": [ "Queued", "Active", "TerminatingOnCancel", "TerminatingOnFailure", "Cancelled", "Failed", "Success" ], "type": "string", "title": "Job State", "description": "Job current state." }
Job Types
Supported job types
{ "enum": [ "PointCloudConversion", "PointCloudOptimization", "TileMapOptimization", "VectorOptimization", "MeshSampling", "ContextSceneTiler" ], "title": "Job Types", "description": "Supported job types" }
Job Creation
Model for creating a new job.
Name of the job.
iTwin Id for the job.
List of inputs, outputs and options for the job, must be in sync with type.
{ "type": "object", "title": "Job Creation", "required": [ "iTwinId", "specifications", "type" ], "properties": { "name": { "type": "string", "default": null, "pattern": "^([^\"<>|:*?\\\\/\\u0000-\\u001f])+$", "nullable": true, "maxLength": 256, "minLength": 3, "description": "Name of the job." }, "type": { "$ref": "#/components/schemas/JobTypes" }, "iTwinId": { "type": "string", "description": "iTwin Id for the job." }, "specifications": { "anyOf": [ { "$ref": "#/components/schemas/PointCloudConversionSpecificationsCreate" }, { "$ref": "#/components/schemas/PointCloudOptimizationSpecificationsCreate" }, { "$ref": "#/components/schemas/TileMapOptimizationSpecificationsCreate" }, { "$ref": "#/components/schemas/VectorOptimizationSpecificationsCreate" }, { "$ref": "#/components/schemas/MeshSamplingSpecificationsCreate" }, { "$ref": "#/components/schemas/ContextSceneTilerSpecificationsCreate" } ], "description": "List of inputs, outputs and options for the job, must be in sync with type." } }, "description": "Model for creating a new job.", "additionalProperties": false }
Job Response
{ "type": "object", "title": "Job Response", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/Job" } }, "additionalProperties": false }
CSTilerInputs
ContextScene reality data id to tile
{ "type": "object", "title": "CSTilerInputs", "required": [ "scene" ], "properties": { "scene": { "type": "string", "title": "Scene", "description": "ContextScene reality data id to tile" } }, "additionalProperties": false }
DetailedError
Contains error information and an array of more specific errors.
One of a server-defined set of error codes.
The target of the error.
A human-readable representation of the error.
{ "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.
{ "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 }
CSTilerOptions
{ "type": "object", "title": "CSTilerOptions", "properties": { "objectToTile": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/CSObject" } ], "nullable": true, "description": "Object to tile inside the ContextScene." } }, "additionalProperties": false }
MeshSamplingFormat
{ "enum": [ "OPC", "3DTilesPnts", "3DTilesGlbc", "LAS", "LAZ", "E57", "POD" ], "type": "string", "title": "MeshSamplingFormat" }
Mesh Sampling Inputs
Reality data Ids of meshes to sample
{ "type": "object", "title": "Mesh Sampling Inputs", "required": [ "meshes" ], "properties": { "meshes": { "type": "array", "items": { "type": "string" }, "title": "Meshes", "description": "Reality data Ids of meshes to sample" } }, "additionalProperties": false }
PointCloud Conversion Format
{ "enum": [ "OPC", "3DTilesPnts", "3DTilesGlbc", "LAS", "LAZ", "E57", "POD" ], "type": "string", "title": "PointCloud Conversion Format" }
PointCloud Conversion Inputs
Reality data Id of point cloud(s) to convert
{ "type": "object", "title": "PointCloud Conversion Inputs", "required": [ "pointCloud" ], "properties": { "pointCloud": { "type": "string", "title": "PointCloud", "description": "Reality data Id of point cloud(s) to convert" } }, "additionalProperties": false }
TileMap Image Format
{ "enum": [ "JPG", "PNG" ], "type": "string", "title": "TileMap Image Format" }
Mesh Sampling Options
CRS for the input data
Sampling value in meter
CRS for the output data
{ "type": "object", "title": "Mesh Sampling Options", "properties": { "inputCrs": { "type": "string", "nullable": true, "description": "CRS for the input data" }, "sampling": { "type": "number", "title": "Sampling", "nullable": true, "description": "Sampling value in meter" }, "outputCrs": { "type": "string", "nullable": true, "description": "CRS for the output data" }, "outputFormat": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/MeshSamplingFormat" } ], "nullable": true, "description": "Output format for the conversion." } }, "additionalProperties": false }
PointCloud Conversion Options
CRS for the input data
CRS for the output data
{ "type": "object", "title": "PointCloud Conversion Options", "properties": { "inputCrs": { "type": "string", "nullable": true, "description": "CRS for the input data" }, "outputCrs": { "type": "string", "nullable": true, "description": "CRS for the output data" }, "outputFormat": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PCConversionFormat" } ], "nullable": true, "description": "Output format for the conversion." } }, "additionalProperties": false }
Execution Information
Execution information of a job.
End time of the job.
Creation time of the job.
The number of processing units consumed by the job.
Start time of the job.
{ "type": "object", "title": "Execution Information", "required": [ "createdDateTime" ], "properties": { "endedDateTime": { "type": "string", "format": "date-time", "default": null, "nullable": true, "description": "End time of the job." }, "createdDateTime": { "type": "string", "format": "date-time", "description": "Creation time of the job." }, "processingUnits": { "type": "number", "default": null, "nullable": true, "description": "The number of processing units consumed by the job." }, "startedDateTime": { "type": "string", "format": "date-time", "default": null, "nullable": true, "description": "Start time of the job." } }, "description": "Execution information of a job.", "additionalProperties": false }
PointCloud Optimization Format
{ "enum": [ "OPC", "3DTilesPnts", "3DTilesGlbc", "LAS", "LAZ", "E57", "POD" ], "type": "string", "title": "PointCloud Optimization Format" }
PointCloud Optimization Inputs
Reality data Ids of point cloud(s) to convert
{ "type": "object", "title": "PointCloud Optimization Inputs", "required": [ "pointClouds" ], "properties": { "pointClouds": { "type": "array", "items": { "type": "string" }, "title": "Pointclouds", "description": "Reality data Ids of point cloud(s) to convert" } }, "additionalProperties": false }
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.
{ "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 }
PointCloud Optimization Options
CRS for the input data
CRS for the output data
{ "type": "object", "title": "PointCloud Optimization Options", "properties": { "inputCrs": { "type": "string", "nullable": true, "description": "CRS for the input data" }, "outputCrs": { "type": "string", "nullable": true, "description": "CRS for the output data" }, "outputFormat": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PCOptimizationFormat" } ], "nullable": true, "description": "Output format for the conversion." } }, "additionalProperties": false }
Vector Optimization Format
{ "enum": [ "GeoJSON", "FeatureDB" ], "type": "string", "title": "Vector Optimization Format" }
Vector Optimization Inputs
Reality data Ids of vectors to consolidate
{ "type": "object", "title": "Vector Optimization Inputs", "required": [ "vectors" ], "properties": { "vectors": { "type": "array", "items": { "type": "string" }, "title": "Vectors", "description": "Reality data Ids of vectors to consolidate" } }, "additionalProperties": false }
TileMap Optimization Format
{ "enum": [ "XYZTileMap" ], "type": "string", "title": "TileMap Optimization Format" }
TileMap Optimization Inputs
Reality data Ids of tile maps to convert
{ "type": "object", "title": "TileMap Optimization Inputs", "required": [ "tileMaps" ], "properties": { "tileMaps": { "type": "array", "items": { "type": "string" }, "title": "Tile Maps", "description": "Reality data Ids of tile maps to convert" } }, "additionalProperties": false }
Vector Optimization Options
CRS for the input data
CRS for the output data
Display class name
{ "type": "object", "title": "Vector Optimization Options", "properties": { "inputCrs": { "type": "string", "nullable": true, "description": "CRS for the input data" }, "outputCrs": { "type": "string", "nullable": true, "description": "CRS for the output data" }, "outputFormat": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/VectorOptimizationFormat" } ], "nullable": true, "description": "Output format for the conversion." }, "featureClassDisplayName": { "type": "string", "title": "Feature Class Display Name", "nullable": true, "description": "Display class name" } }, "additionalProperties": false }
Mesh Sampling Specifications
Specifications for Mesh Sampling.
Reality Data id of the sampled point cloud
{ "type": "object", "title": "Mesh Sampling Specifications", "required": [ "inputs", "output" ], "properties": { "inputs": { "$ref": "#/components/schemas/MeshSamplingInputs" }, "output": { "type": "string", "title": "output", "description": "Reality Data id of the sampled point cloud" }, "options": { "allOf": [ { "$ref": "#/components/schemas/MeshSamplingOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for Mesh Sampling.", "additionalProperties": false }
TileMap Optimization Options
CRS for the input data
Top level of the tile map to generate.
CRS for the output data
Quality of JPG tiles to generate
Bottom level of the tile map to generate.
Background color to use for tiles
{ "type": "object", "title": "TileMap Optimization Options", "properties": { "inputCrs": { "type": "string", "nullable": true, "description": "CRS for the input data" }, "topLevel": { "type": "integer", "title": "Top Level", "nullable": true, "description": "Top level of the tile map to generate." }, "outputCrs": { "type": "string", "nullable": true, "description": "CRS for the output data" }, "jpgQuality": { "type": "integer", "title": "JPG Quality", "maximum": 99, "minimum": 10, "nullable": true, "description": "Quality of JPG tiles to generate" }, "bottomLevel": { "type": "integer", "title": "Bottom Level", "nullable": true, "description": "Bottom level of the tile map to generate." }, "imageFormat": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/TileMapImageFormat" } ], "nullable": true, "description": "Image format" }, "outputFormat": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/TileMapOptimizationFormat" } ], "nullable": true, "description": "Output format for the conversion." }, "backgroundColor": { "type": "string", "title": "Background Color", "pattern": "^#[a-fA-F0-9]{6}$", "nullable": true, "description": "Background color to use for tiles" } }, "additionalProperties": false }
Context Scene Tiler Specifications
Specifications for Context Scene Tiler.
Reality Data id of tiled ContextScene
{ "type": "object", "title": "Context Scene Tiler Specifications", "required": [ "inputs", "output" ], "properties": { "inputs": { "$ref": "#/components/schemas/CSTilerInputs" }, "output": { "type": "string", "title": "output", "description": "Reality Data id of tiled ContextScene" }, "options": { "allOf": [ { "$ref": "#/components/schemas/CSTilerOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for Context Scene Tiler.", "additionalProperties": false }
Mesh Sampling Specifications for Creation
Specifications for Mesh Sampling job creation.
{ "type": "object", "title": "Mesh Sampling Specifications for Creation", "required": [ "inputs" ], "properties": { "inputs": { "$ref": "#/components/schemas/MeshSamplingInputs" }, "options": { "allOf": [ { "$ref": "#/components/schemas/MeshSamplingOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for Mesh Sampling job creation.", "additionalProperties": false }
Vector Optimization Specifications
Specifications for Vector Optimization.
Reality Data id of the vector data or Feature DB index (fdb:)
{ "type": "object", "title": "Vector Optimization Specifications", "required": [ "inputs", "output" ], "properties": { "inputs": { "$ref": "#/components/schemas/VectorOptimizationInputs" }, "output": { "type": "string", "title": "output", "description": "Reality Data id of the vector data or Feature DB index (fdb:)" }, "options": { "allOf": [ { "$ref": "#/components/schemas/VectorOptimizationOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for Vector Optimization.", "additionalProperties": false }
TileMap Optimization Specifications
Specifications for TileMap Optimization.
Reality Data id of the tile map
{ "type": "object", "title": "TileMap Optimization Specifications", "required": [ "inputs", "output" ], "properties": { "inputs": { "$ref": "#/components/schemas/TileMapOptimizationInputs" }, "output": { "type": "string", "title": "output", "description": "Reality Data id of the tile map" }, "options": { "allOf": [ { "$ref": "#/components/schemas/TileMapOptimizationOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for TileMap Optimization.", "additionalProperties": false }
PointCloud Conversion Specifications
Specifications for PointCloud Conversion.
Reality Data id of the converted point cloud
{ "type": "object", "title": "PointCloud Conversion Specifications", "required": [ "inputs", "output" ], "properties": { "inputs": { "$ref": "#/components/schemas/PCConversionInputs" }, "output": { "type": "string", "title": "output", "description": "Reality Data id of the converted point cloud" }, "options": { "allOf": [ { "$ref": "#/components/schemas/PCConversionOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for PointCloud Conversion.", "additionalProperties": false }
PointCloud Optimization Specifications
Specifications for PointCloud Optimization.
Reality Data id of the converted point cloud
{ "type": "object", "title": "PointCloud Optimization Specifications", "required": [ "inputs", "output" ], "properties": { "inputs": { "$ref": "#/components/schemas/PCOptimizationInputs" }, "output": { "type": "string", "title": "output", "description": "Reality Data id of the converted point cloud" }, "options": { "allOf": [ { "$ref": "#/components/schemas/PCOptimizationOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for PointCloud Optimization.", "additionalProperties": false }
Context Scene Tiler Specifications Create
Specifications for Context Scene Tiler job creation.
{ "type": "object", "title": "Context Scene Tiler Specifications Create", "required": [ "inputs" ], "properties": { "inputs": { "$ref": "#/components/schemas/CSTilerInputs" }, "options": { "allOf": [ { "$ref": "#/components/schemas/CSTilerOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for Context Scene Tiler job creation.", "additionalProperties": false }
Vector Optimization Specifications for Creation
Specifications for Vector Optimization job creation.
{ "type": "object", "title": "Vector Optimization Specifications for Creation", "required": [ "inputs" ], "properties": { "inputs": { "$ref": "#/components/schemas/VectorOptimizationInputs" }, "options": { "allOf": [ { "$ref": "#/components/schemas/VectorOptimizationOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for Vector Optimization job creation.", "additionalProperties": false }
TileMap Optimization Specifications for Creation
Specifications for TileMap Optimization job creation.
{ "type": "object", "title": "TileMap Optimization Specifications for Creation", "required": [ "inputs" ], "properties": { "inputs": { "$ref": "#/components/schemas/TileMapOptimizationInputs" }, "options": { "allOf": [ { "$ref": "#/components/schemas/TileMapOptimizationOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for TileMap Optimization job creation.", "additionalProperties": false }
PointCloud Conversion Specifications for Creation
Specifications for PointCloud Conversion job creation.
{ "type": "object", "title": "PointCloud Conversion Specifications for Creation", "required": [ "inputs" ], "properties": { "inputs": { "$ref": "#/components/schemas/PCConversionInputs" }, "options": { "allOf": [ { "$ref": "#/components/schemas/PCConversionOptions" } ], "nullable": true, "description": "Options for the job." } }, "description": "Specifications for PointCloud Conversion job creation.", "additionalProperties": false }
PointCloud Optimization Specifications for Creation
Specifications for PointCloud Optimization job creation.
{ "type": "object", "title": "PointCloud Optimization Specifications for Creation", "required": [ "inputs" ], "properties": { "inputs": { "$ref": "#/components/schemas/PCOptimizationInputs" }, "options": { "allOf": [ { "$ref": "#/components/schemas/PCOptimizationOptions" } ], "nullable": true, "description": "Options" } }, "description": "Specifications for PointCloud Optimization job creation.", "additionalProperties": false }
Was this page helpful?