v1

latestOpenAPI 3.1.02026-08-06284092.1 KB

jobs

Start a job

Start a new job against a workflow.

Requires a writer role (MEMBER, ADMIN, or OWNER) in the active organization; VIEWERs are refused. The job is created in IN_PROGRESS status. The workflow must exist, not be soft-deleted, and be visible to the active organization (its own workflows plus system workflows). Members are further restricted to workflows they own, system workflows, or workflows assigned to a group they belong to. Members in the virtual "All workflows" group have unrestricted access. Omit workflow_id to start an ad-hoc job (requires the org to have ad-hoc jobs enabled). Submit step results with POST /{id}/steps/{sort_order} and finalize with POST /{id}/analyse.

post/api/v2/jobs

Request body

workflow_idstring nullable

Id of the workflow to run. The job captures the workflow's current steps automatically and will always resolve to those exact steps, even if the workflow is edited later. Omit to start an ad-hoc job with no workflow (requires the org to have ad-hoc jobs enabled); steps are then added via extra-steps.

namestring nullable

Display name for an ad-hoc job. Ignored when workflow_id is set.

Example request

{
  "workflow_id": "3f9b1c2d-4f7e-4b9a-9a3c-1f7e0d2b5a11",
  "name": "Ad-hoc inspection"
}

Response

Successful Response

idstring required

Stable job id.

workflow_idstring required

Id of the workflow this job is running against.

workflow_namestring nullable

Display name of the workflow this job runs against. Null when the workflow row is unavailable. Additive convenience field so clients need not resolve the name from workflow_id separately.

user_idstring required

Id of the user who started the job.

is_adhocboolean

True when this job runs against a synthetic ad-hoc workflow (no predefined steps). Clients render the workflow column as an ad-hoc placeholder rather than the synthetic workflow name.

organization_idstring nullable

Owning organization id. Null for personal jobs.

status'in_progress' | 'analysing' | 'completed' | 'completed_with_errors' | 'abandoned' required

result'pending' | 'passed' | 'failed'

The pass/fail outcome of a job, distinct from its lifecycle status.

Lifecycle (JobLifecycleStatus) answers "did the run finish, and did any step technically error?". Result answers "did the run pass its checks?". The two are independent: a run can finish cleanly (COMPLETED) yet still FAILED because too few steps passed for the workflow's pass policy.

The pass policy is driven by allow_step_failure:

Off: strict. Any errored or failing step makes the result FAILED.
On: threshold. Failures are tolerated until the percentage of evaluable steps that failed exceeds fail_threshold_percent; errored steps count as failures.
PENDING: not yet determined (job still in progress / analysing).
PASSED: the workflow's pass policy is satisfied.
FAILED: the workflow's pass policy is not satisfied.

started_atstring date-time required

When the job was created.

analysing_started_atstring date-time nullable

When the job transitioned to ANALYSING. Null while still IN_PROGRESS. Used by the stale-analysis recovery sweep to time out crashed analysis tasks.

completed_atstring date-time nullable

When the job was completed. Null while in progress.

allow_adhoc_stepboolean

Whether ad-hoc steps may be appended to this job via POST /jobs/{id}/extra-steps. Mirrors the backing workflow's allow_adhoc_step. Clients should gate the add-step UI on this flag rather than fetching the workflow, which is unavailable for hidden ad-hoc workflows.

allow_out_of_order_stepsboolean

When True, steps may be captured in any order. When False, they must be captured in ascending sort_order. Mirrors the backing workflow's allow_out_of_order_steps so clients can gate step selection without fetching the workflow.

allow_step_skipboolean

When True, the job may be finalised (analysed) with steps left uncaptured. When False, every step must be captured first. Mirrors the backing workflow's allow_step_skip so clients can relax the Analyse gate without fetching the workflow.

Example response

{
  "steps": [
    {
      "name": "Overview shot",
      "workflow_note": "Stand back and capture the whole subject in frame.",
      "agent_id": "object-detection-v1"
    }
  ],
  "extra_steps": [
    {
      "agent_id": "object-detection-v1"
    }
  ]
}