People

Notifications

notification-service

What the viewer is told of: who followed them, liked, replied to or reposted what they wrote, and the rest; and what they asked to be told about.

The viewer's notifications

GET/notifications/

The latest first, each with who did what to what, as they are now.

Who: Somebody signed in, with notifications:read

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not do this

Request

curl "https://api.example.org/notifications/" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/notifications/",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "actions": [
        "string"
      ],
      "comment_id": 42,
      "created_at": "2026-10-27T09:30:00Z",
      "id": 42,
      "ids": [
        1
      ],
      "is_read": false,
      "object": null,
      "others": [
        null
      ],
      "others_count": 1,
      "service": "string",
      "subject": null,
      "target": null,
      "type": "string",
      "updated_at": "2026-10-27T09:30:00Z"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Mark one as read

PATCH/notifications/{id}

It takes nothing else: the one thing that changes is that it is read. Answers with it.

Who: Somebody signed in, with notifications:write

Parameters

idintegerrequiredin path
The notification's id.

Answers

200
OK
notification.NotificationItem application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
it is somebody else's
404
there is no such notification

Request

curl -X PATCH "https://api.example.org/notifications/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/<id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/notifications/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "actions": [
    "string"
  ],
  "comment_id": 42,
  "created_at": "2026-10-27T09:30:00Z",
  "id": 42,
  "ids": [
    1
  ],
  "is_read": false,
  "object": {
    "alias": "string",
    "body": "string",
    "content": "string",
    "id": 42,
    "name": "string",
    "portrait_urls": {
      "key": null
    },
    "service": "string",
    "title": "string",
    "type": "string"
  },
  "others": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "others_count": 1,
  "service": "string",
  "subject": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "target": {
    "alias": "string",
    "id": 42,
    "name": "string",
    "title": "string",
    "type": "string"
  },
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z"
}

Delete one

DELETE/notifications/{id}

Who: Somebody signed in, with notifications:write

Parameters

idintegerrequiredin path
The notification's id.

Answers

204
it is gone
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
it is somebody else's
404
there is no such notification

Request

curl -X DELETE "https://api.example.org/notifications/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/<id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/notifications/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Mark all as read

PATCH/notifications/read-all

Every one of the viewer's notifications. Answers how many were unread.

Who: Somebody signed in, with notifications:write

Answers

200
OK
notification.MarkedRead application/json
401
no token, or one that has expired
403
the viewer may not do this

Request

curl -X PATCH "https://api.example.org/notifications/read-all" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/read-all', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/notifications/read-all",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "count": 1
}

What the viewer is told about

GET/notifications/settings

Every kind of thing, on or off: likes, reposts, replies, mentions, follows, posts, events and invitations. All on to begin with.

Who: Somebody signed in, with notifications:read

Answers

200
OK
notification.Settings application/json
401
no token, or one that has expired
403
the viewer may not do this

Request

curl "https://api.example.org/notifications/settings" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/settings', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/notifications/settings",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "topics": [
    {
      "on": false,
      "topic": "string"
    }
  ]
}

Be told about a kind of thing, or not

PATCH/notifications/settings

Turns one on or off. A notification of a kind turned off is not made. Answers with them all.

Who: Somebody signed in, with notifications:write

Body application/json or application/x-www-form-urlencoded or multipart/form-data

onboolean
Whether to be told about it.
topicstringrequired
The kind of thing: likes, reposts, replies, mentions, follows, posts, events or invitations. One of likes, reposts, replies, mentions, follows, posts, events, invitations.

Answers

200
OK
notification.Settings application/json
400
there is no such kind of thing
401
no token, or one that has expired
403
the viewer may not do this

Request

curl -X PATCH "https://api.example.org/notifications/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "on": false,
    "topic": "likes"
  }'

const response = await fetch('https://api.example.org/notifications/settings', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "on": false,
    "topic": "likes"
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/notifications/settings",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "on": False,
      "topic": "likes"
    },
)
answer = response.json()

Answer · 200

{
  "topics": [
    {
      "on": false,
      "topic": "string"
    }
  ]
}

Be told about a post or a profile

POST/notifications/subscriptions

The viewer is notified of what happens to it from now on. Answers with what they are told about.

Who: Somebody signed in, with notifications:write

Body application/x-www-form-urlencoded or multipart/form-data

target_idintegerrequired
The id of the post or the profile to be told about.

Answers

201
Created
NodeItem application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not see it
404
there is no such post or profile

Request

curl -X POST "https://api.example.org/notifications/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "target_id=42"

const form = new URLSearchParams();
form.append('target_id', "42");
const response = await fetch('https://api.example.org/notifications/subscriptions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/notifications/subscriptions",
    headers={"Authorization": f"Bearer {token}"},
    data={"target_id": "42"},
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "alias": "string",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "comment_count": 1,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "event": {
    "address": {
      "city": null,
      "country": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "state_province": null,
      "street": null
    },
    "cancelled_at": "2026-10-27T09:30:00Z",
    "capacity": 1,
    "ends_at": "2026-10-27T09:30:00Z",
    "going_count": 1,
    "has_address": false,
    "has_online_url": false,
    "host": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null,
      "verified": null
    },
    "is_full": false,
    "maybe_count": 1,
    "online_url": "https://example.org/",
    "open_to_host_followers": false,
    "starts_at": "2026-10-27T09:30:00Z",
    "state": "string",
    "timezone_name": "string",
    "viewer_rsvp": "string"
  },
  "feed": {
    "definition": null,
    "icon": "string"
  },
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_leading_viewer": false,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "name": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "uri": "https://example.org/",
  "verified": false,
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  }
}

Stop being told about it

DELETE/notifications/subscriptions/{target_id}

Answers with what they were told about.

Who: Somebody signed in, with notifications:write

Parameters

target_idintegerrequiredin path
The id of the post or the profile.

Answers

200
OK
NodeItem application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not see it
404
there is no such post or profile, or the viewer was not told about it

Request

curl -X DELETE "https://api.example.org/notifications/subscriptions/<target_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/subscriptions/<target_id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/notifications/subscriptions/<target_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "comment_count": 1,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "event": {
    "address": {
      "city": null,
      "country": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "state_province": null,
      "street": null
    },
    "cancelled_at": "2026-10-27T09:30:00Z",
    "capacity": 1,
    "ends_at": "2026-10-27T09:30:00Z",
    "going_count": 1,
    "has_address": false,
    "has_online_url": false,
    "host": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null,
      "verified": null
    },
    "is_full": false,
    "maybe_count": 1,
    "online_url": "https://example.org/",
    "open_to_host_followers": false,
    "starts_at": "2026-10-27T09:30:00Z",
    "state": "string",
    "timezone_name": "string",
    "viewer_rsvp": "string"
  },
  "feed": {
    "definition": null,
    "icon": "string"
  },
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_leading_viewer": false,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "name": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "uri": "https://example.org/",
  "verified": false,
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  }
}

How many are unread

GET/notifications/unread-count

Who: Somebody signed in, with notifications:read

Answers

200
OK
notification.UnreadCount application/json
401
no token, or one that has expired
403
the viewer may not do this

Request

curl "https://api.example.org/notifications/unread-count" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/notifications/unread-count', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/notifications/unread-count",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "count": 1,
  "newest_at": "2026-10-27T09:30:00Z"
}

Written by Claude, reviewed by Rastin Mehr · About this