Guides

Suggestions

POST /v1/suggestions — score a batch of titles for one member.

POST /v1/suggestions takes a batch of titles you’re about to show a member and scores them against that member’s bound persona and affinity — a fast-tier “why this, for you” pass over content you already have on screen.

Session-scoped — requires the X-Session-Id header. Body (max 64 KiB):

FieldRequiredRules
seatIdyesThe member’s seat.
titleIdsyes1–20 integer title ids (see the id note).
memberSlotnoWhich member on a shared seat. Omit for solo.
$curl -X POST "https://api.staging.westiq.ai/v1/suggestions" \
>  -H "Authorization: Bearer $ACCESS_TOKEN" \
>  -H "X-Session-Id: seat-12A-f3d9c1" \
>  -H "Content-Type: application/json" \
>  -d '{ "seatId": "12A", "titleIds": [2041, 2088, 3120] }'
1{
2  "schemaVersion": "1",
3  "correlationId": "req_0197c0a1b2c3d4e5f60718293a4b5c6d",
4  "items": [
5    {
6      "titleId": 2041,
7      "delta": 0.18,
8      "boostScore": 74,
9      "whyForYou": "Leans into the character drama you finish most"
10    }
11  ],
12  "behavioralInsight": "You're in a settle-in, one-long-film mood.",
13  "moodInference": "focused"
14}
  • delta and boostScore (0–100) are code-clamped composites — the model supplies a raw signal, deterministic code computes the final numbers.
  • whyForYou and behavioralInsight are passenger-visible model free text.
  • moodInference is optional and may be null.

Flight-bound sessions

If the session is bound to a flight (via flightInstanceId at session setup) and that flight has a pushed active catalog, suggestions are intersected with the flight’s active set — titles not loaded on the aircraft are not suggested. The intersection can only ever narrow, and it never overrides the age gate below. A session with no flight binding, or a flight with no push, behaves exactly as before.

Age-gating: an empty result is honest, not an error

Before any model call, the requested titleIds are filtered against the member’s age tier. This has an important consequence:

A fully-gated request returns an honest empty result, not a 4xx. If none of the titles you sent are allowed for this member’s tier (e.g. a Child member and all-mature titles, or an unbound member whose tier is Unknown), the platform makes no model call and returns a 200 with empty fields:

1{ "schemaVersion": "1", "correlationId": "req_…",
2  "items": [], "behavioralInsight": "" }

(moodInference is null here, and null fields are omitted from responses — so the key is simply absent, not sent as null.)

Do not treat this as a failure — it is the fail-closed design, and it costs nothing. If you expected results, check that the member is bound with the right age and that the titleIds suit their tier.

Titles the visible catalog has no rating for (never seen, or outside your namespace) are treated as unknown-rating and excluded for non-adult tiers — so a legitimate client should only send ids it surfaced through an already-gated catalog view.

Today the result rides this HTTP response only — the suggestions.updated SSE frame is not yet published. Read the response directly.

Errors

Standard envelope: 400 session.unresolved, 401 / 403, 422 request.validation (blank seatId, empty titleIds, or more than 20), 429 rate.limited over the per-client request-rate limit (honor the Retry-After header), 500.