Logo of linkbreakers
← Back to API Reference overview

Workflow Steps

Endpoints for managing workflow steps in Linkbreakers. Workflow steps define the behavior of links, such as redirection destinations and data collection flows.

Shortcut: ⌘K

#The Workflow Step object

Models a node in the Linkbreakers workflow canvas, defining what should occur after a scan (redirects, gates, forms) and how it connects to other steps in the visitor journey.

branches

array<object>

Every exit of this step, with its current destination. This is the vocabulary for connecting the step: pass one of these branch_ids to workflow_steps_connect. An atomic step has exactly one branch, "next". A composite step has one per button, option or range, plus "else" for a condition's fallback. An exit step has none.

canvasPosition

object

Canvas position for React Flow node positioning

childStepIds

array<string>

Child workflow step IDs (steps that this step can transition to, UUID)

createdAt

string (date-time)

When the workflow step was created

eventAction

string (enum)

leads to a next step, not straight out. Records which button the visitor pressed, so use it over SOCIAL_LINKS_PAGE when that choice is worth measuring or when a branch needs to do more than redirect. the common case, not the only one: app stores, docs, booking pages and storefronts all work, and the name is the only thing about it that is social. It is an exit step, so the visitor leaves from here. visitor automatically. It carries no list of destinations, so a page that should offer a choice between two or more places is not this step. Use SOCIAL_LINKS_PAGE when the choices leave for external URLs, or MULTI_LINK when each choice continues into more workflow.

Allowed values
EVENT_ACTION_UNSPECIFIED

Event action not specified

EVENT_ACTION_CLIENT_REDIRECT

Redirect visitors to a destination URL

EVENT_ACTION_LINK_VISIT

Entry step triggered when the link is visited.

EVENT_ACTION_PASSWORD_VERIFY

Require visitors to enter a password before proceeding

EVENT_ACTION_FORM_SUBMIT

Present a data collection form to visitors

EVENT_ACTION_CONTACT_CARD

Generate a vCard (VCF) response with contact information

EVENT_ACTION_MULTI_LINK

A page of buttons where each one continues into more workflow: the button

EVENT_ACTION_VISIT_TYPE_CONDITION

Route visitors based on whether it's a first or returning visit

EVENT_ACTION_COUNTRY_CONDITION

Route visitors based on their country location

EVENT_ACTION_DAY_OF_WEEK_CONDITION

Route visitors based on day of week

EVENT_ACTION_TIME_OF_DAY_CONDITION

Route visitors based on time of day

EVENT_ACTION_DAY_OF_MONTH_CONDITION

Route visitors based on day of month

EVENT_ACTION_SPECIFIC_DATE_CONDITION

Route visitors based on specific calendar dates

EVENT_ACTION_SOCIAL_LINKS_PAGE

A page of buttons that each leave for an external URL. Social profiles are

EVENT_ACTION_DEVICE_TYPE_CONDITION

Route visitors based on device type (e.g. MOBILE, DESKTOP, TABLET)

EVENT_ACTION_DEVICE_PLATFORM_CONDITION

Route visitors based on device platform / operating system (e.g. iOS, Android, macOS)

EVENT_ACTION_DEVICE_BROWSER_CONDITION

Route visitors based on browser family (e.g. Chrome, Safari, Firefox)

EVENT_ACTION_DEVICE_BRAND_CONDITION

Route visitors based on hardware brand (e.g. Apple, Samsung, Google)

EVENT_ACTION_DEVICE_ACTOR_CONDITION

Route visitors based on actor classification (e.g. HUMAN, BOT, AGENT)

EVENT_ACTION_VISITOR_DATA_CONDITION

Route visitors based on their profile data or custom attributes

EVENT_ACTION_THANK_YOU_PAGE

Display a final thank you / completion message (exit step)

EVENT_ACTION_MESSAGE_PAGE

Text with ONE way onward: a single button, or a timer that moves the

id

string

The unique identifier of the workflow step (UUID)

kind

string (enum)

The kind of workflow step (entry, exit, etc.) - read-only, determined by server

Allowed values
KIND_UNSPECIFIED

Workflow step kind not specified

KIND_ENTRY

Entry steps are automatically triggered when a visitor reaches the workflow

KIND_EXIT

Exit steps finalize the workflow (commonly a redirect)

KIND_INTERACTION

Interaction steps require visitor input (forms, passwords, etc.)

KIND_CONDITION

Condition steps evaluate logic and route to different next steps

linkId

string

The link ID this workflow step belongs to (UUID)

nodeType

string (enum)

