Flows API

Create, update, publish, and archive interactive flows. All endpoints require JWT authentication via the session_token cookie or Authorization: Bearer <token> header.

List Flows

curl https://api.breakground.io/api/flows?status=published&page=1&limit=20 \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Param	Type	Default	Description
status	string	—	Filter by status: DRAFT, PUBLISHED, SCHEDULED, ARCHIVED
template	string	—	Filter by template: PRODUCT_TOUR, FEATURE_WALKTHROUGH, INTERACTIVE_DEMO, ANNOUNCEMENT_SEQUENCE, CUSTOM
siteId	uuid	—	Filter by site
search	string	—	Search flows by name
page	string	1	Page number
limit	string	20	Results per page

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Onboarding Walkthrough",
      "template": "FEATURE_WALKTHROUGH",
      "status": "PUBLISHED",
      "tenantId": "t1-...",
      "siteId": "site-...",
      "createdAt": "2026-01-10T08:00:00.000Z",
      "updatedAt": "2026-03-01T12:30:00.000Z",
      "_count": { "steps": 5 }
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

Create Flow

curl -X POST https://api.breakground.io/api/flows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Feature Tour",
    "siteId": "550e8400-e29b-41d4-a716-446655440000",
    "template": "FEATURE_WALKTHROUGH",
    "description": "Introduces the new reporting dashboard",
    "trigger": {
      "type": "URL_MATCH",
      "config": { "matchType": "contains", "pattern": "/reports" }
    },
    "steps": [
      { "type": "TOOLTIP", "order": 0, "targetSelector": "#report-btn", "content": { "title": "Click here" } }
    ]
  }'

Required fields: name, siteId, template. Optional: description, settings, trigger, steps, audienceId, scheduledAt, expiresAt.

The trigger field accepts a single object with type (URL_MATCH or MANUAL) and a type-specific config. Step type values must come from the FlowStepType enum (TOOLTIP, MODAL, BEACON, BANNER, SLIDEOUT, VIDEO, FORM, CLICK, NAVIGATE, WAIT, INPUT, SCROLL).

Get Flow

curl https://api.breakground.io/api/flows/:id \
  -H "Authorization: Bearer $TOKEN"

Returns the full flow definition including steps, triggers, and conditions.

Update Flow

curl -X PATCH https://api.breakground.io/api/flows/:id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated Tour Name", "description": "Revised description" }'

All fields are optional. Only provided fields are modified (partial update).

Delete (Archive) Flow

curl -X DELETE https://api.breakground.io/api/flows/:id \
  -H "Authorization: Bearer $TOKEN"

This is a soft delete: the flow's status is set to ARCHIVED and it is hidden from default list views, but the record and its steps are preserved. Archived flows can be restored by updating the status back to DRAFT or PUBLISHED via the Update Flow endpoint.

Pass ?disableDependents=true to also disable any content that depends on this flow (e.g. journeys that reference it).

Publish Flow

curl -X POST https://api.breakground.io/api/flows/:id/publish \
  -H "Authorization: Bearer $TOKEN"

Transitions a draft flow to published status, making it available to end users via the SDK.

Archive Flow

curl -X POST https://api.breakground.io/api/flows/:id/archive \
  -H "Authorization: Bearer $TOKEN"

Moves a flow to archived status. Archived flows are no longer served by the SDK but can be restored.

Restore Flow

curl -X POST https://api.breakground.io/api/flows/:id/restore \
  -H "Authorization: Bearer $TOKEN"

Restores an archived flow back to draft status.

Flow Steps

List Steps

curl https://api.breakground.io/api/flows/:id/steps \
  -H "Authorization: Bearer $TOKEN"

Create Step

curl -X POST https://api.breakground.io/api/flows/:id/steps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "TOOLTIP", "order": 0, "targetSelector": "#btn", "content": { "title": "Click here" } }'

Get Step

curl https://api.breakground.io/api/flows/:id/steps/:stepId \
  -H "Authorization: Bearer $TOKEN"

Update Step

curl -X PATCH https://api.breakground.io/api/flows/:id/steps/:stepId \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": { "title": "Updated title" } }'

Delete Step

curl -X DELETE https://api.breakground.io/api/flows/:id/steps/:stepId \
  -H "Authorization: Bearer $TOKEN"

Reorder Steps

curl -X POST https://api.breakground.io/api/flows/:id/steps/reorder \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stepIds": ["step_1", "step_3", "step_2"] }'

Reorders steps within a flow. The stepIds array defines the new order.