TItiliter
jobs

Append an ad-hoc step to a job

Changed on

Append an ad-hoc step to a running job.

Only allowed when the workflow's allow_adhoc_step flag is true. The new step appends at max(existing sort_order) + 1 across both workflow steps and prior extras, so the UI's sort order is stable.

Like :func:submit_job_step, this is capture-only: the metadata arrives as multipart/form-data form fields, the image as a file upload (written straight to object storage), and the background analysis runs at /analyse time.

post/api/v2/jobs/{job_id}/extra-steps

Request

Path parameters

job_idstring required

Request body multipart/form-data

namestring required

Display name for the ad-hoc step.

imagestring binary required

Captured image for this step (standard file upload).

step_typestring nullable

Strategy for the ad-hoc step (e.g. vision_agent). Omit and send legacy agent_id for pre-refactor clients.

step_configstring nullable

Per-type configuration as a JSON object string. Legacy clients may omit this.

agent_idstring nullable

Deprecated. Legacy top-level agent id; folded into step_config when supplied.

workflow_notestring nullable

Optional note shown to the operator for this step.

reference_file_pathsstring[] nullable

Optional reference file object paths for this step (repeatable form field).

agent_parametersstring nullable

Deprecated. Legacy agent parameters as a JSON object string; folded into step_config.

pass_criteriastring nullable

Pass criteria as a JSON object string.

allow_multiple_imagesboolean

Whether this ad-hoc step accepts more than one image per submission.

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.

operator_namestring nullable

Display label for the operator who started the job: their name, or their email when no name is set. Set on the job list and on GET /jobs/{id}; omitted elsewhere and when the user row is unavailable.

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.

site_idstring nullable

Site selected at the start of this inspection.

asset_idstring nullable

Asset selected at the start of this inspection.

location_pathstring nullable

Human-readable site and hierarchy path captured when this inspection started.

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.

enforce_live_captureboolean

When True, step photos must be taken with the live camera and library or file uploads are not offered. Mirrors the backing workflow's enforce_live_capture; False when the job has no workflow.

credits_requiredinteger

Workflow credits POST /jobs/{id}/analyse would charge for this job now.

Example response

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

Changes

  • d1aed8b7c278Revision changes
    • info

      added the optional property to the response with the status

  • b83922616927Revision changes
    • warning

      added the new barcode enum value to the // response property for the response status

    • warning

      added the new barcode enum value to the // response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status