Sign in

v1

latestOpenAPI 3.1.02026-08-06284092.1 KB
workflows

Publish a draft (new workflow or edits to a live one)

Publish the caller's draft.

For a brand-new-workflow draft this is the "Save workflow" action: full validation (at least one step, at least one vision agent step, every agent and its parameters valid, pass criteria within range), org name uniqueness, and the plan's workflow cap (the only place a new draft is counted). The row flips from draft to active and normal versioning begins.

For an edit draft (staging changes to an existing live workflow) the draft's steps are applied to the parent as a new snapshot version, its metadata and reference images overwrite the parent's, and the draft is discarded. No cap is consumed (the parent already counts). If the parent has been published again since the draft branched, this returns 409 draft_base_outdated so the author can overwrite (retry with force=true) or discard, rather than silently dropping the newer version. Either way a validation failure leaves the draft intact to fix and retry.

post/api/v2/workflows/{workflow_id}/publish

Path parameters

workflow_idstring required

Query parameters

forceboolean

Publish an edit draft even though its workflow has been published by someone else since the draft branched, overwriting their version.

Publish an edit draft even though its workflow has been published by someone else since the draft branched, overwriting their version.

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"
    }
  ]
}