One API, five clients

Send the token in the Authorization header on every authenticated request. A missing or expired token gets a 401.

A provider token works as a bearer on its own, but Apple’s expires in about ten minutes. So a client trades whatever it holds for a Cue session: a 1-hour access token plus a 90-day opaque refresh token. There is one mint endpoint rather than one per provider — whatever the existing decoder accepts, POST /api/auth/session accepts. Each refresh rotates the pair, and replaying a consumed token revokes the whole chain descended from that sign-in.

{}

A user’s chosen name colour is one fixed enum, shared verbatim across web, iOS and the backend. Change it and all of your past messages recolour on the next fetch.

Every account carries an allowance on the two dimensions that cost real money: stored bytes, and how many events, decisions and trips it starts per rolling 30 days. It rides a self-scoped endpoint and nothing else — no roster, profile or member list ever carries level data, so no one can tell what level anyone else holds. slug and dimension are opaque, and allowances is a list rather than fixed keys, so a new tier or a third dimension lights up on already-shipped apps with no release. A non-null displayName is the badge.

{
  "slug": "established",
  "displayName": null,
  "blurb": null,
  "allowances": [
    {
      "dimension": "storage",
      "label": "Photos & video",
      "unit": "bytes",
      "allowance": 3221225472,
      "used": 431006720,
      "room": 2790218752,
      "resetsAt": null
    },
    {
      "dimension": "creations",
      "label": "New events, decisions and trips",
      "unit": "count",
      "allowance": 100,
      "used": 7,
      "room": 93,
      "resetsAt": "2026-08-27T09:14:00Z"
    }
  ]
}

One read returns everything a client renders: the proposed slots, every invitation with its free-text reply, and the AI resolution with its per-slot scores (JSON, as a string) and a human-readable reason in the majority language of the replies.

{
  "id": 128,
  "title": "Saturday hike",
  "description": "Bring water and good shoes.",
  "location": "Sognsvann",
  "googleMapsUrl": null,
  "placeId": null,
  "status": "open",
  "finalizedTime": null,
  "timeZone": "Europe/Oslo",
  "createdBy": {
    "id": 42,
    "name": "Ada",
    "pictureUrl": null,
    "chatColor": "indigo"
  },
  "proposedTimes": [
    {
      "id": 901,
      "dateTime": "2026-06-13T09:00:00Z"
    },
    {
      "id": 902,
      "dateTime": "2026-06-14T10:00:00Z"
    }
  ],
  "invitations": [
    {
      "id": 511,
      "user": {
        "id": 7,
        "name": "Linnea",
        "pictureUrl": null,
        "chatColor": "coral"
      },
      "status": "responded",
      "responseText": "Saturday is better for me",
      "respondedAt": "2026-06-08T18:30:00Z",
      "role": "participant"
    }
  ],
  "resolution": {
    "id": 77,
    "recommendedTime": {
      "id": 901,
      "dateTime": "2026-06-13T09:00:00Z"
    },
    "reasoning": "Saturday morning suits everyone who has replied so far.",
    "scores": "[{\"proposedTimeId\":901,\"score\":0.9},{\"proposedTimeId\":902,\"score\":0.4}]",
    "resolvedAt": "2026-06-08T18:31:00Z"
  },
  "createdAt": "2026-06-08T18:00:00Z",
  "updatedAt": "2026-06-08T18:31:00Z",
  "aiCommentatorType": null,
  "aiComment": null,
  "weatherEnabled": true,
  "weatherReport": {
    "id": 88,
    "report": "Saturday looks dry and mild — about 18°C with light cloud; bring a layer for the morning.",
    "forecastFetchedAt": "2026-06-08T18:25:00Z",
    "createdAt": "2026-06-08T18:25:30Z"
  },
  "latitude": 59.9764,
  "longitude": 10.7214,
  "chatEnabled": true,
  "chatPreview": null,
  "cover": null,
  "containers": [
    {
      "kind": "trip",
      "id": 44,
      "title": "Lisbon, long weekend"
    }
  ],
  "myRole": "organizer"
}

