Workflow Engine API

Introduction

The Workflow Engine API enables you to create, trigger, and monitor RT3D templates in the cloud. It offers built-in templates for common RT3D data preparation (convert, optimize, transform) so your assets can be interoperable. You can also create your own custom templates to be used by members of your organization. This helps scale your workload, eliminate repetitive tasks, and improve data integrity.

With the Workflow Engine API you can:

Run built-in RT3D templates offered by Unity Technologies using industry leading solutions like Pixyz
Run custom templates with your own operators using custom scripts
Monitor jobs and debug your custom templates

Get Started

Prerequisites: You have a Unity account. To get started, you will first need to create a service account and assign suitable roles for it. Note that you must be an Organization Owner to manage service accounts.

Set up a service account

You can find information on how to create a service account here. After the service account has been created, you will need to authenticate an API and choose the roles that would be assigned to it.

Authentication & Authorization

To learn how to authenticate your requests, please visit the Admin API authentication page.

Roles and Permissions

The service account must have the relevant access to be able to call the APIs. The Workflow Engine API uses the Automation roles. Please see below for the available service account roles and their corresponding access rights:

Role	Access Rights
Automation Developer	Grants full read and write access.
Automation User	Grants access to the read, list and trigger endpoints. Also grants access to retry and terminate job.
Automation Viewer	Grants access to the read and list endpoints.

You can learn more about the Automation roles available on the Admin API authentication page under St (Storage and transformation) section.

Guides

This section contains guides on how to use the API.

Jobs

Get job list

You can retrieve jobs from your organization in a paginated list and narrow the results using filters via [GET /workflow-engine/v1/organizations/{organizationId}/jobs]. The available filters are:

inputDatasetId
inputDatasetVersion
outputDatasetId
outputDatasetVersion
status
template

Monitor a Job

With a job id, you can directly view the state of a job by calling [GET /workflow-engine/v1/organizations/{organizationId}/jobs/{id}]. The response can be used to determine the progress of the job and its individual steps. If its status equals succeeded then it will also contain any output data generated from the workflow.

Retry a Job

With a job id, you can retry a job that failed by calling [PUT /workflow-engine/v1/organizations/{organizationId}/jobs/{id}/retry].

Terminate a Job

With a job id, you can terminate a job that is running by calling [PUT /workflow-engine/v1/organizations/{organizationId}/jobs/{id}/terminate].

Custom Templates

Get custom template list

You can retrieve the list of custom template for your organization via [GET /workflow-engine/v1/organizations/{organizationId}/templates].

Get custom template details

With a custom template's id you can retrieve the template details by calling [GET /workflow-engine/v1/organizations/{organizationId}/templates/{template_id}].

Trigger custom template by id

With a custom template's id you can trigger a template by calling [POST /workflow-engine/v1/organizations/{organizationId}/templates/{template_id}/trigger].

Download OpenAPI specification:

List workflow jobs

Returns list of workflow jobs scoped by organization with optional filters.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

Query parameters for "{title}"

inputDatasetId

string

example: b40397bf-ef96-4106-ab01-4a0dea914aa6

UUID of the input dataset

inputDatasetVersion

string

example: b40397bf-ef96-4106-ab01-4a0dea914aa6

UUID of the input dataset version

outputDatasetId

string

example: b40397bf-ef96-4106-ab01-4a0dea914aa6

UUID of the output dataset

outputDatasetVersion

string

example: b40397bf-ef96-4106-ab01-4a0dea914aa6

UUID of the output dataset version

status

string

example: Running

Status of the workflow job

template

string

example: My Custom Workflow

Name of the workflow template

limit

integer

默认: 10

example: 10

The maximum number of records to return

offset

默认: 0

example: 0

Offset of the records to return

HTTP response status codes for "{title}":

Returns when operation succeeds

Returns when the request fails to process the template's spec

Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs"

Response example

{ "offset": 0, "limit": 0, "total": 0, "results": [ { "id": "c2535cac-969d-4cab-b7b5-9c8b4c7d4658", "name": "my-first-custom-workflow-zpjdt", "status": "Failed", "inputs": {}, "errors": [ { "message": "string", "code": "400" } ], "user_id": "5772981717015", "organization_id": "5772981717015", "from_template": "b40397bf-ef96-4106-ab01-4a0dea914aa6", "template_name": "my-template", "started_at": "2023-02-13T23:17:22+00:00", "finished_at": "2023-02-13T23:17:22+00:00", "duration_in_seconds": 1900, "progress": 100, "error": "Error (exit code 255)", "steps": [ { "id": "file-import-template-2fpj4-3759637542", "name": "download-dataset", "status": "Failed", "error": "Error code 404", "host_node_name": "file-import-template-2fpj4-workspace-index-download-3759637542", "progress": "0.1", "started_at": "2023-02-13T21:45:52+00:00", "finished_at": "2023-02-13T22:45:52+00:00", "duration_seconds": 0 } ], "resource_duration": { "cpu": 1000, "memory": 1000 }, "results": { "step0": { "/output/model.glb": "/api/datasets/822d400b-8565-428b/versions/db127388-adc754a01a9a" } }, "input_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "output_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "outputs": [ { "name": "string", "value": "string" } ], "external_workflow_id": "123e4567-e89b-12d3-a456-426614174000", "updated_at": "2023-02-13T23:17:22+00:00" } ]}

