Developer

API reference

The current browser loader calls the public assignment endpoint and posts matching goal events. Copy the experiment-specific loader from the running experiment's detail page; neither endpoint requires authentication.

Browser loader

The active experiment detail page gives you the full <script> tag with crossorigin="anonymous", its id, and selected goal. It loads from /api/variantix.js, sends the visitor through /r/[experimentId], stores the assignment token in the browser session, and exposes window.variantix.track() for the customer site to call after the selected goal succeeds. Install it in the tested page's <head>; allow the Variantix origin in the customer site's script-src and connect-src policies when CSP is enabled. The loader uses a CORS-enabled script request and sends its goal with a CORS-simple text/plain keepalive request.

GET

/r/[experimentId]

Resolves a running experiment and 302-redirects the visitor to the weighted variant URL. A first assignment records an impression and sets per-experiment sticky cookies. The redirect also carries an opaque assignment token for the customer-site loader to attribute a later cross-origin goal event. Returning visitors keep the same assigned variant. Completed experiments serve the winner only after rollout deploys it.

URL pattern
https://<host>/r/<experimentId>
Method
GET
Path param
experimentId

The experiment’s unique identifier (string).

Authentication
None — the endpoint is intentionally public.
Sticky cookie
polsia_exp_<experimentId> — httpOnly, SameSite=Lax, 30-day TTL, Secure in production. Set on a fresh assignment; read on every subsequent hit to pin the visitor to the same variant.

Reliable tests need enough observations, and gathering them takes time. One month may be enough to run some tests but may not provide enough evidence for a confident conclusion; up to three months can be a useful testing runway, not a required wait, purchase, or guarantee. The sticky assignment lasts 30 days to keep a visitor on the same variant; that cookie lifetime does not set the test duration.

Example requestbash
curl -i https://YOUR_VARIANTIX_ORIGIN/r/<experimentId>
Example response (302 + Set-Cookie on a fresh assignment)http
HTTP/1.1 302 Found
Location: https://YOUR_TESTED_SITE/variant-b?variantix_assignment=<assignment-token>
Set-Cookie: polsia_exp_<experimentId>=<variantId>; Path=/; Max-Age=2592000; HttpOnly; SameSite=Lax; Secure
Set-Cookie: polsia_assignment_<experimentId>=<assignment-token>; Path=/; Max-Age=2592000; HttpOnly; SameSite=Lax; Secure

Status codes

  • 302
    Redirects to the chosen variant’s URL. Sets the sticky cookie when the visitor was just assigned.
  • 404
    Experiment missing, paused, draft, stopped, completed without a deployed winner, or a running experiment without 2–4 attached variants.
  • 410
    Experiment is running but every variant has zero weight, so no traffic can be served.
  • 500
    Unexpected server error.
POST

/api/track

Records a conversion against the variant from a previous assignment. The browser loader sends an assignmentToken returned by GET /r/[experimentId], so it works across the customer site and Variantix origins. Same-origin callers may instead send the matching sticky cookie. Successful and recent replay posts return 204 with no body.

URL pattern
https://<host>/api/track
Method
POST
Headers
Content-Type: text/plain (CORS-simple browser POST)
Body
experimentIdstring — the experiment id from /r/[id].
goalTypeenum — one of SIGNUP_CLICK, FORM_SUBMIT, CTA_CLICK, PURCHASE.
assignmentTokenstring — returned on the /r/[id] redirect and required for cross-origin browser tracking. Same-origin callers may use the sticky assignment cookie instead.
Pre-condition
The visitor must have already hit GET /r/[experimentId]. The browser loader uses the returned assignmentToken; same-origin callers may use the polsia_exp_<experimentId> sticky-assignment cookie.
Body shapejson
{
  "experimentId": "<experimentId>",
  "goalType": "SIGNUP_CLICK",
  "assignmentToken": "<assignment-token>"
}
Example requestbash
curl -i -X POST https://YOUR_VARIANTIX_ORIGIN/api/track \
  -H 'Content-Type: text/plain' \
  -d '{"experimentId":"<experimentId>","goalType":"SIGNUP_CLICK","assignmentToken":"<assignment-token>"}'

Status codes

  • 204
    Conversion recorded — or replayed within the dedup window so a retried POST is idempotent from the caller’s perspective.
  • 400
    Body is not JSON or fails validation. Response shape: { errors: { field: "message" } }.
  • 404
    Valid assignment token or same-origin sticky cookie missing; experiment is not running or serving a deployed winner; or the assignment does not match a variant attached to the experiment.
  • 500
    Unexpected server error.