status is one of openfinalizedcanceled and each invitation is pendingrespondeddeclined. Every invitation also carries a role — organizerparticipant — so the creator can hand the organizing powers to anyone already invited, and myRole tells the client which one the viewer holds without re-deriving the rule. Two opt-in extras ride along on the event when enabled:

One read returns the whole picture: every option (each with its optional AI insight), every participant’s free-text preference, and the AI recommendation with per-option fit scores (JSON, as a string) and a human-readable reason.

{
  "id": 128,
  "question": "Where should we go this summer?",
  "context": "4 people, a long weekend, flying from Oslo.",
  "status": "open",
  "createdBy": {
    "id": 42,
    "name": "Ada",
    "pictureUrl": null,
    "chatColor": "indigo"
  },
  "finalizedOption": null,
  "options": [
    {
      "id": 301,
      "label": "Lisbon",
      "createdByUserId": 42,
      "createdAt": "2026-06-08T18:00:00Z",
      "insight": {
        "id": 51,
        "brief": "Warm, walkable, cheap direct flights from Oslo; can be crowded in July.",
        "sources": "[{\"title\":\"Visit Lisboa\",\"url\":\"https://www.visitlisboa.com\"}]",
        "searchQueries": "[\"Lisbon July weather\",\"Oslo Lisbon direct flights\"]",
        "createdAt": "2026-06-08T18:02:00Z"
      }
    },
    {
      "id": 302,
      "label": "Tromsø",
      "createdByUserId": 7,
      "createdAt": "2026-06-08T18:01:00Z",
      "insight": null
    }
  ],
  "preferences": [
    {
      "id": 811,
      "user": {
        "id": 7,
        "name": "Linnea",
        "pictureUrl": null,
        "chatColor": "coral"
      },
      "status": "stated",
      "preferenceText": "Somewhere warm, but Tromsø would be magical",
      "respondedAt": "2026-06-08T18:30:00Z",
      "role": "participant"
    }
  ],
  "recommendation": {
    "id": 61,
    "recommendedOption": {
      "id": 301,
      "label": "Lisbon"
    },
    "reasoning": "Lisbon best fits the group's lean toward warm weather and cheap direct flights.",
    "scores": "[{\"optionId\":301,\"fit\":0.86},{\"optionId\":302,\"fit\":0.42}]",
    "recommendedAt": "2026-06-08T18:31:00Z"
  },
  "contextItems": [],
  "insightsEnabled": true,
  "aiCommentatorType": null,
  "aiComment": null,
  "chatEnabled": true,
  "chatPreview": null,
  "containers": [],
  "deadline": "2026-08-01T22:00:00Z",
  "createdAt": "2026-06-08T18:00:00Z",
  "updatedAt": "2026-06-08T18:31:00Z",
  "myRole": "organizer"
}

status is one of openfinalizedcanceled and each participant is pendingstateddeclined with a role of organizerparticipant. An optional deadline gives the group a decide-by instant — informational only, nothing auto-finalizes. Optional AI extras opt in per decision:

A handful of coarse event names carry a changeType that says precisely what moved. A heartbeat lands every 20 seconds to keep the connection warm.

Why signals and not payloads? The full reasoning is in the architecture deep-dive.

An AI participant takes one of three interaction modes: proactivemention_onlyevent_driven.

visibility is publicprivatesecret and each member holds a role of owneradminmember. Private channels gate entry behind a request a member approves.

One read returns the container and everything hanging off it: the roster with roles, the linked pillars in itinerary order, the notes and documents, and the Travel AI brief when it’s switched on. The album pages separately — only its count rides here.

