Replace my notification + view preferences
PATCH /account/preferences
Upserts the caller’s preferences. The wire
contract is full-object replacement: the client sends the
entire resolved object, the server validates against the
build’s known_event_types + known_channels catalogs, and
rejects unknown values rather than silently persisting them.
There is no per-field PATCH verb. To “remove a channel from
an event,” send the full notification_channels object with
that channel omitted from the array. To “fall back to system
default for an event,” omit the event key entirely from the
map.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”PATCH-time payload for the per-user preferences row. Wire
contract is full-object replacement; field-level merge is
NOT supported. Both fields are optional — an absent
notification_channels clears the user’s overrides, an
absent default_views clears the view selections.
object
Map from event-type key to channel list. Unknown event types or unknown channel names trigger a 400. An empty array MEANS “deliver nothing for this event” and overrides the system default; an absent key means “use system default.”
object
Map from event-type key to email delivery cadence
(immediate | hourly | daily | weekly). Absent key =
immediate (send-now). “off” is not a cadence value — mute
email by dropping email from notification_channels.
Unknown event types or cadence values trigger a 400.
object
Default-view selections. Unset fields fall back to per-route defaults at render time. Adding a new view knob is a string-additive change; the valid value sets grow as new layouts ship in later phases.
object
Which tab the home page lands on. Valid values today:
following, latest, trending, for_you. Empty/unset
falls back to latest.
Default browse-feed layout. Valid values today: grid,
masonry, thumbnail, list. Empty/unset falls back to
the route’s default.
Default browse-feed sort. Valid values today: newest,
oldest, popular, trending. Empty/unset falls back
to the route’s default.
Responses
Section titled “ Responses ”Preferences saved.
GET / PATCH response for per-user preferences. Includes the build’s known event-type + channel catalogs so the UI renders toggle grids without hard-coding the lists client-side. Per-event system defaults are surfaced so the UI can show “follows system default — in_app only” hints alongside each toggle.
object
object
Per-event-type email cadence. Absent key = immediate. Values: immediate | hourly | daily | weekly.
object
Default-view selections. Unset fields fall back to per-route defaults at render time. Adding a new view knob is a string-additive change; the valid value sets grow as new layouts ship in later phases.
object
Which tab the home page lands on. Valid values today:
following, latest, trending, for_you. Empty/unset
falls back to latest.
Default browse-feed layout. Valid values today: grid,
masonry, thumbnail, list. Empty/unset falls back to
the route’s default.
Default browse-feed sort. Valid values today: newest,
oldest, popular, trending. Empty/unset falls back
to the route’s default.
Canonical ordered list of notification event types this build knows about. Order is the recommended rendering order in the UI.
Canonical channel names this build supports
(in_app, email, future: sms, push, webhook).
Per-event-type system default channel list. Applied at
notification-write time when the user’s
notification_channels doesn’t have that key.
object
Validation failure (unknown event / channel / duplicate).
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Unexpected server error
object
Human-readable error summary
Example
the request could not be completed