Get workflow job details

Get a workflow job details by providing its ID.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

id

string

必填

Workflow job id

Query parameters for "{title}"

force_refresh

boolean

默认: false

example: true

enforce job synchronization

HTTP response status codes for "{title}":

Returns job details

Returns when not authorized

Returns when job is not found

Validation Error

Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs/{id}"

Response example

{ "id": "c2535cac-969d-4cab-b7b5-9c8b4c7d4658", "name": "my-first-custom-workflow-zpjdt", "status": "Failed", "inputs": {}, "errors": [ { "message": "string", "code": "400" } ], "user_id": "5772981717015", "organization_id": "5772981717015", "from_template": "b40397bf-ef96-4106-ab01-4a0dea914aa6", "template_name": "my-template", "started_at": "2023-02-13T23:17:22+00:00", "finished_at": "2023-02-13T23:17:22+00:00", "duration_in_seconds": 1900, "progress": 100, "error": "Error (exit code 255)", "steps": [ { "id": "file-import-template-2fpj4-3759637542", "name": "download-dataset", "status": "Failed", "error": "Error code 404", "host_node_name": "file-import-template-2fpj4-workspace-index-download-3759637542", "progress": "0.1", "started_at": "2023-02-13T21:45:52+00:00", "finished_at": "2023-02-13T22:45:52+00:00", "duration_seconds": 0 } ], "resource_duration": { "cpu": 1000, "memory": 1000 }, "results": { "step0": { "/output/model.glb": "/api/datasets/822d400b-8565-428b/versions/db127388-adc754a01a9a" } }, "input_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "output_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "outputs": [ { "name": "string", "value": "string" } ], "external_workflow_id": "123e4567-e89b-12d3-a456-426614174000", "updated_at": "2023-02-13T23:17:22+00:00"}

List custom templates

List custom templates for your Organization.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

Query parameters for "{title}"

creatorId

Template's Creator ID

offset

默认: 0

example: 0

Offset to list from

limit

integer

默认: 10

example: 10

The maximum number of templates to return

HTTP response status codes for "{title}":

Returns a list of WorkflowTemplates

Returns when not authorized

Validation Error

Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/templates"

Response example

{ "offset": 0, "limit": 0, "total": 0, "results": [ { "id": "string", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "name": "string", "labels": {}, "description": "string", "creator_id": "string", "annotations": {}, "spec": { "name": "My Custom Workflow", "parameters": [ { "name": "inputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" }, { "name": "inputDatasetVersion", "required": false, "type": "str", "defaultValue": "latest" }, { "name": "outputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" } ], "mounts": [ { "path": "/workspace/inputs", "url": "https://dt.unity.com/api/datasets/{{ inputDatasetId }}/versions/{{ inputDatasetVersion }}" } ], "artifacts": [ { "path": "/workspace/directorylist.txt", "url": "https://dt.unity.com/api/datasets/{{ outputDatasetId }}" } ], "steps": [ { "name": "job-2", "image": "us-central1-docker.pkg.dev/unity-vert-reflect-mgmt/docker/pixyz-compute_engine_cpu:2022.2.0.7", "command": [ "bash" ], "args": [ "find", "/workspace", ">", "/workspace/directorylist.txt" ], "outputs": [ { "name": "OutputDirectoryList", "valueFrom": { "path": "/workspace/directorylist.txt" }, "default": "Empty" } ] } ] }, "inputs": [ { "name": "", "description": "", "defaultValue": null, "type": "str", "required": true, "metadata": {} } ], "organization_ids": [ "string" ], "type": "string" } ]}

Retry a job

Retry a job by providing its ID.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

job_id

string

必填

Job id to retry

HTTP response status codes for "{title}":

Returns when operation succeeds

Returns when not authorized

Returns when job is not found

Validation Error

Returns when an unexpected server error occurs

Returns when server is unavailable

Code samples for "{title}":

Request example

