Skip to main content

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
NameRequiredDescription
userYesProfile username.
reasonsNoOnly 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.
limitNo1-100.
cursorNopagination.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 }
}
FieldDescription
idat:// URI of the record that caused the notification (the reply, the like, the follow…).
cidContent id of that record.
reasonWhat happened: one of the reasons values above.
reason_subjectat:// URI of the post the notification refers to (the liked or reposted post, for example), or null.
authorWho did it, as an account object.
is_readBluesky's read flag for this notification.
indexed_atWhen Bluesky indexed it.
text, url, created_at, reply_to, thread_rootOnly 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_atThe 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.

This cannot be undone

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.

FieldRequiredDescription
userYesProfile username.
confirmYesMust be true.
seen_atNoISO-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.

FieldRequiredDescription
userYesProfile username.
preferencesYesObject with one key per kind of notification (see below).
KeysEach value takes
follow, like, likeViaRepost, mention, quote, reply, repost, repostViaRepostinclude (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, verifiedlist 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
NameRequiredDescription
userYesProfile username.
limitNo1-100.
cursorNopagination.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
FieldRequiredDescription
userYesProfile username.
subjectYesHandle or DID of the account to follow the activity of.
postNotrue to be notified of its posts. Default false.
replyNotrue 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 (429 bluesky_read_rate_limited) and the shared ceiling (503 bluesky_read_capacity).
  • Errors use the same shape and error_code values as Bluesky Reads. One more applies to the write endpoints (mark as seen, update preferences, activity subscriptions): 503 bluesky_notification_writes_disabled, when changing notification settings is temporarily disabled. Retry later.