My notification feed

GET

/account/notifications

• Local development behind nginx (port 8088 by default)

Cursor-paginated notification feed for the caller. Newest- first; only_unread=true restricts to the unread tail (the inbox’s “Unread” tab). Each notification carries a verb (matching userprefs.KnownEventTypes), an optional actor, an optional polymorphic target reference (target_kind + target_id), and a JSONB payload with per- verb extra context the frontend renderer reads.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Query Parameters

only_unread

boolean

limit

integer

default: 50 >= 1 <= 200

cursor

string

Responses

200

A page of notifications.

object

items

required

Array<object>

One row from the per-user notifications feed. verb matches one of the userprefs.KnownEventTypes strings. target_kind + target_id form a polymorphic reference into whatever entity the notification is about (e.g. target_kind= “post”, target_id=); the frontend renderer keys on verb

• target_kind to build the right card.

object

id

required

string format: uuid

actor_user_ref

User whose action triggered the notification. NULL for system-generated events (license expiry, broadcast).

integer format: int64

nullable

actor_username

Denormalized for inbox render — no second round-trip.

string

nullable

actor_display_name

string

nullable

actor_avatar_url

string

nullable

verb

required

Event-type identifier. One of userprefs.KnownEventTypes. Frontend i18n keys are notifications.verb_<verb>.

string

target_kind

Type discriminator for the polymorphic target (post, comment, asset, user, collection, license, request).

string

nullable

target_id

ID of the target entity. UUID-typed entities stringify; BIGINT-typed entities stringify too. Frontend resolves via target_kind.

string

nullable

payload

Per-verb extra context (comment excerpt, license kid, request reason, etc.). Schema documented per-verb in app/internal/notifications/events.go.

object

key

additional properties

any

read_at

NULL = unread.

string format: date-time

nullable

delivered_at

required

When the row landed (in-app delivery time).

string format: date-time

created_at

required

string format: date-time

next_cursor

string

nullable

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}