🚧

This endpoint is in beta and subject to change.

A beta revision header (2026-07-15.pre) is required to use our beta APIs. Klaviyo APIs in beta are not intended for use in production. See our versioning and deprecation policy for more information.

Insert a new action into an existing flow.

Choose exactly one placement mechanism:

• Use anchor-action to insert after an existing action on one of its outgoing
  links. The selected anchor link must equal the new action's temporary_id,
  and the new action definition must not include links. Use an anchor to append
  to a path or insert into an empty conditional or multi-branch path.
• Use definition.links.next to insert before an existing downstream action.
  The server reconnects that action after the new one.
• Use relationships.flow only to insert the first action into a trigger-only
  flow whose initialized start path has no actions.

anchor-action, links on the new definition, and relationships.flow are
mutually exclusive.

Standard linear actions, standard WhatsApp actions, and multi-branch splits are
supported. Conditional splits, trigger splits, action-output splits, A/B tests,
content experiments, and Automated Conversations actions cannot be inserted.

Communication actions are created in Draft and may need content or template
configuration before activation. Always-live timing and logic actions require
allow_live_action: true when inserted into a live flow and can immediately
affect profiles already progressing through that flow.

A 201 response confirms that the action was created. The action may take a
short time to become available to flow execution. This endpoint is not
idempotent: retrying after an unknown result can create a duplicate action,
and temporary_id is not an idempotency key.

Responses use persisted values. These can include server-generated multi-branch
branch IDs, omission of the request-only joined marker, generated message or
webhook defaults, and a cloned email template ID that differs from the supplied
template ID. Invalid placement, unavailable anchors, and missing live-action
opt-in return standard JSON:API errors with field pointers.

Rate limits:
Burst: 3/s
Steady: 60/m

Scopes:
flows:write

OpenAPI Spec