SDK Endpoints

All SDK endpoints are prefixed with /api/v1/sdk/ and require API key authentication via the X-API-Key header (or _apiKey in the request body for sendBeacon fallback). See Authentication for details.

For detailed event payload examples and integration workflows, see the Event Ingestion Guide.

---

GET /api/v1/sdk/config

Returns the company configuration for SDK initialization.

Response:

{
  "data": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Organization",
    "settings": {},
    "plan": "PROFESSIONAL",
    "features": {
      "tooltips": true,
      "beacons": true,
      "surveys": true,
      "journeys": true
    },
    "defaultLocale": "en-US"
  }
}

curl https://api.breakground.io/api/v1/sdk/config \
  -H "X-API-Key: wfx_your_api_key_here"

---

POST /api/v1/sdk/events

Ingests a batch of events. Events are persisted synchronously, then processed asynchronously into analytics tables. Returns HTTP 202 Accepted.

Request:

{
  "events": [
    {
      "type": "PAGE_VIEW",
      "userId": "user-42",
      "url": "https://app.example.com/dashboard",
      "timestamp": "2026-03-18T14:30:00.000Z",
      "properties": {
        "title": "Main Dashboard",
        "referrer": "https://app.example.com/login"
      }
    }
  ]
}

Response (202):

{
  "data": {
    "accepted": 1,
    "correlationId": "req-abc123"
  }
}

curl -X POST https://api.breakground.io/api/v1/sdk/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wfx_your_api_key_here" \
  -d '{"events":[{"type":"PAGE_VIEW","userId":"user-42","url":"https://app.example.com"}]}'

---

POST /api/v1/sdk/identify

Identifies an end user. Creates the user record if it does not exist, or updates traits if it does.

Request:

{
  "userId": "user-42",
  "role": "admin",
  "traits": {
    "name": "Jane Doe",
    "plan": "professional",
    "company": "Acme Corp"
  }
}

userId is required (min 1 character). role and traits are optional.

Response:

{
  "data": {
    "userId": "user-42",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

The id field is the internal UUID assigned to this end user.

curl -X POST https://api.breakground.io/api/v1/sdk/identify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wfx_your_api_key_here" \
  -d '{"userId":"user-42","traits":{"name":"Jane Doe","plan":"professional"}}'

---

GET /api/v1/sdk/flows

Returns all published flows for this company.

Query Parameters:

Parameter	Type	Description
userId	string	Optional. Filters out flows the user has already completed.

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Onboarding Tour",
      "template": "FEATURE_WALKTHROUGH",
      "description": "Welcome tour for new users",
      "status": "PUBLISHED",
      "settings": {},
      "steps": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "type": "TOOLTIP",
          "title": "Welcome!",
          "content": {},
          "selector": "#dashboard-header",
          "url": null,
          "position": "AUTO",
          "settings": {},
          "order": 0
        }
      ],
      "triggers": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440002",
          "type": "URL_MATCH",
          "config": { "matchType": "contains", "pattern": "/dashboard" }
        }
      ]
    }
  ]
}

curl "https://api.breakground.io/api/v1/sdk/flows?userId=user-42" \
  -H "X-API-Key: wfx_your_api_key_here"

---

GET /api/v1/sdk/content-items

Returns all published content entities (tooltips, beacons, surveys, task lists, announcements, self-help widgets, NPS, and journeys). Results are filtered by the company's plan features.

Responses are cached for 30 seconds per company.

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "tooltip",
      "name": "Feature Highlight",
      "audienceId": "660e8400-e29b-41d4-a716-446655440001",
      "audienceRuleTree": null,
      "config": {
        "selector": "#new-feature-btn",
        "content": "Click here to try the new feature"
      }
    }
  ]
}

Content types returned by this endpoint: tooltip, beacon, survey, task_list, announcement, self_help, nps. (Journeys are fetched separately via the journey enroll/progress endpoints below.)

curl https://api.breakground.io/api/v1/sdk/content-items \
  -H "X-API-Key: wfx_your_api_key_here"

---

GET /api/v1/sdk/experiments

Returns experiment variant assignments for a user. Assignment is deterministic based on a hash of userId:experimentId.

Query Parameters:

Parameter	Type	Description
userId	string	Required. The external user ID.

Response:

[
  {
    "experimentId": "550e8400-e29b-41d4-a716-446655440000",
    "variantId": "variant-b",
    "variantConfig": {
      "flowId": "660e8400-e29b-41d4-a716-446655440001"
    }
  }
]

curl "https://api.breakground.io/api/v1/sdk/experiments?userId=user-42" \
  -H "X-API-Key: wfx_your_api_key_here"

---

GET /api/v1/sdk/content

Returns i18n translations for a single content item.

Query Parameters:

Parameter	Type	Description
locale	string	Required. Locale code (e.g., en-US).
contentType	string	Required. Content type (e.g., tooltip).
contentId	string	Required. Content item UUID.

Response:

{
  "locale": "es",
  "contentType": "tooltip",
  "contentId": "550e8400-e29b-41d4-a716-446655440000",
  "translations": {
    "title": "Bienvenido",
    "body": "Haga clic aqui para comenzar"
  }
}

curl "https://api.breakground.io/api/v1/sdk/content?locale=es&contentType=tooltip&contentId=550e8400-..." \
  -H "X-API-Key: wfx_your_api_key_here"

Batch Translations

GET /api/v1/sdk/content-translations

Fetch translations for up to 50 content items in a single request.

Query Parameters:

Parameter	Type	Description
locale	string	Required. Locale code.
items	string	Required. JSON array of {contentType, contentId} objects (max 50).

Response:

{
  "bundles": [
    {
      "locale": "es",
      "contentType": "tooltip",
      "contentId": "550e8400-...",
      "translations": { "title": "Bienvenido" }
    }
  ]
}

---

POST /api/v1/sdk/journeys/:id/enroll

Enrolls a user in a journey.

Request:

{
  "userId": "user-42"
}

Provide either userId (the external ID of an identified user) or anonymousId (a stable identifier for an unidentified visitor). At least one is required. anonymousId is only accepted on journeys with allowAnonymous: true.

Response:

Returns the enrollment with the current node and total nodes.

curl -X POST https://api.breakground.io/api/v1/sdk/journeys/550e8400-.../enroll \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wfx_your_api_key_here" \
  -d '{"anonymousId":"anon-42"}'

---

POST /api/v1/sdk/journeys/:id/progress

Advances a user to the next node in a journey.

Request:

{
  "userId": "user-42",
  "currentNodeId": "660e8400-e29b-41d4-a716-446655440001"
}

currentNodeId is required. Pass either userId or anonymousId (matching the value used at enrollment).

Response:

Returns the updated enrollment with a completed boolean indicating whether the journey is finished.

curl -X POST https://api.breakground.io/api/v1/sdk/journeys/550e8400-.../progress \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wfx_your_api_key_here" \
  -d '{"userId":"user-42","currentNodeId":"660e8400-..."}'

---

POST /api/v1/sdk/surveys/:id/responses

Submits a survey response. Returns HTTP 201 Created.

Request:

{
  "endUserId": "550e8400-e29b-41d4-a716-446655440000",
  "answers": {
    "q1": "Very satisfied",
    "q2": 5,
    "q3": ["Feature A", "Feature C"]
  }
}

endUserId is the internal UUID returned from the identify endpoint. answers can be any JSON structure matching the survey's question schema.

curl -X POST https://api.breakground.io/api/v1/sdk/surveys/770e8400-.../responses \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wfx_your_api_key_here" \
  -d '{"endUserId":"550e8400-...","answers":{"q1":"Very satisfied","q2":5}}'