curl -X PUT \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs/{job_id}/retry"

Response example

Terminate a job

Terminate a job by providing its ID.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

job_id

string

必填

Job id to terminate

HTTP response status codes for "{title}":

Returns when operation succeeds

Returns when not authorized

Returns when job is not found

Returns when job is not valid for termination

Validation Error

Returns when an unexpected server error occurs

Returns when server is unavailable

Code samples for "{title}":

Request example

Response example

{ "status": "string"}

Get custom template details

Get a custom template details for your Organization by providing its template ID.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

template_id

string

必填

WorkflowTemplate ID

HTTP response status codes for "{title}":

Returns a WorkflowTemplate

Returns when not authorized

Returns when WorkflowTemplate is not found

Validation Error

Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/templates/{template_id}"

Response example

{ "id": "string", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "name": "string", "labels": {}, "description": "string", "creator_id": "string", "annotations": {}, "spec": { "name": "My Custom Workflow", "parameters": [ { "name": "inputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" }, { "name": "inputDatasetVersion", "required": false, "type": "str", "defaultValue": "latest" }, { "name": "outputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" } ], "mounts": [ { "path": "/workspace/inputs", "url": "https://dt.unity.com/api/datasets/{{ inputDatasetId }}/versions/{{ inputDatasetVersion }}" } ], "artifacts": [ { "path": "/workspace/directorylist.txt", "url": "https://dt.unity.com/api/datasets/{{ outputDatasetId }}" } ], "steps": [ { "name": "job-2", "image": "us-central1-docker.pkg.dev/unity-vert-reflect-mgmt/docker/pixyz-compute_engine_cpu:2022.2.0.7", "command": [ "bash" ], "args": [ "find", "/workspace", ">", "/workspace/directorylist.txt" ], "outputs": [ { "name": "OutputDirectoryList", "valueFrom": { "path": "/workspace/directorylist.txt" }, "default": "Empty" } ] } ] }, "inputs": [ { "name": "", "description": "", "defaultValue": null, "type": "str", "required": true, "metadata": {} } ], "organization_ids": [ "string" ], "type": "string"}

Trigger a custom template

Trigger a custom template for your Organization by providing its template ID.

Authorizations

Client (Client)

HTTP: Client

HTTP Authorization Scheme: bearer

Required scopes: Client

ServiceAccount (ServiceAccount)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string

必填

example: 3973850012340

The active Organization ID

template_id

string

必填

Template ID

Request body for "{title}"

Media Type:

application/json

Schema:

The request body for a template is defined by the parameters outlined in its

WorkflowTemplate.inputs

. The fields in the body correspond with the

name

of each input parameter and their values must adhere to its defined

type

. Required parameters must be included in the request body, while optional parameters can be omitted.

{}

HTTP response status codes for "{title}":

Returns when Job is triggered

Returns when user does not have permission to trigger the resource

Returns when resource is not found

Returns when the request fails to process the template's spec

Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{}' \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/templates/{template_id}/trigger"

Workflow Engine API

Introduction

Get Started

Set up a service account

Authentication & Authorization

Roles and Permissions

Role

Access Rights

Guides

Jobs

Get job list

Monitor a Job

Retry a Job

Terminate a Job

Custom Templates

Get custom template list

Get custom template details

Trigger custom template by id

List workflow jobs

Path parameters for "{title}"

organizationId

Query parameters for "{title}"

inputDatasetId

inputDatasetVersion

outputDatasetId

outputDatasetVersion

status

template

limit

offset

HTTP response status codes for "{title}":

200Returns when operation succeeds

422Returns when the request fails to process the template's spec

500Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

Response example

GET/workflow-engine/v1/organizations/{organizationId}/jobs

Get workflow job details

Path parameters for "{title}"

organizationId

id

Query parameters for "{title}"

force_refresh

HTTP response status codes for "{title}":

200Returns job details

403Returns when not authorized

404Returns when job is not found

422Validation Error

500Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

Response example

GET/workflow-engine/v1/organizations/{organizationId}/jobs/{id}

List custom templates

Path parameters for "{title}"

organizationId

Query parameters for "{title}"

creatorId

offset

limit

HTTP response status codes for "{title}":

200Returns a list of WorkflowTemplates

403Returns when not authorized

422Validation Error

500Returns when an unexpected server error occurs

Code samples for "{title}":

Request example

Response example

GET/workflow-engine/v1/organizations/{organizationId}/templates

Retry a job

Path parameters for "{title}"

organizationId

job_id

HTTP response status codes for "{title}":

200Returns when operation succeeds

403Returns when not authorized

404Returns when job is not found

422Validation Error

500Returns when an unexpected server error occurs