Skip to content

Replace my preferences

PATCH
/account/preferences

Replaces all your preferences with the document you send. Anything you leave out is reset to its default, so sending {} clears everything.

To change one setting, get your preferences, change what you need and send every member back: notification_channels, email_cadence, default_views, feed_filters, browse_rail and mature_content. There’s no version check, so two clients saving at the same time can overwrite each other.

In notification_channels, list the channels you want for an event, send an empty list to mute it, or leave the event out to use its default. An unknown event, channel, cadence or view value, or a channel listed twice, gets a 400. Rail lists are cleaned instead of refused, and unknown top-level keys are ignored.

The response is what was saved, in the same shape as GET /account/preferences. Other app servers that share the database are told to drop their cached copy; if that message fails, they can keep serving the old preferences for a while.

The whole preferences document. Every member is optional, but a member you leave out is reset, not kept.

object
notification_channels

Channels for each event. List the channels you want, send an empty list to mute the event, or leave the event out to use its default. An unknown event or channel, or a channel listed twice, gets a 400.

object
key
additional properties
Array<string>
email_cadence

How often to email each event: immediate, hourly, daily or weekly. An event you leave out gets immediate. A digest cadence only applies while in_app is also on for that event; with email alone, the email goes out right away. To stop email for an event, take email out of its channels; there’s no “off” cadence.

object
key
additional properties
string
default_views

Your default views: the tab the browse page opens on, its layout and its sort. In the web app they’re starting points: a choice this device has already stored wins over the account default.

object
home_tab

The feed tab the browse page opens on. Empty or unset means latest.

string
Allowed values: "" latest following
browse_layout

The default browse layout, used when the operator has that layout turned on. Otherwise the app picks a default for the device from the layouts that are turned on.

string
Allowed values: "" grid masonry thumbnail list feed
browse_sort

The default sort order: newest posts first or oldest first. Empty or unset means newest.

string
Allowed values: "" newest oldest
feed_filters

Feed filters. A filter you leave out, or the whole object, is set to false.

object
show_restricted

Whether GET /posts keeps placeholders for assets you can’t see. It’s off by default: the feed drops those assets, and drops a post altogether when it had assets and none are left, unless you wrote it. Turn it on to keep every placeholder. Other endpoints, such as GET /posts/{id}, don’t use this setting.

boolean
browse_rail

Your browse-rail changes. Leaving out the object clears them all, and leaving out a list clears that list. Duplicates, empty entries and tags longer than 200 bytes are dropped, and each list keeps at most 1,000 entries. Entries for teams or tags you can no longer see are kept; the rail just doesn’t show them.

object
hidden_team_ids

Teams the person has hidden from the rail. Empty means none.

Array<string>
team_order

Followed teams the person has moved to the front, in that order. Other teams keep their usual order behind them. Empty means the server’s order.

Array<string>
hidden_tags

Followed tags the person has hidden from the rail. Hiding a tag isn’t unfollowing it: its posts still reach the following feed.

Array<string>
tag_order

Followed tags the person has moved to the front, in that order, with the rest behind them. Empty means the server’s order, most recently followed first.

Array<string>
mature_content

Your mature-content opt-in. Leaving out the object, or show inside it, sets it to false, so a request that sends only other members opts the account out.

object
show

Whether the account has opted in to mature content. Absent or false means it hasn’t, which is the default.

boolean

Preferences saved.

Your preferences, plus what a client needs to show them: the known events and channels and the default channels for each event.

object
notification_channels
required

Channels for each event you’ve set. An event that isn’t here uses its default; an event you’ve muted comes back as null.

object
key
additional properties
Array<string>
email_cadence

Email cadence for each event you’ve set. An event that isn’t here gets immediate.

object
key
additional properties
string
default_views
required

Your default views: the tab the browse page opens on, its layout and its sort. In the web app they’re starting points: a choice this device has already stored wins over the account default.

object
home_tab

The feed tab the browse page opens on. Empty or unset means latest.

string
Allowed values: "" latest following
browse_layout

The default browse layout, used when the operator has that layout turned on. Otherwise the app picks a default for the device from the layouts that are turned on.

string
Allowed values: "" grid masonry thumbnail list feed
browse_sort

The default sort order: newest posts first or oldest first. Empty or unset means newest.

string
Allowed values: "" newest oldest
feed_filters
required

Feed filters. Always present, with every filter set to true or false.

object
show_restricted

Whether GET /posts keeps placeholders for assets you can’t see. It’s off by default: the feed drops those assets, and drops a post altogether when it had assets and none are left, unless you wrote it. Turn it on to keep every placeholder. Other endpoints, such as GET /posts/{id}, don’t use this setting.

boolean
browse_rail
required

Your browse-rail changes. Always present, with every list included even when it’s empty.

object
hidden_team_ids

Teams the person has hidden from the rail. Empty means none.

Array<string>
team_order

Followed teams the person has moved to the front, in that order. Other teams keep their usual order behind them. Empty means the server’s order.

Array<string>
hidden_tags

Followed tags the person has hidden from the rail. Hiding a tag isn’t unfollowing it: its posts still reach the following feed.

Array<string>
tag_order

Followed tags the person has moved to the front, in that order, with the rest behind them. Empty means the server’s order, most recently followed first.

Array<string>
mature_content
required

Your mature-content opt-in. Always present, with show set.

object
show

Whether the account has opted in to mature content. Absent or false means it hasn’t, which is the default.

boolean
known_event_types
required

The notification events this build knows about, in the order to show them.

Array<string>
known_channels
required

The channels this build supports: in_app and email.

Array<string>
default_channels_by_event
required

The channels each event uses when you haven’t set it. Every event defaults to in_app; direct messages and an expired license also default to email.

object
key
additional properties
Array<string>

A value isn’t recognised: an unknown event, channel, cadence or view value, or a channel listed twice for one event.

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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"
}

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed