workflows

Save a new workflow draft

Persist an in-progress workflow as a resumable draft.

A draft is a real workflow row in draft status: it is private to its author, never appears in the normal workflow list, never counts against the plan's workflow cap, and cannot be run, cloned, promoted, or shared. Validation is deliberately loose so a half-finished workflow (missing steps, an unconfigured agent, no name) still saves. There is no capacity gate here on purpose. The cap is enforced only when the draft is published. No WORKFLOW_CREATED audit is written for a draft; that is emitted at publish time when the workflow becomes real.

post/api/v2/workflows/drafts

Request body

namestring

Draft name (may be blank until published).

descriptionstring nullable

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

tagsstring[]

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

allow_step_skipboolean

Allow completing the job with uncaptured steps.

allow_out_of_order_stepsboolean

Allow capturing steps in any order.

allow_step_failureboolean

Strict (False) fails the job on any failing step; threshold (True) uses fail_threshold_percent.

fail_threshold_percentinteger

Percentage of steps that can fail before workflow fails (0-100).

allow_adhoc_stepboolean

Allow the operator to append ad-hoc steps during a run.

Example request

{
  "steps": [
    {
      "agent_id": "object-detection-v1"
    }
  ]
}

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

Changes

Changed in 2 of the 3 revisions of this API.6

Aug 24, 20262d003f6f36fe2See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
Aug 18, 2026eef1814ea8154See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the required property to the response with the status
  response-required-property-added

Full history