Skip to main content

Bluesky Chat

Bluesky-only chat endpoints, on top of Direct Messages (/dms/send and /dms/conversations with platform=bluesky). They act on the Bluesky account connected to the profile in user, and need the same thing as Bluesky DMs: an app password created with "Allow access to your direct messages" (otherwise 403 bluesky_dm_scope_missing, see how to fix it).

All endpoints take Authorization: Apikey your-api-key-here. user goes in the query string for GET and in the JSON body otherwise. Errors use the same error_code values as Bluesky DMs.


Chat status​

GET /api/uploadposts/dms/bluesky/status?user=my-profile

{"success": true, "platform": "bluesky", "chat_disabled": false, "can_create_groups": true, "group_member_limit": 100}
  • chat_disabled: Bluesky disabled chat for this account (it cannot send messages).
  • can_create_groups: new Bluesky accounts cannot create group chats yet.
  • group_member_limit: the largest group Bluesky allows.

Notification settings​

GET /api/uploadposts/dms/bluesky/preferences?user=my-profile and POST /api/uploadposts/dms/bluesky/preferences:

{"user": "my-profile", "chat": {"include": "follows", "push": true}, "chat_request": {"push": false}}
  • chat: notifications for messages in accepted conversations. chat_request: for message requests.
  • include: all or follows (only from accounts you follow). push: true or false.
  • Send only what you want to change; whatever you leave out keeps its current value.

Both answer {"success": true, "platform": "bluesky", "preferences": {"chat": {"include", "push"}, "chat_request": {"include", "push"}}}.

Export the chat history​

GET /api/uploadposts/dms/bluesky/export?user=my-profile

Downloads every conversation and message of the account as JSON Lines (application/jsonl, one Bluesky object per line, as Bluesky exports it), streamed as a file named <handle>-chat-export.jsonl. It contains other people's messages: keep it private.

  • Only the account owner can export, with their own API key or session. A team member acting for the account (X-Act-As-User) gets 403 bluesky_owner_only.
  • One export at a time per Bluesky account (409 bluesky_dm_export_in_progress), then a 10-minute pause before the next one (429 bluesky_dm_export_cooldown with Retry-After).
  • A download stops after 4 minutes. If it is cut (time limit, or Bluesky failed midway), the file ends with one last line {"truncated": true, "reason": "deadline"} (or "reason": "upstream_error"): the export is incomplete. A complete export has no such line.

Delete the chat account​

POST /api/uploadposts/dms/bluesky/account/delete

{"user": "my-profile", "confirm": true, "confirm_handle": "brand.bsky.social"}

Deletes the account's Bluesky chat account: every conversation and message, for good. The Bluesky account itself (profile, posts, followers) is not touched.

  • confirm must be true and confirm_handle the connected Bluesky handle, or the request is refused with 400 confirmation_required.
  • Only the account owner can do it, with their own API key or session (403 bluesky_owner_only otherwise). Every attempt is recorded.
  • This action is not enabled yet: it answers 403 bluesky_chat_delete_disabled.

Changing the account's email or handle is not possible through Upload-Post: Bluesky only allows it with the account's main password, never with an app password.


Group chats (experimental)​

Bluesky marks its group chat API as under active development and unstable. These endpoints follow it, every answer carries "experimental": true, and the shapes may change when Bluesky changes them. Group chats are not generally available yet: until they are, every endpoint below answers 403 bluesky_dm_experimental_disabled.

Group conversations also show up in GET /dms/conversations?platform=bluesky (kind: "group" and a group block), you send to them with conversation_id, and an invitation is a DM attachment {"type": "join_link", "code": "..."}.

Method and pathBody / queryWhat it does
POST /api/uploadposts/dms/bluesky/groupsname (up to 50 characters), members (1-100 handles or DIDs), optional idempotency_keyCreates a group. The members get a request they have to accept. Every invited member counts as one DM against your daily quota (all or nothing).
GET /api/uploadposts/dms/bluesky/groups?subject=subject: handle or DID; limit, cursorGroups you share with someone.
PATCH /api/uploadposts/dms/bluesky/groups/<conversation_id>name and/or locked (true / false)Renames the group, or locks it (nobody can post) and unlocks it. Owner only.
GET /api/uploadposts/dms/bluesky/groups/<conversation_id>/memberslimit, cursorEvery member.
POST / DELETE same pathmembers: handles or DIDsAdds members (one DM of quota per member) or removes them. Owner only.
POST /api/uploadposts/dms/bluesky/groups/<conversation_id>/join-linkaction: create, edit, enable or disable; require_approval (boolean), join_rule (anyone or followed_by_owner)Manages the group's invitation link.
GET /api/uploadposts/dms/bluesky/groups/<conversation_id>/join-requestslimit, cursorPending requests to join (owner).
POST same pathaction: approve or reject with member, mark_read, or withdraw (your own pending request to that group)Answers join requests.
GET /api/uploadposts/dms/bluesky/join-links?codes=a,bup to 50 codesPreviews of join links: status active (with name, owner, member count), disabled or invalid.
POST /api/uploadposts/dms/bluesky/join-linkscodeAsks to join a group; status is joined or pending.

Creating a group is not idempotent on Bluesky (the same call twice makes two groups). Upload-Post makes it idempotent for 10 minutes: the same idempotency_key, or without one the same name and members, returns the group already created with "idempotent_replay": true. If Bluesky did not confirm a create (504 bluesky_group_create_unconfirmed), the group may exist: list your conversations with kind=group before trying again, or send a new idempotency_key.

curl -X POST https://api.upload-post.com/api/uploadposts/dms/bluesky/groups \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "name": "Launch team", "members": ["alice.bsky.social", "bob.bsky.social"],
"idempotency_key": "launch-team-2026"}'
{
"success": true,
"platform": "bluesky",
"experimental": true,
"conversation_id": "3l5uabcd2s42a",
"group": {"conversation_id": "3l5uabcd2s42a", "name": "Launch team", "member_count": 3, "member_limit": 100,
"lock_status": "unlocked", "locked_by_moderation": false, "created_time": "2026-11-14T10:00:00+0000",
"experimental": true, "members": [{"id": "did:plc:...", "username": "alice.bsky.social"}]}
}

Group errors​

Statuserror_codeMeaning
403bluesky_dm_experimental_disabledGroup chats are not enabled.
403bluesky_group_not_ownerOnly the group's owner can do that.
403bluesky_group_not_allowedBluesky does not let this (new) account create groups yet.
403bluesky_recipient_unavailableA member does not accept group chats or a block exists.
409bluesky_group_lockedThe group is locked (by its owner or by Bluesky moderation).
409bluesky_group_fullThe group reached its member limit.
409bluesky_group_create_in_progressThe same group is being created by another request right now.
409 / 504bluesky_group_create_unconfirmedA create was not confirmed by Bluesky: check before creating again.
404 / 409bluesky_join_link_not_found, bluesky_join_link_exists, bluesky_join_link_enabled, bluesky_join_link_disabledJoin link state.
404bluesky_join_request_not_foundNo pending join request.
429dm_daily_limitYour daily DM quota does not cover every member you invite (one DM each); nothing was done.
400bluesky_dm_lookups_exceededMore than 10 members given by handle in one request: give the rest by DID.