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>
Idempotency-Key: 9fe7c30d-3134-44ba-b672-1d73d8fdf28c
Content-Type: application/json

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

The response is 202 Accepted with the created job row. Idempotency-Key is required and must contain 1–200 characters. Generate one stable key for each logical enqueue and keep it when retrying a timed-out request. For the same organization and requesting user, an exact replay returns the original job and does not consume another monthly or organization-lifetime job slot. Reusing the key for a different location, input bundle, pipeline, or parameter set returns 409 Conflict.

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 and the same required header.

{
  "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.

When the job publishes a model output, the output bundle uses the input bundle as its parent: previousBundleId equals the job's inputBundleId. The input bundle's children collection contains every direct output bundle published from it. Clients can retrieve those outputs directly with:

GET /v1/spatial/locations/{locationId}/bundles?parentBundleId={inputBundleId}
Authorization: Bearer <personal-access-token>

Permissions

Listing pipeline actions requires final LocationBundles=Read for the exact input bundle and final PipelineScriptsRead=Allow for the organization and every returned concrete active pipeline version. Both checks use the same exact session or personal-access-token identity. Global pipeline registration and activation remain platform AdminFull operations and are not granted by the organization read capability.

Starting a job is a composite authorization decision. Immediately before acceptance, the API requires all of the following final values after organization-entitlement and credential caps:

• JobsEnqueue=Allow at the selected location
• PipelineScriptsRead=Allow and PipelineScriptsExecute=Allow for the exact active pipeline version
• LocationBundles=Read for the input bundle
• LocationBundles=Write for the output location
• a live personal access token identity and sufficient PAT organization and capability scopes when a PAT is used
• one available slot in the organization's current UTC-month job limit
• one available slot in the organization's non-resetting lifetime job limit
• an available Bundle-storage policy for the planned output destination

New jobs and generated output bundles must be organization-owned. User-owned protected spatial rows are unsupported and block startup/readiness rather than being used to enqueue work or silently reassigned.

The queue boundary checks the input bundle, output location, and exact pipeline independently. A request is rejected as a whole if any reference is missing, belongs to another organization, or is inaccessible. On acceptance, the Job and one immutable logical usage charge are committed in one serializable transaction. Worker retries, assignment retries, and an exact API replay do not create another charge. That charge contributes once to the independent monthly and organization-lifetime aggregates. Cancellation, failure, retry, or deletion does not refund either accepted slot.

An exhausted UTC-month allowance returns HTTP 403 with monthly_job_limit_exceeded in monthlyJobAdmission and includes its UTC reset boundary. An exhausted all-time allowance returns lifetime_job_limit_exceeded in lifetimeJobAdmission and never contains reset data. If both limits are exhausted, the response retains both typed entries; the request creates neither a Job nor a charge.

Job acceptance does not permanently reserve permission to publish a result. Before a worker-generated output bundle becomes visible, the API reconstructs the credential recorded at enqueue and rechecks the requesting user's active account, live PAT identity and scopes when applicable, current LocationBundles=Write, current entitlement policy, destination ownership, canonical job output path, and Bundle-storage capacity. It measures every stored object at finalization instead of trusting the worker's declared byte count. The complete output Bundle, all file rows, committed storage usage, and successful Job state are published in one transaction. If any validation or commit fails, none of those database rows becomes visible and the staged objects remain outside the published Bundle. A current ACL, credential, tier, or destination denial persists authorization_changed on the Job and active attempt; a Bundle-capacity denial persists capacity_changed. The attempt remains retryable, and a later completion retry reuses the same logical Job, immutable monthly/lifetime charge, action correlation, and idempotent storage reservation so the full output set is published once without another charge.