The node type says how many exits a step has. Whatever the answer, you connect every one of them the same way, with workflow_steps_connect: name the branch, name the step it leads to. Read a step's branches field for its branch ids. Example: a multi-link with 3 buttons has 3 branches, with the buttons' ids. A redirect has one branch, "next". A country condition has one branch per country plus "else". for a condition's fallback. Examples: MULTI_LINK, VISIT_TYPE_CONDITION, COUNTRY_CONDITION, DAY_OF_WEEK_CONDITION, TIME_OF_DAY_CONDITION, DAY_OF_MONTH_CONDITION, SPECIFIC_DATE_CONDITION, DEVICE_*_CONDITION, VISITOR_DATA_CONDITION (THANK_YOU_PAGE, CONTACT_CARD, SOCIAL_LINKS_PAGE, CLIENT_REDIRECT) are atomic but end the journey, so they have no branches at all. Examples: LINK_VISIT, PASSWORD_VERIFY, FORM_SUBMIT, MESSAGE_PAGE

Allowed values
NODE_TYPE_UNSPECIFIED

Workflow step node type not specified

NODE_TYPE_COMPOSITE

Composite steps have one exit per button, option or range, plus "else"

NODE_TYPE_ATOMIC

Atomic steps have exactly one exit, branch id "next". Exit steps

parentStepIds

array<string>

Parent workflow step IDs (steps that can transition into this step, UUID)

payload

object

Workflow step payload - uses oneof for type safety based on EventAction

updatedAt

string (date-time)

When the workflow step was last updated

GET/v1/links/{linkId}/workflow-steps/{id}Requires auth

#Get workflow step details

Retrieves information about a specific workflow step.

#Parameters

path parameters

linkId

stringRequiredpath

The ID of the link (UUID)

id

stringRequiredpath

The ID of the workflow step to retrieve (UUID)

#Response

200

Everything worked as expected.

workflowStep

object

Models a node in the Linkbreakers workflow canvas, defining what should occur after a scan (redirects, gates, forms) and how it connects to other steps in the visitor journey.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

POST/v1/links/{linkId}/workflow-stepsRequires auth

#Create a new workflow step

This endpoint allows users to create a new workflow step for a link. Workflow steps define the behavior of links, such as redirection destinations.

#Parameters

path parameters

linkId

stringRequiredpath

The ID of the link to create the workflow step for (UUID)

#Request body

canvasPosition

object

Canvas position for React Flow node positioning

eventAction

string (enum)

leads to a next step, not straight out. Records which button the visitor pressed, so use it over SOCIAL_LINKS_PAGE when that choice is worth measuring or when a branch needs to do more than redirect. the common case, not the only one: app stores, docs, booking pages and storefronts all work, and the name is the only thing about it that is social. It is an exit step, so the visitor leaves from here. visitor automatically. It carries no list of destinations, so a page that should offer a choice between two or more places is not this step. Use SOCIAL_LINKS_PAGE when the choices leave for external URLs, or MULTI_LINK when each choice continues into more workflow.

Allowed values
EVENT_ACTION_UNSPECIFIED

Event action not specified

EVENT_ACTION_CLIENT_REDIRECT

Redirect visitors to a destination URL

EVENT_ACTION_LINK_VISIT

Entry step triggered when the link is visited.

EVENT_ACTION_PASSWORD_VERIFY

Require visitors to enter a password before proceeding

EVENT_ACTION_FORM_SUBMIT

Present a data collection form to visitors

EVENT_ACTION_CONTACT_CARD

Generate a vCard (VCF) response with contact information

EVENT_ACTION_MULTI_LINK

A page of buttons where each one continues into more workflow: the button

EVENT_ACTION_VISIT_TYPE_CONDITION

Route visitors based on whether it's a first or returning visit

EVENT_ACTION_COUNTRY_CONDITION

Route visitors based on their country location

EVENT_ACTION_DAY_OF_WEEK_CONDITION

Route visitors based on day of week

EVENT_ACTION_TIME_OF_DAY_CONDITION

Route visitors based on time of day

EVENT_ACTION_DAY_OF_MONTH_CONDITION

Route visitors based on day of month

EVENT_ACTION_SPECIFIC_DATE_CONDITION

Route visitors based on specific calendar dates

EVENT_ACTION_SOCIAL_LINKS_PAGE

A page of buttons that each leave for an external URL. Social profiles are

EVENT_ACTION_DEVICE_TYPE_CONDITION

Route visitors based on device type (e.g. MOBILE, DESKTOP, TABLET)

EVENT_ACTION_DEVICE_PLATFORM_CONDITION

Route visitors based on device platform / operating system (e.g. iOS, Android, macOS)

EVENT_ACTION_DEVICE_BROWSER_CONDITION

Route visitors based on browser family (e.g. Chrome, Safari, Firefox)

EVENT_ACTION_DEVICE_BRAND_CONDITION

Route visitors based on hardware brand (e.g. Apple, Samsung, Google)

EVENT_ACTION_DEVICE_ACTOR_CONDITION

Route visitors based on actor classification (e.g. HUMAN, BOT, AGENT)

EVENT_ACTION_VISITOR_DATA_CONDITION

Route visitors based on their profile data or custom attributes

EVENT_ACTION_THANK_YOU_PAGE

Display a final thank you / completion message (exit step)

EVENT_ACTION_MESSAGE_PAGE

