---
title: "Update workflow metadata"
method: PATCH
path: "/api/v2/workflows/{workflow_id}"
tags: ["workflows"]
---

# Update workflow metadata

`PATCH /api/v2/workflows/{workflow_id}`

Patch display metadata (name/description/tags) on the family row.

## Path parameters

- `workflow_id` string, required

## Request body

- WorkflowUpdate — In-place patch for workflow display metadata.
  - `name` string, nullable — New human-readable name. Omit to leave unchanged.
  - `description` string, nullable — New long-form description. Omit to leave unchanged.
  - `tags` string[], nullable — New full tag list (replaces the existing tags). Omit to leave unchanged.
  - `allow_step_skip` boolean, nullable — New value for the skip-steps flag. Omit to leave unchanged.
  - `allow_out_of_order_steps` boolean, nullable — New value for the capture-order flag. Omit to leave unchanged.
  - `allow_step_failure` boolean, nullable — New value for the allow-step-failure flag. Omit to leave unchanged.
  - `fail_threshold_percent` integer, nullable — New fail threshold percentage (0-100). Omit to leave unchanged.
  - `allow_adhoc_step` boolean, nullable — New value for the add-steps-during-run flag. Omit to leave unchanged.
  - `is_tiliter_created` boolean, nullable — Superuser-only. Set the Tiliter-authored ordering flag on a system workflow. Omit to leave unchanged. Rejected (403) for non-superusers.

## Response `200`

Successful Response

- WorkflowRead — Full workflow payload including its steps.
  - `id` string, required — Stable family id, unchanged across edits.
  - `name` string, required — Current human-readable workflow name.
  - `description` string, nullable — Optional long-form description of the workflow's purpose.
  - `tags` string[] — Tag values (system or org-custom) for filtering/grouping.
  - `is_system` boolean, required — True when this is a system workflow visible to every org.
  - `system_source` 'registry' | 'user', nullable — Provenance of a system workflow: 'registry' for a built-in seeded into the environment, 'user' for one promoted from an org's workflow. Null for non-system workflows.
  - `is_tiliter_created` boolean — True when this system workflow is Tiliter-authored. Tiliter-created entries sort ahead of community-promoted ones in the picker. Always false for non-system workflows.
  - `is_deleted` boolean — True when the workflow has been soft-deleted.
  - `status` 'active' | 'draft' | 'deleted' — Lifecycle state of a workflow row. Transitions: ``draft`` -> ``active`` -> ``deleted``. Non-draft rows skip to ``active`` on creation.
  - `allow_step_skip` boolean — When True, the job can be completed with steps left uncaptured. When False, every step must be captured first.
  - `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.
  - `allow_step_failure` boolean — Selects the job pass policy. When False (strict), any step that fails its pass_criteria or errors makes the job's result FAILED. When True (threshold), failures are tolerated until the percentage of evaluable steps that failed exceeds ``fail_threshold_percent``. Either way the job's lifecycle status is unaffected -- only a technical error makes a job COMPLETED_WITH_ERRORS.
  - `fail_threshold_percent` integer — Maximum percentage (0-100) of evaluable steps that may fail before the job is FAILED when ``allow_step_failure`` is True. Ignored when ``allow_step_failure`` is False.
  - `allow_adhoc_step` boolean — When True, the operator may append ad-hoc steps during a run.
  - `owner_user_id` string, nullable — Owning user id. Null for system workflows.
  - `organization_id` string, nullable — Owning organization id. Null for personal workflows.
  - `parent_workflow_id` string, nullable — Set on an edit draft (a 'draft' row that stages changes to a live workflow): the id of the live workflow these edits will publish to. Null on active workflows and on brand-new-workflow drafts.
  - `unpublished_draft_id` string, nullable — On an active workflow, the id of the caller's own in-progress edit draft for it, if one exists (so the client can offer 'resume editing' and show an 'unpublished changes' indicator). Null when the caller has no edit draft for this workflow.
  - `step_count` integer — Number of steps in the workflow.
  - `active_job_count` integer — Number of non-completed jobs currently running against this workflow.
  - `access_user_count` integer — Number of distinct users who have access to this workflow via group membership or direct ownership. Zero for system workflows.
  - `created_at` string, date-time, required — When the workflow was first created.
  - `updated_at` string, date-time, nullable — When the workflow was last modified.
  - `steps` WorkflowStepRead[] — Ordered list of steps in the workflow.
    - `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 reference files (blob-storage object paths) shown to the operator and fed to the agent. 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 reference files. 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.
    - `step_type` 'vision_agent' | 'selection' — 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`` and ``use_selection_as_criteria``. 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
    - `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.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/tiliter/apis/tiliter-vision-ai-public-api.md) · [All operations](https://skmtc.net/tiliter/apis/tiliter-vision-ai-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tiliter/tiliter-vision-ai-public-api/revisions/30b6f7f148f8/schema)