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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”true for unread notifications only. Left out or false, every notification is returned, read or not.
How many notifications per page, 50 if left out; values below 1 count as 1 and above 200 as 200.
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.
Responses
Section titled “ Responses ”A page of your notifications, newest first.
object
Up to limit notifications, newest first; empty when there are none.
One notification: what happened, who caused it, what it is about and the details saved when it was written.
object
The notification’s id, used to mark it read with markNotificationRead.
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.
Not filled in at present, so always left out. Look the user up by actor_user_ref if you need a name.
Not filled in at present, so always left out.
Not filled in at present, so always left out.
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.
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.
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.
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
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.
When the notification was saved, the same time as created_at. It isn’t when it was shown or emailed.
When the notification was saved. Pages are ordered by this time.
Send this back as cursor, with the same only_unread, for older notifications. Left out when there are no more.
Authentication 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"}