Endpoints
{post_id} is the post’s AT URI, for example at://did:plc:abc123xyz/app.bsky.feed.post/3kq2example. It is targets[].platform_post_id on a post you published through SocialAPI, and id in GET /v1/inbox/comments. An AT URI contains / and :, so URL-encode it in the path: at%3A%2F%2Fdid%3Aplc%3Aabc123xyz%2Fapp.bsky.feed.post%2F3kq2example. {comment_id} and comment_id take the reply’s sapi_cmt_ ID or its AT URI (platform_id). The sapi_cmt_ ID needs no encoding. See IDs.
The like and private reply endpoints exist for every platform, but Bluesky supports neither: see What Bluesky does not support.
Your first reply
List the replies to a post.account_id is required:
comment_id in the response is the new reply’s sapi_cmt_ ID.
List replies
GET /v1/inbox/comments/{post_id} returns the replies to the post, up to 6 levels below it and at most limit of them, as one flat list. Each reply is followed by the replies below it, in the order Bluesky returns the thread.
The list has one page:
has_more is always false and next_cursor is always empty. Replies after the first limit are not returned, so pass limit=100 to read as many as possible. On a long thread Bluesky can return fewer replies than exist, and there is no way to page past them. The YouTube filters moderation_status, order, and q do not filter Bluesky replies, but an invalid value still returns 400 validation.field_invalid.
Fields that differ from the shared comment fields:
Replies below one reply
GET /v1/inbox/comments/{post_id}/{comment_id}/replies returns the replies below one reply, up to 6 levels below it, in the same shape. The default limit is 10, and a value above 100 is treated as 100. The list has one page, like the post list. To read the replies below one reply, including those deeper than 6 levels below the post, call this endpoint on a reply whose has_replies is true.
Posts with replies
GET /v1/inbox/comments?account_id={account_id} lists the account’s posts with comment_count (Bluesky’s reply count) and like_count. id is the post’s AT URI, the value for {post_id}. thumbnail is null on Bluesky. The list holds the posts you published through SocialAPI and the posts SocialAPI imported: see Retrieve posts. The parameters are in List posts with comments.
Reply to a post or a reply
POST /v1/inbox/comments/{post_id} publishes a reply as the connected account.
A reply to a reply stays in the original post’s thread, directly below the reply you answered. A reply is a Bluesky post, so its text holds at most 300 characters (Bluesky counts each emoji as 1). Bluesky refuses longer text with
400 validation.platform_param.
SocialAPI turns every http:// or https:// address in the text into a link and every #tag that starts the text or follows a space into a hashtag. It does not turn @handle into a mention: the text publishes as plain text and the mentioned account is not notified.
A reply costs 1 interaction credit. When the allowance is used up, the call returns 429 validation.interaction_limit_exhausted. The credit comes back when the call fails with a validation.* error: see When a credit comes back.
Hide and unhide a reply
Hiding a reply takes it out of the thread view for other people on Bluesky. The reply is not deleted: it stays on Bluesky. Only the author of the original post can hide replies to it, at any level of the thread. Hiding or unhiding a reply never changes who can reply to the post: its reply settings on Bluesky stay as they are, including on a post closed to replies.DELETE on the same path and account_id as a query parameter:
- Your threads only. Hiding a reply in a thread another account started returns
403 platform.bluesky.not_thread_owner. - 300 per thread. A thread holds at most 300 hidden replies. Hiding a 301st returns
422 platform.bluesky.hidden_replies_full. Unhide a reply to make room.
Delete your own reply
DELETE /v1/inbox/comments/{post_id}/{comment_id}?account_id={account_id} deletes a reply the connected account wrote. It returns { "success": true } and cannot be undone. Bluesky lets no account delete another account’s reply: deleting one returns 403 platform.bluesky.not_own_record. Hide that reply instead. Deleting costs no credit.
What Bluesky does not support
- Liking a reply.
POSTandDELETE /v1/inbox/comments/{post_id}/{comment_id}/likereturn501 resource.not_supported. - Private replies. Bluesky has no way to send a DM from a reply:
POST /v1/inbox/comments/{post_id}/{comment_id}/private-replyreturns501 resource.not_supported. To message the person, use Bluesky direct messages. - Deleting another account’s reply. Hide it.
- Editing a reply. Delete it and send a new reply.
- Automations. Automations run on Instagram and Facebook only.
Limits
When Bluesky’s write budget is used up, the call fails with
429 platform.bluesky.rate_limit. Wait, then retry. Write points are shared with publishing: see Bluesky limits.
Errors and debugging
Check these in order when a Bluesky comment call fails:401,403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks the scope in Scopes.403 account.permission_missing. The account lacks thecomments.readorcomments.writepermission.error.meta.permissionnames it.400 validation.field_invalidwitherror.meta.fieldset toapp_password. Bluesky no longer accepts the saved app password, for example because it was deleted in Bluesky settings. Create a new app password and connect the account again: see Connect an account.403 account.reconnection_required,401 platform.bluesky.auth. Bluesky rejected the saved credential. Connect the account again.401 platform.bluesky.unauthorized. Bluesky refused the request as unauthorized. If it repeats, connect the account again.403 platform.bluesky.account_takedown. Bluesky suspended the account. Connecting again does not restore access.400 validation.field_required,400 validation.field_invalid. A required field is missing, or a parameter has a wrong value.error.meta.fieldnames it: a value other thanapp_passwordpoints at your request.400 validation.platform_param. Bluesky rejected a parameter, for example reply text over 300 characters or a malformed AT URI.error.messagecarries Bluesky’s reason.403 platform.bluesky.not_thread_owner,422 platform.bluesky.hidden_replies_full. A hide outside your own thread, or past 300 hidden replies.403 platform.bluesky.not_own_record. A delete of another account’s reply.404 resource.not_found. The post or the reply was deleted on Bluesky.409 platform.bluesky.stale_record. The record changed while the request ran. Retry.429 platform.bluesky.rate_limit. Bluesky’s write budget is used up. Wait, then retry.429 validation.interaction_limit_exhausted. Your plan’s interaction allowance is used up: see Plans and usage.501 resource.not_supported. A like or a private reply.503 platform.bluesky.api_error. The request to Bluesky failed, or Bluesky answered with no error name. Retry.
503 platform.bluesky.{error}, where {error} is Bluesky’s error name, and error.message carries Bluesky’s reason. Bluesky’s own codes are in Errors: Bluesky, and the comment codes in Errors.
Scopes
Events
Bluesky sends SocialAPI no notification of new replies, so SocialAPI sends nocomment.received event for a Bluesky account. Read new replies with GET /v1/inbox/comments/{post_id}. See Bluesky webhook events.
Use from an AI agent
The tool list and error shape are in MCP tools.
Related
- Bluesky API: connect the account, mentions, scopes, and the write budget
- Bluesky direct messages: message a person privately
- Bluesky publishing: the posts whose replies you read here
- Comments: the endpoints and fields shared by every platform
- Errors: every Bluesky error code