Skip to content

List your notifications

GET
/account/notifications

Returns your notifications, newest first, one page at a time. Reading the list doesn’t mark anything read.

You need to be signed in; no capability is needed. Without a session cookie or bearer token that identifies you, the answer is 401, whether or not public mode is on. A limit that isn’t a whole number, an only_unread that can’t be read as true or false, or a parameter given twice, gets a plain-text 400 before sign-in is checked. After sign-in, a cursor that can’t be read gets 401 with the error “invalid cursor”; it doesn’t mean you have been signed out.

With only_unread set to true you get only unread notifications; left out or false, you get all of them, read and unread. Each one says what happened (verb), which user here caused it, if any (actor_user_ref), what it is about (target_kind and target_id) and the details saved with it (payload). The actor’s name and picture aren’t included.

A notification records what happened when it was written and isn’t checked again when you read it. It can point at something that has since been deleted or that you can no longer open, or come from someone you have blocked since, and its details aren’t filtered by what you can see now. Marking a notification read doesn’t remove it, and notifications aren’t cleaned up automatically.

Pages hold at most limit notifications, 50 unless you ask for another number; values below 1 count as 1 and above 200 as 200. Notifications with the same time come in a fixed order by id. When more remain, next_cursor is set: send it back as cursor, with the same only_unread, to get older ones. Each page is read separately. A notification newer than the last one on your current page appears only when you start again from the first page. Because a notification’s time is taken when saving begins, one that finishes saving late can still turn up on a later page, or be missed if its time falls among pages you have already read. With only_unread, one marked read in between isn’t on later pages. Server errors get a plain-text 500.

only_unread
boolean

true for unread notifications only. Left out or false, every notification is returned, read or not.

limit
integer
default: 50 >= 1 <= 200

How many notifications per page, 50 if left out; values below 1 count as 1 and above 200 as 200.

cursor
string

The next_cursor from the previous page, to get older notifications; send the same only_unread with it. Left out or empty, the page starts from the newest; one that can’t be read gets 401.

A page of your notifications, newest first.

object
items
required

Up to limit notifications, newest first; empty when there are none.

Array<object>

One notification: what happened, who caused it, what it is about and the details saved when it was written.

object
id
required

The notification’s id, used to mark it read with markNotificationRead.

string format: uuid
actor_user_ref

The user on this server whose action caused the notification. Left out when no user here acted, such as for a like or comment from another server.

integer format: int64
nullable
actor_username

Not filled in at present, so always left out. Look the user up by actor_user_ref if you need a name.

string
nullable
actor_display_name

Not filled in at present, so always left out.

string
nullable
actor_avatar_url

Not filled in at present, so always left out.

string
nullable
verb
required

What happened, such as comment_on_my_post, new_follower or post_shared_with_me. It isn’t a fixed list and other values can appear, so show a verb you don’t recognise in a readable way.

string
target_kind

What target_id refers to, such as post, comment, user or request. Other values can appear. Left out, with target_id, when the notification isn’t about one thing.

string
nullable
target_id

The id of what the notification is about, as text: a UUID for a post, comment or request, or a user’s ref for user. It may since have been deleted or become something you can’t open.

string
nullable
payload

Details saved with the notification, depending on verb, such as a post title or the start of a comment. They are based on what was saved when it was written, aren’t filtered by what you can see now and may not match the stored values exactly. Always sent: usually an object; if the stored details can’t be fully read, it can be null or an object missing the parts that couldn’t be read.

object
key
additional properties
any
read_at

When the notification was marked read; left out while it is unread. It records the mark-read call, not that you opened what it points at.

string format: date-time
nullable
delivered_at
required

When the notification was saved, the same time as created_at. It isn’t when it was shown or emailed.

string format: date-time
created_at
required

When the notification was saved. Pages are ordered by this time.

string format: date-time
next_cursor

Send this back as cursor, with the same only_unread, for older notifications. Left out when there are no more.

string
nullable

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