API Reference

Create Workflow Step

post
https://api.whippy.co/v1/workflows//steps

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. Default responses are summary-sized (no schemas).
  2. Call listWorkflowStepTypes again with detail=full and id=<option_id>
    when you need input/output field schemas for configuration.
  3. Call this endpoint with the template fields (name, type, data,
    plus previous_step_id or previous_step_alias / parent_step_id or
    parent_step_alias / child_role as needed).
    For linear chains, use the returned data.id as the next
    previous_step_id — no list call needed. For splits/branches, pass
    include=steps to get the full draft step list in the same response.
  4. Call updateWorkflowStep to fill input mappings / credentials.
  5. Call testWorkflowStep to verify behavior.
  6. 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).
  • previous_step_alias / parent_step_alias are alternatives to the UUID
    fields and resolve against the same editable steps. Providing both an id
    and its alias pair returns 422. An unknown alias returns 404.
  • 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

Query Params
string
enum

When steps, also return the full editable draft step list as a top-level
steps array (same shape as each listWorkflowSteps item). Use after
creating forks (split_in_paths / condition_path) so you can wire
branch successors via predecessor links (previous_step_id /
previous_step_alias) without a separate list call. parent_step_id /
parent_step_alias remain for nesting under loop / wait_for only. Omit
for linear chains — chain on data.id instead. Default response is
unchanged (data only).

Allowed:
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. Copy step_template.data from
listWorkflowStepTypes. Keep identity fields such as subtype,
app_id, app_version_id, and credential_id at the top level of
data; put operation fields inside data.operation.perform.

For example, schedule configuration belongs at
data.operation.perform.cron and
data.operation.perform.timezone. Never invent a mapping path:
test the upstream step and copy its documented output path. Action
results commonly use ${alias.output.data.field}; trigger values
may use ${alias.input.field}. Never use {{steps.alias.field}}.

string

Optional step description

metadata
object

Step metadata

string
required
length between 1 and 255

Step display name

string
length between 1 and 255

Alternative to parent_step_id: alias of the parent loop / wait_for step on the editable draft.

uuid

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

string
length between 1 and 255

Alternative to previous_step_id: alias of the previous step on the editable draft (e.g. "webhook"). Prefer this when chaining without listing step UUIDs.

uuid

Previous step in the linear chain. Required for non-trigger steps. Mutually exclusive with previous_step_alias. 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

Updated 27 days ago

Did this page help you?
Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 27 days ago

Did this page help you?