{
  "id": 44,
  "title": "Lisbon, long weekend",
  "description": "Four of us, flying from Oslo.",
  "destination": "Lisbon",
  "startDate": "2026-09-11",
  "endDate": "2026-09-14",
  "cover": null,
  "members": [
    {
      "id": 210,
      "user": {
        "id": 42,
        "name": "Ada",
        "pictureUrl": null,
        "chatColor": "indigo"
      },
      "role": "guide",
      "joinedAt": "2026-06-08T18:00:00Z"
    },
    {
      "id": 211,
      "user": {
        "id": 7,
        "name": "Linnea",
        "pictureUrl": null,
        "chatColor": "coral"
      },
      "role": "traveler",
      "joinedAt": "2026-06-08T18:04:00Z"
    }
  ],
  "links": [
    {
      "linkId": 91,
      "linkedBy": {
        "id": 42,
        "name": "Ada",
        "pictureUrl": null,
        "chatColor": "indigo"
      },
      "linkedAt": "2026-06-08T18:10:00Z",
      "pillar": {
        "kind": "event",
        "id": 128,
        "title": "Flight out",
        "when": "2026-09-11T06:40:00Z",
        "status": "finalized"
      },
      "access": "member"
    },
    {
      "linkId": 92,
      "linkedBy": {
        "id": 7,
        "name": "Linnea",
        "pictureUrl": null,
        "chatColor": "coral"
      },
      "linkedAt": "2026-06-08T18:12:00Z",
      "pillar": {
        "kind": "decision",
        "id": 301,
        "title": "Where do we stay?",
        "status": "open",
        "deadline": "2026-08-01T22:00:00Z"
      },
      "access": "none"
    }
  ],
  "notes": [
    {
      "id": 55,
      "title": "Packing",
      "body": "Light layers — it's still warm in September.",
      "noteDate": null,
      "author": {
        "id": 42,
        "name": "Ada",
        "pictureUrl": null,
        "chatColor": "indigo"
      },
      "createdAt": "2026-06-08T18:20:00Z",
      "updatedAt": "2026-06-08T18:20:00Z"
    }
  ],
  "documents": [],
  "mediaCount": 0,
  "chatEnabled": true,
  "chatPreview": null,
  "travelAiEnabled": true,
  "travelBrief": {
    "id": 12,
    "brief": "Four of you land in Lisbon on the 11th…",
    "createdAt": "2026-06-08T18:21:00Z"
  },
  "aiCommentatorType": "funny",
  "aiComment": null,
  "sourceChannel": null,
  "createdAt": "2026-06-08T18:00:00Z",
  "updatedAt": "2026-06-08T18:21:00Z"
}

A link is a soft tag, never ownership or access. The wire never says “trip” where it means container: containerKind is tripchannel and pillarKind is eventdecision, both plain strings a client can skip when it meets an unknown one. Each row carries the viewer’s access — membernone — and none stops at kind, title and date: the discoverable card. Trip roles are guidetraveler.

A clip is too big to push through the API, so it goes straight to storage. Ask for a ticket, PUT the raw bytes to the signed URL, then finalize — an async worker transcodes and signals media-ready over SSE. mediaKind is imagevideodocument and status is readyprocessingfailed.

{
  "contentLength": 18452310,
  "durationMsHint": 8200
}

Groups come back in one fixed order — eventdecisiontripchannelusermessagephoto — with empty ones omitted, because a surface driven by muscle memory beats one that reshuffles. kind is a plain lowercase string rather than a wire enum: the set is open, and a client drops one it doesn’t recognize. Every hit shares one shape — required kind, id, title, plus optionals only some kinds carry (snippet, status, when, handle, imagePhotoId, mediaKind, sender, createdAt, conversation).

Where a client can render something better than a sentence, the body carries numbers instead of prose. Both allowance refusals do — a code to switch on, and the figures behind it, so each client composes its own copy once at its API seam rather than in every form.

{
  "code": "quota_exceeded",
  "usedBytes": 3218000000,
  "quotaBytes": 3221225472
}