Start Pipeline Jobs from Bundles

Pipelines are configured actions that can process an input artifact bundle. Jobs are executions of those pipelines. A job reads the bundle data, processes it asynchronously, and writes generated output back as a new artifact bundle when it completes successfully.

List available actions

Use the bundle action endpoint when a user opens an uploaded bundle and the frontend needs to show what can be done with it.

GET /v1/spatial/bundles/{bundleId}/pipeline-actions
Authorization: Bearer <personal-access-token>

Each action contains the pipeline id to submit, plus the configured displayName, description, optional parameterSchemaJson, default queue priority, and resource hints. Frontends should display the name and description, then use parameterSchemaJson to render pipeline-specific options when it is present.

Example response:

[
  {
    "pipelineVersionId": "a4cf2b66-9cd8-4af8-93d7-8f7fbd7db92a",
    "pipeline": "model-build",
    "version": 3,
    "displayName": "Build model",
    "description": "Create a renderable model from this bundle.",
    "parameterSchemaJson": "{\"type\":\"object\"}",
    "requiredCapabilityClass": "render-gpu",
    "requiresGpu": true,
    "requestedGpuCount": 1,
    "allowCloudBurst": true,
    "maxRuntimeMinutes": 120,
    "defaultPriority": 100
  }
]

Start the job

Submit the selected pipeline id to create a job for the bundle.

POST /v1/spatial/bundles/{bundleId}/jobs
Authorization: Bearer <personal-access-token>
Content-Type: application/json

{
  "pipeline": "model-build",
  "parameters": {
    "quality": "high"
  }
}

The response is 202 Accepted with the created job row. Omit priority to use the pipeline's defaultPriority; send priority only when the user or client needs an explicit override. Higher values run before lower values when matching capacity becomes available. The same workflow is also available through POST /v1/jobs by providing inputBundleId in the request body.

{
  "inputBundleId": "6f7c35ef-4023-4dc0-8de8-00f97df6752a",
  "pipeline": "model-build",
  "parameters": {
    "quality": "high"
  }
}

The API adds bundle context to the job parameters, including bundleId, locationId, bundleType, and detailLevel. Client-provided values are kept under the parameters property.

Permissions

Listing pipeline actions requires read access to the bundle's spatial cluster. Starting a job requires write access, because the job may create a new output bundle for the same location.