---
title: "Set location before resuming an inspection"
method: PATCH
path: "/api/v2/jobs/{job_id}/location"
tags: ["jobs"]
---

# Set location before resuming an inspection

`PATCH /api/v2/jobs/{job_id}/location`

## Request

- Base URL: `https://api.ai.vision.tiliter.com`
- URL: `https://api.ai.vision.tiliter.com/api/v2/jobs/{job_id}/location`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/tiliter/apis/tiliter-vision-ai-public-api/docs/api/v2/jobs/:job_id/location/patch.ts> (a function with typed inputs; its response is checked against the schema)

Attach a location to an unlabelled in-progress job before capture.

## Path parameters

- `job_id` string, required

## Request body

- JobLocationUpdate: Location selected before an unlabelled in-progress job is resumed.
  - `site_id` string, nullable: Site where the in-progress inspection is being performed.
  - `asset_id` string, nullable: Optional nested location or asset being inspected within the selected site.

## Response `200`

Successful Response

- JobRead: Full job payload including the latest result per step. `steps` is the workflow's steps as they were at the moment the job was started -- not the current workflow. Clients should render the run UI from this list so edits to the workflow after the job started never change historical runs.
  - `id` string, required: Stable job id.
  - `workflow_id` string, required: Id of the workflow this job is running against.
  - `workflow_name` string, 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_id` string, required: Id of the user who started the job.
  - `operator_name` string, 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_adhoc` boolean: 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_id` string, nullable: Owning organization id. Null for personal jobs.
  - `site_id` string, nullable: Site selected at the start of this inspection.
  - `asset_id` string, nullable: Asset selected at the start of this inspection.
  - `location_path` string, 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_at` string, date-time, required: When the job was created.
  - `analysing_started_at` string, 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_at` string, date-time, nullable: When the job was completed. Null while in progress.
  - `steps` WorkflowStepRead[]: The workflow's steps as they were at job start.
    - `id` string, required: Stable id of this step. Useful as a React key on edit forms.
    - `step_key` string, nullable: Stable logical-step identity carried across snapshot versions. Reference files attach to this key, so it round-trips: the editor echoes it back on the step-replace save to keep a step's files. Null on job reads, which never edit steps.
    - `sort_order` integer, required: Zero-based position of this step within the workflow.
    - `name` string, required: Human-readable step title shown to the operator.
    - `workflow_note` string, nullable: Optional guidance shown to the operator before they capture the image.
    - `reference_file_paths` string[], nullable: Optional agent reference images (blob-storage object paths), sent to the agent. Operator instruction images are in ``operator_reference_file_urls``. Populated in workflow contexts; null on the job-read endpoint (GET /jobs/{id}), where only ``reference_file_urls`` is returned.
    - `reference_file_urls` string[], nullable: Short-lived signed download URLs for the step's agent reference images (sent to the agent; operator instruction images are in ``operator_reference_file_urls``). Best-effort: paths that fail to sign are omitted, so this is not positionally aligned with the underlying paths. Populated only on terminal-status job reads (when the results page renders its report); null in workflow contexts and on in-progress/analysing job polls.
    - `operator_reference_file_urls` string[]: Short-lived signed download URLs for the step's operator reference images: shown to the operator while working the step, never sent to the agent and never charged. Best-effort signing, like ``reference_file_urls``. Populated on workflow reads and on in-progress job reads; empty otherwise.
    - `step_type` 'vision_agent' | 'selection' | 'barcode': Discriminator for a workflow step's strategy. Every registered value has a matching :class:`StepTypeSpec` subclass in :mod:`app.workflow_steps` that owns the strategy's config, input, output, submit payload and handlers. Adding a value here is one of the three edits required to register a new step type; see :mod:`app.workflow_steps.registry` for the full checklist.
    - `step_config` object: Per-type configuration for this step. For ``vision_agent`` the blob carries ``agent_id`` and the agent's structured input parameters. For ``selection`` it carries ``options``, ``use_selection_as_criteria``, ``allow_adhoc_option``, and the report-heading pair ``use_as_report_heading`` + ``report_heading_level``. For ``barcode`` it carries ``formats``, the optional value rules (``prefix``, ``suffix``, ``min_length``, ``max_length``, ``characters``) and the same report-heading pair. Empty ``{}`` when the type has no configuration.
    - `agent_id` string, nullable: Deprecated. Prefer ``step_type`` + ``step_config``. Mirrored from ``step_config.agent_id`` for vision-agent steps; the selection sentinel is emitted for legacy clients on selection steps.
    - `agent_parameters` object, nullable: Deprecated. Prefer ``step_config``. Mirrored from ``step_config`` with the ``agent_id`` key stripped for vision-agent steps.
    - `pass_criteria` PassCriteria
      - `combinator` 'and' | 'or', required: How to aggregate rule outcomes. ``and`` requires every rule to pass; ``or`` requires at least one.
      - `rules` PassCriteriaRule[], required: One or more rules to evaluate against the agent response.
        - `path` string, required: Dotted path into agent response.
        - `op` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'exists' | 'not_exists' | 'length_gte' | 'length_lt', required
        - `value` unknown
    - `notification_rule` StepNotificationRule: Who to tell about one step's outcome, and when. Attached to the step, so it is pinned to the workflow version the job ran against. Null means the step notifies nobody.
      - `recipient_user_ids` string[]: Ids of users to notify, in addition to the job owner when ``notify_job_owner`` is set. Ids outside the job's organisation are dropped at dispatch time rather than failing the run.
      - `notify_job_owner` boolean: Whether the user who ran the job is notified.
      - `delivery_channels` NotificationChannel[]: Channels used for this rule. Email and WhatsApp are only sent when explicitly selected.
      - `email_recipients` string[]: Additional email addresses that receive this notification's result summary.
      - `on` 'passed' | 'failed' | 'criteria', required: Step outcome that fires a step-level notification.
      - `criteria` PassCriteria
        - `combinator` 'and' | 'or', required: How to aggregate rule outcomes. ``and`` requires every rule to pass; ``or`` requires at least one.
        - `rules` PassCriteriaRule[], required: One or more rules to evaluate against the agent response.
          - `path` string, required: Dotted path into agent response.
          - `op` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'exists' | 'not_exists' | 'length_gte' | 'length_lt', required
          - `value` unknown
    - `allow_multiple_images` boolean: Whether a capture step accepts more than one image per submission (up to the server-enforced cap). Meaningful only for ``vision_agent`` steps; ignored for ``selection`` steps, which never capture images.
  - `allow_adhoc_step` boolean: 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_steps` boolean: 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_skip` boolean: 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_capture` boolean: 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.
  - `extra_steps` JobExtraStepRead[]: Ad-hoc steps appended to this job via `POST /jobs/{id}/extra-steps`. Empty for jobs started against a workflow with `allow_adhoc_step=false`.
    - `id` string, required: Stable id of this extra step.
    - `sort_order` integer, required: Zero-based position after all workflow steps.
    - `name` string, required: Human-readable name shown to the operator.
    - `workflow_note` string, nullable: Optional guidance copy for the operator.
    - `reference_file_paths` string[], nullable: Optional reference files (blob-storage object paths). Null on the job-read endpoint (GET /jobs/{id}), where only ``reference_file_urls`` is returned.
    - `reference_file_urls` string[], nullable: Short-lived signed download URLs for the step's reference files. Best-effort: paths that fail to sign are omitted, so this is not positionally aligned with the underlying paths. Populated only once the job reaches a terminal status (when the results page renders its report); null on the in-progress/analysing polls.
    - `step_type` 'vision_agent' | 'selection' | 'barcode': Discriminator for a workflow step's strategy. Every registered value has a matching :class:`StepTypeSpec` subclass in :mod:`app.workflow_steps` that owns the strategy's config, input, output, submit payload and handlers. Adding a value here is one of the three edits required to register a new step type; see :mod:`app.workflow_steps.registry` for the full checklist.
    - `step_config` object: Per-type configuration for this step. Empty ``{}`` when the type has none.
    - `agent_id` string, nullable: Deprecated. Mirrored from ``step_config.agent_id`` for vision-agent steps; carries the selection sentinel for legacy selection clients.
    - `agent_parameters` object, nullable: Deprecated. Mirrored from ``step_config`` (with ``agent_id`` stripped for vision-agent steps).
    - `pass_criteria` PassCriteria
      - `combinator` 'and' | 'or', required: How to aggregate rule outcomes. ``and`` requires every rule to pass; ``or`` requires at least one.
      - `rules` PassCriteriaRule[], required: One or more rules to evaluate against the agent response.
        - `path` string, required: Dotted path into agent response.
        - `op` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'exists' | 'not_exists' | 'length_gte' | 'length_lt', required
        - `value` unknown
    - `allow_multiple_images` boolean: Whether this ad-hoc capture step accepts more than one image per submission (up to the server-enforced cap). Meaningful only for ``vision_agent`` steps; ignored for ``selection`` steps, which never capture images.
    - `is_extra` boolean: Always true; lets the UI render ad-hoc chips with a single field check.
  - `step_results` JobStepResultRead[]: Latest result per step (one entry per submitted step).
    - `sort_order` integer, required: Zero-based position of the step in the workflow.
    - `workflow_step_id` string, nullable: Id of the workflow step that this result is for. Null when the result belongs to an ad-hoc extra step added during the job -- `extra_step_id` will be set instead.
    - `extra_step_id` string, nullable: Id of the ad-hoc extra step, if this result is for one.
    - `agent_id` string, nullable: Id of the agent that produced this result. Null for non-agent step types (e.g. an operator-picked selection).
    - `step_input` unknown
    - `step_output` unknown
    - `agent_response` unknown
    - `submitted_at` string, date-time, required: When this (most-recent) result was submitted.
    - `analysis_status` 'pending' | 'running' | 'completed' | 'errored': Per-step analysis lifecycle for the deferred-analysis flow (VA-415). A capture-only POST creates a step row in `pending`. The background completion task transitions it to `running`, then to `completed` or `errored`. The agent verdict (pass/fail) is a separate field on the same row and is only meaningful when `analysis_status == completed`.
    - `passed` boolean, nullable: Verdict from the step's pass-criteria evaluation. Null when the step is informational (no criteria configured) or has not yet been analysed.
    - `pass_explanation` string, nullable: Human-readable summary of which criteria passed / failed.
    - `step_narrative` string, nullable: Resolved, display-ready sentence describing this step's outcome. Built server-side from the agent's declared narrative fields (first non-empty), falling back to the analysis error, then the pass-criteria explanation, then a generic verdict line. This is the same resolution the PDF report uses, so every surface reads the same text. Null while the step has nothing to say yet (e.g. captured but not analysed). Clients should render this instead of deriving text from `step_output`.
    - `error_message` string, nullable: Truncated error message when analysis_status == ERRORED.
    - `image_available` boolean: True when an image was captured for this result and can be fetched via `GET /jobs/{id}/steps/{sort_order}/image-url` (which returns a short-lived signed URL).
    - `capture_batch_index` integer: Zero-based position of this image within its capture batch, defines display order.
    - `capture_batch_id` string, nullable: Id grouping the rows submitted together for one step. Null on legacy rows written before batching existed.
    - `original_filename` string, nullable: Original name of the uploaded file, sanitised to its basename. Null when the client never sent one (e.g. a mobile camera capture).
  - `credits_required` integer: Workflow credits `POST /jobs/{id}/analyse` would charge for this job now.

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-13** `d1aed8b7c278`: 1 info
  - added the optional property `enforce_live_capture` to the response with the `200` status
- **2026-11-02** `b83922616927`: 2 warning, 2 info
  - added the new `barcode` enum value to the `extra_steps/items/step_type` response property for the response status `200`
  - added the new `barcode` enum value to the `steps/items/step_type` response property for the response status `200`
  - added the optional property `credits_required` to the response with the `200` status
  - added the optional property `steps/items/operator_reference_file_urls` to the response with the `200` status
- **2026-10-27** `b29acb7cf93e`: 1 info
  - added the optional property `operator_name` to the response with the `200` status
- **2026-09-04** `eb7293c7622b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tiliter/apis/tiliter-vision-ai-public-api/changes/api/v2/jobs/:job_id/location/patch.md)

---

[API](https://skmtc.dev/tiliter/apis/tiliter-vision-ai-public-api.md) - [All operations](https://skmtc.dev/tiliter/apis/tiliter-vision-ai-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tiliter/apis/tiliter-vision-ai-public-api/revisions/d1aed8b7c278?raw)