Developer

API reference

Two public HTTP endpoints power every Variantix experiment. Visitors hit the redirect endpoint to be assigned a variant and stick to it across visits; your app posts goal completions to the tracking endpoint to attribute conversions back to the same variant. Neither endpoint requires authentication.

GET

/r/[experimentId]

Resolves a running experiment and 302-redirects the visitor to the chosen variant’s URL. Returning visitors stick to the same variant via a per-experiment cookie; freshly-assigned visitors get the cookie set in the redirect response. Completed experiments always serve the winner.

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.

Variantix recommends running experiments for at least ~1 month for stable results; the cookie TTL matches that cadence, so visitors stay pinned to the same variant across the recommended floor and beyond.

Example requestbash
curl -i https://variantix.app/r/exp_01HMZ8C5W3X4Y9QAB
Example response (302 + Set-Cookie on a fresh assignment)http
HTTP/1.1 302 Found
Location: https://example.com/variant-b
Set-Cookie: polsia_exp_exp_01HMZ8C5W3X4Y9QAB=v_01HMZ...; 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, or completed without a winner; or not fewer than 3 variants attached to a running experiment.
  • 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 the visitor was previously assigned to. No authentication — attribution comes from the sticky cookie set by GET /r/[experimentId] in the same browser session. Successful and replayed posts both return 204 with no body.

URL pattern
https://<host>/api/track
Method
POST
Headers
Content-Type: application/json
Body
experimentIdstring — the experiment id from /r/[id].
goalTypeenum — one of SIGNUP_CLICK, FORM_SUBMIT, CTA_CLICK, PURCHASE.
Pre-condition
The visitor must have already hit GET /r/[experimentId] in this browser session, so the polsia_exp_<experimentId> sticky-assignment cookie is present.
Body shapejson
{
  "experimentId": "exp_01HMZ8C5W3X4Y9QAB",
  "goalType": "SIGNUP_CLICK"
}
Example requestbash
curl -i -X POST https://variantix.app/api/track \
  -H 'Content-Type: application/json' \
  --cookie 'polsia_exp_exp_01HMZ8C5W3X4Y9QAB=v_01HMZ...' \
  -d '{"experimentId":"exp_01HMZ8C5W3X4Y9QAB","goalType":"SIGNUP_CLICK"}'

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
    Sticky cookie missing, experiment missing / non-running / non-completed, cookie pointing at a variant that isn’t attached to the experiment, or (for completed experiments) the cookie doesn’t match the configured winner.
  • 500
    Unexpected server error.