Bluesky Notifications
Read and manage the notifications of a connected Bluesky account: replies, mentions, quotes, likes, reposts, new followers and the rest of what the Bluesky app shows under its bell.
Every endpoint on this page acts as the connected account, so user (the Upload-Post profile username with Bluesky connected) is always required. Without it the call answers 400 bluesky_user_required; a profile without Bluesky answers 400 bluesky_not_connected.
Authorization: Apikey your-api-key-here
To get new replies pushed to you instead of polling, see the comment_received webhook (not generally available yet for Bluesky). For other Bluesky reads (profiles, feeds, search, followers) see Bluesky Reads.
List notifications
GET /api/uploadposts/bluesky/notifications
| Name | Required | Description |
|---|---|---|
user | Yes | Profile username. |
reasons | No | Only these kinds, comma-separated or repeated: reply, mention, quote, like, repost, follow, starterpack-joined, verified, unverified, like-via-repost, repost-via-repost, subscribed-post, contact-match. |
limit | No | 1-100. |
cursor | No | pagination.next_cursor of the previous page. |
Reading notifications does not mark them as seen. To clear the unread badge, call Mark as seen.
curl 'https://api.upload-post.com/api/uploadposts/bluesky/notifications?user=my-profile&reasons=reply,mention,quote&limit=50' \
-H 'Authorization: Apikey your-api-key-here'
{
"success": true,
"platform": "bluesky",
"notifications": [
{
"id": "at://did:plc:def456.../app.bsky.feed.post/3lb9abc",
"cid": "bafyreib...",
"reason": "reply",
"reason_subject": "at://did:plc:abc123.../app.bsky.feed.post/3lb2xyz",
"author": {
"id": "did:plc:def456...",
"handle": "bob.bsky.social",
"display_name": "Bob",
"avatar": "https://cdn.bsky.app/img/avatar/...",
"url": "https://bsky.app/profile/bob.bsky.social"
},
"is_read": false,
"indexed_at": "2026-11-12T09:14:03.120Z",
"text": "Great thread, thanks!",
"url": "https://bsky.app/profile/bob.bsky.social/post/3lb9abc",
"created_at": "2026-11-12T09:14:02.800Z",
"reply_to": "at://did:plc:abc123.../app.bsky.feed.post/3lb2xyz",
"thread_root": "at://did:plc:abc123.../app.bsky.feed.post/3lb2xyz"
},
{
"id": "at://did:plc:ghi789.../app.bsky.graph.follow/3lb8def",
"cid": "bafyreic...",
"reason": "follow",
"reason_subject": null,
"author": {
"id": "did:plc:ghi789...",
"handle": "carol.bsky.social",
"display_name": "Carol",
"avatar": null,
"url": "https://bsky.app/profile/carol.bsky.social"
},
"is_read": true,
"indexed_at": "2026-11-11T18:02:41.000Z"
}
],
"seen_at": "2026-11-12T08:00:00.000Z",
"pagination": { "next_cursor": "2026-11-11T18:02:41.000Z", "has_more": true }
}
| Field | Description |
|---|---|
id | at:// URI of the record that caused the notification (the reply, the like, the follow…). |
cid | Content id of that record. |
reason | What happened: one of the reasons values above. |
reason_subject | at:// URI of the post the notification refers to (the liked or reposted post, for example), or null. |
author | Who did it, as an account object. |
is_read | Bluesky's read flag for this notification. |
indexed_at | When Bluesky indexed it. |
text, url, created_at, reply_to, thread_root | Only when the record is a post (replies, mentions, quotes): its text, bsky.app link, creation time and the at:// URIs of its parent and root. |
seen_at | The account's last "seen" mark. |
Unread count
GET /api/uploadposts/bluesky/notifications/unread-count?user=my-profile
{ "success": true, "platform": "bluesky", "count": 7 }
Mark as seen
POST /api/uploadposts/bluesky/notifications/seen
Marks the account's notifications as seen, exactly like opening the notifications tab in the Bluesky app: the unread badge clears there too.
Bluesky puts the account's unread notification count to 0, whatever seen_at says (even a seen_at in the past), and there is no way to bring the unread notifications back. The request needs "confirm": true; without it the answer is 400 confirmation_required and nothing changes.
| Field | Required | Description |
|---|---|---|
user | Yes | Profile username. |
confirm | Yes | Must be true. |
seen_at | No | ISO-8601 datetime with a time zone, stored as the account's last "seen" mark. Defaults to now. Cannot be in the future. |
curl -X POST 'https://api.upload-post.com/api/uploadposts/bluesky/notifications/seen' \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "confirm": true}'
{
"success": true,
"platform": "bluesky",
"seen_at": "2026-11-12T09:20:00.000Z",
"unread_count": 0,
"warning": "Bluesky resets the account's unread notification count to 0, whatever seen_at says, and that cannot be undone."
}
Notification preferences
Get
GET /api/uploadposts/bluesky/notification-preferences?user=my-profile
Returns {"success": true, "platform": "bluesky", "preferences": {...}}, where preferences is Bluesky's own object, as Bluesky returns it.
Update
POST /api/uploadposts/bluesky/notification-preferences
Send only what you want to change: it is merged with the current preferences.
| Field | Required | Description |
|---|---|---|
user | Yes | Profile username. |
preferences | Yes | Object with one key per kind of notification (see below). |
| Keys | Each value takes |
|---|---|
follow, like, likeViaRepost, mention, quote, reply, repost, repostViaRepost | include (all or follows: from everyone or only from accounts you follow), list (show it in the notifications list, boolean), push (send a push notification, boolean). |
starterpackJoined, subscribedPost, unverified, verified | list and push (booleans). |
Chat (DM) notification settings are not here: they belong to the DM settings.
curl -X POST 'https://api.upload-post.com/api/uploadposts/bluesky/notification-preferences' \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "preferences": {"reply": {"include": "follows"}, "like": {"push": false}}}'
The answer is {"success": true, "platform": "bluesky", "preferences": {...}} with the preferences after the change. An unknown key, a wrong sub-key or a value of the wrong type answers 400 bluesky_invalid_parameter.
Activity subscriptions
An activity subscription makes the Bluesky account get a notification whenever another account posts, or posts and replies (the bell on a Bluesky profile).
List
GET /api/uploadposts/bluesky/activity-subscriptions?user=my-profile
| Name | Required | Description |
|---|---|---|
user | Yes | Profile username. |
limit | No | 1-100. |
cursor | No | pagination.next_cursor of the previous page. |
{
"success": true,
"platform": "bluesky",
"subscriptions": [
{
"id": "did:plc:def456...",
"handle": "bob.bsky.social",
"display_name": "Bob",
"avatar": null,
"url": "https://bsky.app/profile/bob.bsky.social",
"activity_subscription": { "post": true, "reply": false }
}
],
"pagination": { "next_cursor": null, "has_more": false }
}
Subscribe, change or unsubscribe
POST /api/uploadposts/bluesky/activity-subscriptions
| Field | Required | Description |
|---|---|---|
user | Yes | Profile username. |
subject | Yes | Handle or DID of the account to follow the activity of. |
post | No | true to be notified of its posts. Default false. |
reply | No | true to be notified of its replies too. Default false. |
Sending both post and reply as false stops the notifications from that account.
curl -X POST 'https://api.upload-post.com/api/uploadposts/bluesky/activity-subscriptions' \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "subject": "bob.bsky.social", "post": true, "reply": false}'
{
"success": true,
"platform": "bluesky",
"subject": "did:plc:def456...",
"activity_subscription": { "post": true, "reply": false }
}
A handle that does not exist answers 404 bluesky_not_found.
Caching, limits and errors
- The notification list, the unread count, the preferences and the activity subscriptions are cached for 30 seconds per Bluesky account, keyed on the validated parameters, so a change you just made can take up to 30 seconds to show in them. The write endpoints are not cached.
- These endpoints read as the account, so they count against the per-account limits of Bluesky Reads (
429bluesky_read_rate_limited) and the shared ceiling (503bluesky_read_capacity). - Errors use the same shape and
error_codevalues as Bluesky Reads. One more applies to the write endpoints (mark as seen, update preferences, activity subscriptions):503bluesky_notification_writes_disabled, when changing notification settings is temporarily disabled. Retry later.