Sign in

v1

latestOpenAPI 3.1.02026-08-06284092.1 KB
workflows

Update workflow metadata

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

patch/api/v2/workflows/{workflow_id}

Path parameters

workflow_idstring required

Request body

namestring nullable

New human-readable name. Omit to leave unchanged.

descriptionstring nullable

New long-form description. Omit to leave unchanged.

tagsstring[] nullable

New full tag list (replaces the existing tags). Omit to leave unchanged.

allow_step_skipboolean nullable

New value for the skip-steps flag. Omit to leave unchanged.

allow_out_of_order_stepsboolean nullable

New value for the capture-order flag. Omit to leave unchanged.

allow_step_failureboolean nullable

New value for the allow-step-failure flag. Omit to leave unchanged.

fail_threshold_percentinteger nullable

New fail threshold percentage (0-100). Omit to leave unchanged.

allow_adhoc_stepboolean nullable

New value for the add-steps-during-run flag. Omit to leave unchanged.

is_tiliter_createdboolean nullable

Superuser-only. Set the Tiliter-authored ordering flag on a system workflow. Omit to leave unchanged. Rejected (403) for non-superusers.

Response

Successful Response

idstring required

Stable family id, unchanged across edits.

namestring required

Current human-readable workflow name.

descriptionstring nullable

Optional long-form description of the workflow's purpose.

tagsstring[]

Tag values (system or org-custom) for filtering/grouping.

is_systemboolean 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_createdboolean

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_deletedboolean

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_skipboolean

When True, the job can be completed with steps left uncaptured. When False, every step must be captured first.

allow_out_of_order_stepsboolean

When True, steps may be captured in any order. When False, they must be captured in ascending sort_order.

allow_step_failureboolean

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_percentinteger

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_stepboolean

When True, the operator may append ad-hoc steps during a run.

owner_user_idstring nullable

Owning user id. Null for system workflows.

organization_idstring nullable

Owning organization id. Null for personal workflows.

parent_workflow_idstring 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_idstring 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_countinteger

Number of steps in the workflow.

active_job_countinteger

Number of non-completed jobs currently running against this workflow.

access_user_countinteger

Number of distinct users who have access to this workflow via group membership or direct ownership. Zero for system workflows.

created_atstring date-time required

When the workflow was first created.

updated_atstring date-time nullable

When the workflow was last modified.

Example response

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