Skip to content
Ttoolab Ttoolab Ttoolab Docs

SDK Endpoints

These endpoints are called by the Ttoolab pixel in the browser. They are the public HTTP interface for experimentation and event collection.

Base URL: https://sdk.ttoolab.com

GET /sdk/bootstrap

Section titled “GET /sdk/bootstrap”

Fetches experiment assignments, variant changes, surveys, and integration settings for the current page.

Query parameters

Section titled “Query parameters”

| Parameter | Required | Description | | :-------- | :------- | :---------- | | projectKey | Yes | Your project’s public key | | anonymousId | Yes | Visitor anonymous ID (UUID format) | | url | No | Current page URL (used for URL rule matching) |

Example request

Section titled “Example request”
Terminal window
curl "https://sdk.ttoolab.com/sdk/bootstrap?projectKey=PROJECT_KEY&anonymousId=550e8400-e29b-41d4-a716-446655440000&url=https%3A%2F%2Fexample.com%2Fpricing"

Example response

Section titled “Example response”
{
  "projectKey": "PROJECT_KEY",
  "anonymousId": "550e8400-e29b-41d4-a716-446655440000",
  "version": "2025-06-09T12:00:00.000Z",
  "fetchedAt": "2025-06-09T12:00:01.000Z",
  "hasActiveExperiments": true,
  "assignments": [
    {
      "experimentKey": "hero-cta-test",
      "experimentId": "hero-cta-test",
      "experimentName": "Hero CTA Test",
      "variantKey": "variant-b",
      "variantId": "variant-b",
      "variantName": "Variant B",
      "isControl": false
    }
  ],
  "experiments": [
    {
      "experimentKey": "hero-cta-test",
      "experimentId": "hero-cta-test",
      "status": "running",
      "variant": {
        "key": "variant-b",
        "changes": [
          {
            "selector": "#hero-cta",
            "operation": "set_text",
            "value": "Get started free",
            "orderIndex": 0
          }
        ]
      },
      "goals": []
    }
  ],
  "integrations": {
    "googleAnalytics": {
      "enabled": true,
      "gtmEventsEnabled": true
    },
    "clarity": {
      "enabled": false
    }
  }
}

Notes

Section titled “Notes”
  • Returns an empty blob when no experiments match the URL.
  • Response is not cached (Cache-Control: private, no-store).

POST /sdk/event

Section titled “POST /sdk/event”

Records an exposure or custom conversion event.

Request body

Section titled “Request body”

| Field | Type | Required | Description | | :---- | :--- | :------- | :---------- | | projectKey | string | Yes | Project public key | | anonymousId | string | Yes | Visitor anonymous ID | | eventName | string | Yes | Event name (e.g. $exposure, purchase) | | payload | object | No | Custom event properties | | url | string | No | Current page URL | | referrer | string | No | Document referrer | | userAgent | string | No | Browser user agent | | assignments | array | Yes | Active experiment assignments | | createdAt | string | No | ISO 8601 timestamp |

Example request

Section titled “Example request”
Terminal window
curl -X POST "https://sdk.ttoolab.com/sdk/event" \
  -H "Content-Type: application/json" \
  -d '{
    "projectKey": "PROJECT_KEY",
    "anonymousId": "550e8400-e29b-41d4-a716-446655440000",
    "eventName": "purchase",
    "payload": { "revenue": 99.90, "order_id": "ORD-12345" },
    "url": "https://example.com/checkout/success",
    "referrer": "https://example.com/checkout",
    "userAgent": "Mozilla/5.0",
    "assignments": [
      {
        "experimentKey": "hero-cta-test",
        "experimentId": "hero-cta-test",
        "variantKey": "variant-b",
        "variantId": "variant-b",
        "isControl": false
      }
    ],
    "createdAt": "2025-06-09T12:00:05.000Z"
  }'

Example response

Section titled “Example response”
{ "success": true }

POST /sdk/survey

Section titled “POST /sdk/survey”

Records CES survey lifecycle events and responses.

Survey event types

Section titled “Survey event types”
  • shown
  • accepted
  • dismissed
  • completed

GET /sdk/survey-preview

Section titled “GET /sdk/survey-preview”

Loads a survey preview configuration for dashboard preview mode. Requires a preview token query parameter.

GET /health

Section titled “GET /health”

Health check endpoint.

Example response

Section titled “Example response”
{
  "ok": true,
  "service": "ttoolab-worker",
  "kv": true
}

Static assets

Section titled “Static assets”

| Asset | URL | | :---- | :— | | Minified SDK | https://sdk.ttoolab.com/ttoolab.min.js | | Full SDK | https://sdk.ttoolab.com/ttoolab.js |

Load with optional project key:

<script async src="https://sdk.ttoolab.com/ttoolab.min.js?project=PROJECT_KEY"></script>

Possible errors

Section titled “Possible errors”

See Errors for HTTP status codes and error messages.

Next steps

Section titled “Next steps”