ap_add_step
ap_add_stepAdd a new step to a flow. Optionally configure it in the same call by providing input/auth/sourceCode. Prefer PIECE actions and inline formula expressions over CODE.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| auth | No | Connection externalId from ap_list_connections. Pass the plain id, not a template. | |
| input | No | For PIECE/CODE steps: input config (key-value pairs). Reference a prior step's output with {{stepName['output'].field}} (output is nested under ['output'], e.g. {{trigger['output'].body.email}}, {{send_email['output'].id}}). For a continue-on-failure step's error, use {{stepName['error'].message}}. | |
| flowId | Yes | The id of the flow | |
| stepType | Yes | The type of step to add. Prefer PIECE over CODE — only use CODE when no piece fits and the logic can't be done with an inline formula expression (in a free-text/value input) or a router condition. | |
| loopItems | No | For LOOP steps: expression for items to iterate (e.g. "{{step_1['output'].items}}"). | |
| pieceName | No | For PIECE steps: the piece name (e.g. "@activepieces/piece-gmail"). Use ap_research_pieces to get valid values. | |
| actionName | No | For PIECE steps: the action name within the piece. Use ap_research_pieces with includeActions=true to get valid values. | |
| sourceCode | No | For CODE steps: JavaScript/TypeScript source. Must export a `code` function. | |
| branchIndex | No | Branch index (required when stepLocationRelativeToParent is INSIDE_BRANCH) | |
| displayName | Yes | Display name for the step | |
| packageJson | No | For CODE steps: package.json as JSON string. Defaults to "{}". | |
| parentStepName | Yes | The step name to insert after/into (e.g. "trigger", "step_1"). Use ap_flow_structure to get valid values. | |
| retryOnFailure | No | For CODE/PIECE steps: whether to retry this step on failure. Defaults to false. | |
| continueOnFailure | No | For CODE/PIECE steps: set true on the step that can fail (the one whose failure you want to react to), NOT on the recovery step. Defaults to false. When true the flow keeps running on failure and the step gains On success / On failure branches — add handler steps into them with stepLocationRelativeToParent INSIDE_ON_SUCCESS_BRANCH / INSIDE_ON_FAILURE_BRANCH and parentStepName = this step. | |
| stepLocationRelativeToParent | Yes | Where to place the step: AFTER = after the parent, INSIDE_LOOP = first action inside a loop, INSIDE_BRANCH = first action inside a router branch, INSIDE_ON_SUCCESS_BRANCH / INSIDE_ON_FAILURE_BRANCH = first action inside the On success / On failure branch of a continue-on-failure step (set continueOnFailure on the parent first). |