Create Workflow Step

Creates one step on the workflow draft without requiring a full-graph sync.
Prefer this over any full draft replace when building or editing workflows
as an agent.

Agent workflow

  1. Call listWorkflowStepTypes (optionally with workflow_id +
    parent_step_id) to discover valid options and copy a create-ready
    step_template.
  2. Call this endpoint with the template fields (name, type, data,
    plus previous_step_id / parent_step_id / child_role as needed).
  3. Call updateWorkflowStep to fill input mappings / credentials.
  4. Call testWorkflowStep to verify behavior.
  5. Call publishWorkflow when the draft is ready.

Validation

  • Ensures the workflow exists and belongs to the authenticated organization.
  • Ensures previous_step_id / parent_step_id (when provided) reference
    steps on the editable draft (or published current version when no draft
    exists yet).
  • Enforces graph placement (trigger only at root, allowed next steps,
    nested child roles under loop / wait_for).
  • Uses optimistic concurrency against the draft (or published version when
    creating a draft). Concurrent races return 409 stale_draft.
  • Full step config completeness (required fields per action/app) is
    validated on publish, not on create — incomplete data is allowed
    while the agent is still configuring the step.

If no draft exists yet, creates one from the published version (step IDs
may remap for links that pointed at published steps).

OAuth callers require the workflows:update scope (and matching workspace
permission). API key callers are authorized by organization membership.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
uuid
required

Workflow ID

Body Params

Step to create

string
length between 1 and 255

Stable step alias (defaults from name when omitted)

string
enum

Child role when nesting under wait_for

Allowed:
data
object

Step configuration / input mapping. Start from step_template.data from listWorkflowStepTypes (includes subtype, app_id, app_version_id, operation shell, etc.).

string

Optional step description

metadata
object

Step metadata

string
required
length between 1 and 255

Step display name

uuid

Parent step when nesting under loop / wait_for. Must be an id from listWorkflowSteps on this workflow.

uuid

Previous step in the linear chain. Required for non-trigger steps. Must be an id from listWorkflowSteps on this workflow.

sample_input
object

Sample input used when testing

sample_output
object

Sample output from the last successful test

string
enum
required

Step type. Prefer values from listWorkflowStepTypes / step_template.type.

Responses

Callback
Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json