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.

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), 500.