Guides

Session Setup

POST /v1/personas/session — bind a seat’s members and their ages for the session.

POST /v1/personas/session binds the seat roster for a passenger session: who is on which seat, and each member’s declared age band. This is what gives a member their real age tier — until you bind them, every member resolves to Unknown and is served the child-safe catalog. Do it once, early in the session, before scored serves or suggestions.

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

FieldRequiredRules
membersyes1–20 entries. Empty or > 20 → 422 request.validation.
members[].seatIdyesNon-blank.
members[].ageBandyesNon-blank declared band — e.g. "adult", "8-12", "under-5". A binding input, not the authoritative tier.
members[].memberSlotnoWhich member on a shared seat. Omit for a solo traveler.
members[].archetypeIdnoOptional starting persona — an archetypeId from GET /v1/personas.
members[].roleInGroup, members[].gendernoOptional descriptors.
$curl -X POST "https://api.staging.westiq.ai/v1/personas/session" \
>  -H "Authorization: Bearer $ACCESS_TOKEN" \
>  -H "X-Session-Id: seat-12A-f3d9c1" \
>  -H "Content-Type: application/json" \
>  -d '{
>        "members": [
>          { "seatId": "12A", "ageBand": "adult" },
>          { "seatId": "12A", "memberSlot": "slot-2", "ageBand": "8-12" }
>        ]
>      }'
1{
2  "schemaVersion": "1",
3  "correlationId": "req_0197c0a1b2c3d4e5f60718293a4b5c6d",
4  "boundMembers": 2,
5  "ageTiers": ["Adult", "Child"]
6}
  • boundMembers is how many profiles were persisted.
  • ageTiers is the server-resolved tier for each member, in the same order as your members array. It is echoed for your display only — every later serve / suggest / enrich call re-resolves the tier from the stored profile and never trusts this value back.

Age resolution is fail-closed. An unknown, blank, or unparseable ageBand resolves to Unknown — treated as the most-restrictive Child tier — never a permissive default. A member you don’t bind at all is also Unknown. So a Child/Unknown in ageTiers for someone you meant to be an adult means the ageBand string wasn’t recognized — check it.

Errors

Standard envelope: 400 session.unresolved (missing/invalid X-Session-Id), 401 / 403 auth, 422 request.validation (empty members, more than 20, or any member missing seatId/ageBand), 500.