# Personalization and experiments from a non-Kywi frontend

URL: https://kywi-docs-production.up.railway.app/integrating/personalization-and-experiments-from-a-non-kywi-frontend
Type: docPage

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](/targeting/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.

The 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…" } }

## 200 OK

Records 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.

Two 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.

## The cookie wins over the visitorId you send

Every runtime route resolves the visitor from the `kywi_visitor` cookie first and falls back to the body's `visitorId` only when there is none. Core's middleware is what mints and forwards that cookie, and a frontend that does not run the middleware has neither — so send `visitorId` on every call and keep it stable yourself, or assignments will not be. And without personalization consent the server substitutes a throwaway id: the call still answers with a variant, but `recorded` comes back false and nothing is stored.

## Audiences

`{ 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.

Pin 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.

## 200 OK

`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.

## The two write routes refuse a request that cannot say where it came from

`/kywi/audience` and `/kywi/self-id` both demand positive same-origin evidence — a matching `Origin`, failing that a `Sec-Fetch-Site` of `same-origin`, `same-site` or `none`, failing that a same-origin `Referer`. Nothing at all is `403 Cross-origin request rejected`, and a site that issues a `kywi_csrf` cookie also requires the matching double-submit token. These are visitor-facing routes where the cookie *is* the credential, so this is the only thing standing between them and a forged submit.

Which means an external frontend proxies them from its own server, forwarding the visitor's cookies and an `Origin` naming the Kywi site. Nothing here emits CORS headers, so a browser on another origin was never going to read the response anyway — see [Topologies that work, and the cross-origin wall](/integrating/topologies-that-work--and-the-cross-origin-wall/).

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](/targeting/how-a-visitor-ends-up-in-one-audience/) and [What consent does to your targeting](/targeting/what-consent-does-to-your-targeting/).
