v1

latestOpenAPI 3.1.02026-08-06284092.1 KB

workflows

Start (or resume) a draft of edits to a live workflow

Open an editable draft copy of a live workflow's current definition.

Returns a private draft row (steps and reference images copied from the live workflow) that the caller edits and autosaves without affecting the running workflow, then publishes to apply the changes. Resumes the caller's existing edit draft for this workflow if one is already open, so reopening the editor continues where they left off. The live workflow keeps running untouched until publish.

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

Path parameters

workflow_idstring required

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