Notifications

Base URL https://api.flam.fashion. Send Authorization: Bearer flam_sk_… on every call; a handful of routes are session-only and say so. How keys and roles work.

GET /api/notifications

The board — what happened while she was gone

ONE handler, three jobs. No params: the panel's newest page. before=<cursor>: the next page, using the opaque cursor from the previous response's nextCursor. since=<eventSeq>: the reconnect backfill, ascending, for a client that already holds rows.

unread is ALWAYS returned and is always the whole truth, however the list is truncated — it is the badge, and it is bounded to the last 90 days so its cost stays O(recent) rather than O(the house's history) once she has pressed Mark all read.

unread counts only MATURED rows (older than the grace window); the list deliberately does not filter by maturity, because she opened the panel on purpose. Each pending row carries maturesInMs, the server's own remainder — the client never reads its own clock.

Parameters

Responses

200 returns:

{
  "notifications": [
    {
      "id": "string",
      "kind": "string",
      "subjectType": "string",
      "subjectId": "string",
      "payload": {},
      "createdAt": "string",
      "maturesInMs": 0,
      "eventSeq": 0,
      "read": true,
      "needsYou": 0,
      "answered": 0
    }
  ],
  "unread": 0,
  "nextCursor": "string"
}

Call it

curl -X GET "https://api.flam.fashion/api/notifications" \
  -H "Authorization: Bearer $FLAM_API_KEY"

GET /api/notifications/{id}/opinion

The facts behind the house's opinion of one board row

Resolves a matured notification to its develop's frames, their verdicts, the previous pass of each frame, and two 14-day aggregates over the house (the cross-run pattern and the learning floor) — then asks route() which surface may carry it. FACTS ONLY: an enum, ids, counts and vocabulary terms. The sentence is composed on the client, which is what keeps the hedge gate and the tool-noun gate greps instead of hopes.

404 for a notification belonging to another house, indistinguishable from an id that does not exist. No model is called on this path, ever, and the judge's own note is never selected (ADMIN/L1 only).

Parameters

Responses

200 returns:

{
  "surface": "bar",
  "moment": "ranking",
  "subject": "string",
  "href": "string",
  "frames": [
    {
      "jobId": "string",
      "ordinal": 0,
      "code": "string",
      "where": "string",
      "confidence": "sure",
      "unreadable": true
    }
  ],
  "tokensReleased": 0,
  "patternCode": "string",
  "patternWhere": "string",
  "patternRuns": 0,
  "floorCode": "string",
  "floorWhere": "string",
  "cost": 0
}

Call it

curl -X GET "https://api.flam.fashion/api/notifications/{id}/opinion" \
  -H "Authorization: Bearer $FLAM_API_KEY"

POST /api/notifications/read

She saw it

{ ids: [...] } marks those rows; { all: true } marks everything this house has that this person has not read. Idempotent — a second POST from a second tab inserts nothing and returns the ids it found already marked as marked: 0.

NOTHING IS EVER DELETED. Mark all read writes receipts; the rows stay in the board, dated.

source records HOW she came to know — open (she clicked the row), presence (she was looking at the thing when it landed, so the house stayed quiet), all, chat. It is the only way to audit whether presence is OVER-suppressing, which is a failure nobody files a ticket about.

Request body — application/json

{
  "ids": [
    "string"
  ],
  "all": true,
  "source": "open"
}

Responses

200 returns:

{
  "marked": 0,
  "ids": [
    "string"
  ]
}

Call it

curl -X POST "https://api.flam.fashion/api/notifications/read" \
  -H "Authorization: Bearer $FLAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["string"],"all":true,"source":"open"}'