Personalization and experiments from a non-Kywi frontend
A non-Kywi frontend gets every arm from a headless read and drives personalization and experiments through the `/kywi/*` routes from the Kywi origin.
The losing arms are gone before the response leaves the server — but only on the render path. Pruning is one call, made once the page is about to reach a browser: the arms the visitor did not get are stripped from the document right before it crosses into KywiLayout, so they are not in the HTML. A headless read is a different path. GET /content/by-id/:id, GET /content/:type/:id and GET /content/slug/:slug hand back whatever layout is stored for that content — every arm, unpruned, because nothing on that route resolves a visitor to prune against. So a headless frontend must treat the layout it reads as containing all arms and do its own selection: ask the server which one applies (the routes below), or pin an audience and let a render request do the choosing. What pruning means for a browser visitor is What is public about a personalized page.
Experiments
Three anonymous POST routes. assign and exposure take no site of their own because they never need one: both look the experiment up by its id alone, with no site filter, so the id you already hold selects the right row regardless of which site it belongs to. conversion is different — its signal form has no experiment id to key off, so it takes an optional siteId in the body, falling back to a Host-header match against the deployment's configured sites and only then to the first configured site, so a beacon with no id can still be attributed to the site that fired it.
/api/v1/kywi/experiments/assignNo authThe deterministic variant for a visitor. Same visitor, same experiment, same answer — assignment is a hash, not a stored roll.
// request
{ "experimentId": "e3b1…", "visitorId": "vis-9f21…" }
// response
{ "data": {
"experimentId": "e3b1…",
"variantId": "v-2",
"variantKey": "b",
"fromWinner": false,
"visitorId": "vis-9f21…"
} }/api/v1/kywi/experiments/exposureNo authRecords that the visitor saw their variant. The variant is recomputed
server-side and the client's is never trusted, so the body carries only
experimentId and visitorId. Answers
{ experimentId, variantId, recorded } — recorded is false unless
the experiment is actually running and the visitor is tracked.
/api/v1/kywi/experiments/conversionNo authTwo shapes. { event: { type, url?, formId?, eventName? } } lets
the server match the signal against every experiment's goals and answers with how many
conversions it recorded; { experimentId, goalType } attributes one directly to
the visitor's existing assignment. A body carrying neither is a
VALIDATION_ERROR. Unlike assign and exposure, this
route also accepts a siteId field — resolved body siteId → Host
header → the deployment's first configured site — so a server-side proxy fronting several
sites can attribute each conversion correctly instead of pinning them all to one.
Audiences
/api/v1/kywi/audiencesNo auth{ id, name, label } for audiences that are active and flagged
public — the list a switcher UI needs. The admin GET /api/v1/audiences
returns whole audiences including their condition groups, and is not public.
/api/v1/kywi/audienceNo authPin the visitor to an audience. { audienceId, source } in,
{ audienceId, persisted } out — the pin applies to this response either way,
and persisted reports whether it survives the next request.
{ "data": { "audienceId": "aud-7c…", "persisted": true } }persisted is the field to read rather than assume. source: "switcher" — a visitor choosing an audience by hand — is treated as an essential preference and stored whatever the consent state, because a control the visitor operated must be honoured or its buttons lie. Any other source needs personalization consent; without it you get persisted: false and the pin lasts exactly one page. POST /api/v1/kywi/self-id follows the same split: answers are stored only with consent, the resolved winner is pinned regardless.
curl -X POST "$KYWI/api/v1/kywi/audience" \
-H "Content-Type: application/json" \
-H "Origin: $KYWI" \
-H "Cookie: kywi_visitor=vis-9f21…; kywi_consent={\"personalization\":true}" \
-d '{"audienceId":"aud-7c…","source":"switcher"}'The Origin header must name the Kywi site itself — not the external frontend's own origin — because isTrustedWrite checks it against the request's own origin: a proxy is standing in for a same-origin browser call, so it has to claim that origin on the header.
What any of this means is the Targeting surface: How a visitor ends up in one audience and What consent does to your targeting.