Text with ONE way onward: a single button, or a timer that moves the

id

string

Optional ID for the workflow step (UUID; if not provided, will be generated by backend)

payload

object

Workflow step payload - uses oneof for type safety based on EventAction

#Response

200

Everything worked as expected.

workflowStep

object

Models a node in the Linkbreakers workflow canvas, defining what should occur after a scan (redirects, gates, forms) and how it connects to other steps in the visitor journey.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

POST/v1/links/{linkId}/workflow-steps/{stepId}/resolve-collisionsRequires auth

#Resolve step collisions

Pushes overlapping steps away from a given anchor step using iterative radial repulsion. The anchor step stays fixed. Use after adding or moving individual steps to preserve the existing layout.

#Parameters

path parameters

linkId

stringRequiredpath

stepId

stringRequiredpath

#Request body

No structured schema available for this section.

#Response

200

Everything worked as expected.

stepsRepositioned

integer (int32)

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

POST/v1/links/{linkId}/workflow-steps/auto-layoutRequires auth

#Auto-layout workflow

Arranges all workflow steps in a clean left-to-right DAG layout. Useful after building a workflow from scratch.

#Parameters

path parameters

linkId

stringRequiredpath

#Request body

No structured schema available for this section.

#Response

200

Everything worked as expected.

stepsRepositioned

integer (int32)

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

PUT/v1/links/{linkId}/workflow-steps/{stepId}/branches/{branchId}/connectionRequires auth

#Connect one exit of a workflow step to another step

Every workflow step is connected the same way: name the branch it leaves from, and the step it leads to. Atomic steps (redirect, password, form, message page) have exactly one branch, "next". Composite steps (multi-link, conditions) have one branch per button, option or range, plus "else" for a condition's fallback. Exit steps end the journey and have no branches at all. Read a step to see its branches, their ids and their current destinations. Idempotent: connecting a branch to the step it already leads to is a no-op.

#Parameters

path parameters

linkId

stringRequiredpath

The ID of the link (UUID)

stepId

stringRequiredpath

The ID of the step the connection leaves from (UUID)

branchId

stringRequiredpath

Which exit of that step to connect. "next" for atomic steps, or a button id, option id, range id, country code, or "else" for composite steps.

#Request body

nextStepId

string

The ID of the step this branch leads to (UUID)

#Response

200

Everything worked as expected.

disconnectedSteps

array<object>

Steps that nothing can reach now that this connection changed. Empty means the whole workflow is still connected.

unconnectedBranchIds

array<string>

Branches of this step that still lead nowhere, reported without being asked for. Wiring one branch of a condition and forgetting the rest is the most common way a workflow ships broken: the visitor who takes an unwired branch falls through to the fallback URL. Nothing here is unreachable, so a graph-level check would not catch it — only the step itself knows. Empty means every exit of this step leads somewhere.

workflowStep

object

Models a node in the Linkbreakers workflow canvas, defining what should occur after a scan (redirects, gates, forms) and how it connects to other steps in the visitor journey.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

PATCH/v1/links/{linkId}/workflow-steps/{id}Requires auth

#Update a workflow step

Updates an existing workflow step for a link.

#Parameters

path parameters

linkId

stringRequiredpath

The ID of the link (UUID)

id

stringRequiredpath

The ID of the workflow step to update (UUID)

#Request body

canvasPosition

object

Canvas position for React Flow node positioning

payload

object

Workflow step payload - uses oneof for type safety based on EventAction

#Response

200

Everything worked as expected.

workflowStep

object

Models a node in the Linkbreakers workflow canvas, defining what should occur after a scan (redirects, gates, forms) and how it connects to other steps in the visitor journey.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

DELETE/v1/links/{linkId}/workflow-steps/{id}Requires auth

#Delete a workflow step

Removes a workflow step from the link. This operation cannot be undone.

#Parameters

path parameters

linkId

stringRequiredpath

The ID of the link (UUID)

id

stringRequiredpath

The ID of the workflow step to delete (UUID)

#Response

200

Everything worked as expected.

No structured schema available for this section.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

DELETE/v1/links/{linkId}/workflow-steps/{stepId}/branches/{branchId}/connectionRequires auth

#Clear one exit of a workflow step

Leaves the branch with no destination. Clearing a branch that is already clear succeeds. See ConnectStep for what a branch id is.

#Parameters

path parameters

linkId

stringRequiredpath

The ID of the link (UUID)

stepId

stringRequiredpath

The ID of the step the connection leaves from (UUID)

branchId

stringRequiredpath

Which exit of that step to clear. See ConnectWorkflowStepRequest.branch_id.

#Response

200

Everything worked as expected.

disconnectedSteps

array<object>

Steps that nothing can reach now that this connection was cleared

unconnectedBranchIds

array<string>

Branches of this step that lead nowhere, including the one just cleared

workflowStep

object

Models a node in the Linkbreakers workflow canvas, defining what should occur after a scan (redirects, gates, forms) and how it connects to other steps in the visitor journey.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.