Experiments

Client-facing A/B experiment surface: fetch the signed-in user's sticky variant and record an exposure when they actually see it. Both calls require a client session (X-Api-Key + session bearer). Defining experiments and reading results is on the admin surface. See the Experiments guide for the end-to-end flow.

Endpoints

GET /client/experiments/:key/assignment

Returns the user's variant for the experiment. The assignment is sticky — the first call buckets the user (deterministic hash of user_id + experiment_key, weighted by the variant weights) and persists it; every later call returns that same variant, even after the experiment is re-weighted. Only active experiments create new assignments; a paused or ended experiment still serves an existing assignment so in-flight users keep their bucket.

Response 200

{ "data": { "experiment_key": "checkout_button_v2", "variant": "green" } }

Errors

• 404 EXPERIMENT_NOT_FOUND — no experiment with that key.
• 409 EXPERIMENT_INACTIVE — the user has no assignment yet and the experiment isn't active. error.details.status carries the current status.
• 422 NO_VALID_VARIANTS — the experiment has no assignable (positive-weight) variants.
• 500 ASSIGNMENT_FAILED.

Try it:

curl -X GET 'https://api.amba.dev/v1/client/experiments/checkout_button_v2/assignment'

Curl:

curl -X GET '${BASE_URL}/client/experiments/checkout_button_v2/assignment' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/experiments/:key/exposure

Record an exposure — the analytics signal that the user was actually shown the variant (vs. merely assigned). Append-only: each call inserts a row. The caller must already have an assignment (call assignment first). Not gated on status — recording a late exposure for a paused/ended experiment is a legitimate signal.

Request

An empty or absent body is fine — the exposure is recorded against the user's current assignment.

Response 201

{
  "data": {
    "id": "…",
    "experiment_id": "…",
    "app_user_id": "…",
    "variant": "green",
    "created_at": "…"
  }
}

Errors

• 400 INVALID_JSON — body present but not valid JSON.
• 400 INVALID_VARIANT — variant present but not a non-empty string.
• 404 EXPERIMENT_NOT_FOUND — no experiment with that key.
• 404 ASSIGNMENT_REQUIRED — the user has no assignment to expose — call assignment first.
• 500 EXPOSURE_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/client/experiments/checkout_button_v2/exposure'

Curl:

curl -X POST '${BASE_URL}/client/experiments/checkout_button_v2/exposure' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'