Tools

Seven tools for read-only access to the public Bluesky/AT Protocol AppView — no authentication required:

bsky_search_posts

Full-text search across public Bluesky posts.

• Filters: author handle, language (BCP-47), hashtag, date range (since/until), and sort order (top or latest)
• Identifier, language, and date inputs are pattern-validated before the upstream call — a malformed handle, DID, AT-URI, language tag, or date fails locally with the expected shape instead of a generic upstream 400. Language is checked for BCP-47 shape only, matching Bluesky itself: a well-formed tag naming no indexed language returns unfiltered results rather than an error, and the field description says so
• When Bluesky rejects a parameter anyway, its own explanation is surfaced as the error reason and recovery hint instead of a bare Status: 400
• Returns posts with text, author, engagement counts (likes/reposts/replies/quotes), embeds, AT-URIs, and timestamps
• hitsTotal when available, reported as the bound it is — Bluesky caps the count at 10,000, so exactly 10,000 means "at least 10,000" and both the field description and the rendered header say so
• Truncation is disclosed (truncated, shown, cap, and guidance) in both structuredContent and the content[] trailer when more posts match than came back. A returned cursor alone does not trigger it — Bluesky sends one on every non-empty response, exhausted or not, so hitsTotal is what settles whether the page was cut short
• Pagination via opaque cursor; up to 100 results per call
• Embeds normalized into a flat union: images (also covers app.bsky.embed.gallery), external (link cards), record (quoted posts), video, unknown
• A quoted post carries its own attachments under embeds, so a quote of an image post is not reduced to a line of text, alongside media for anything the quoting post attached beside the quote. The rendered output names which post each block belongs to, since the two belong to different accounts
• Quote nesting is followed three levels down, which is deeper than the AppView has been seen to hydrate. A quote at that bound reports the attachments it did not carry through as omittedEmbeds and says so in the rendered text, so it never reads as a quote that had none
• A quote that cannot be read — deleted, blocked, detached — or that points at a feed generator, list, starter pack, or labeler rather than a post carries recordKind naming the case, instead of arriving as an empty quote
• Moderation labels surfaced as-is — not filtered

bsky_get_profile

Fetch a Bluesky actor's public profile by handle or DID.

• Returns displayName, handle, DID, description, pronouns, website, follower/following/post counts, avatar URL, moderation labels, and pinned post AT-URI
• website is the one link a profile carries in a field of its own rather than inside the bio; both it and pronouns are absent for accounts that set neither
• The bio is rendered as a blockquote — it is text the account holder wrote, and can carry markdown of its own. The display name and pronouns render inside lines the server writes, with their line breaks folded to spaces, so neither can open a heading of its own
• The resolution step for handle↔DID — use before tools that require a DID or AT-URI when you only have a handle

bsky_get_author_feed

A user's recent feed ordered newest-first — their own posts and their reposts.

• Filter by post type: posts_with_replies, posts_no_replies (excludes replies), posts_with_media, or posts_and_author_threads. None of them exclude reposts — the AppView has no repost filter
• Reposts carry repostedBy and repostedAt; author always names whoever wrote the post
• Because limit counts reposts too, a page from an account that reposts heavily holds far fewer of that account's own posts than the limit suggests — 30 items from one such account came back as 10 originals and 20 reposts. The response reports originalPosts and reposts whenever a repost is present, so the yield is stated rather than reconstructed by counting
• Returns posts with full text, engagement counts, embeds, and AT-URIs for thread drilling
• Pagination via cursor

bsky_get_post_thread

Fetch the conversation for a post by AT-URI.

• Returns the root post, parent chain (upward), and nested reply tree (downward)
• Configurable depth (reply tree depth, default 6, max 10 — Bluesky returns no more than 10 levels however deep the request) and parent_height (parent chain height, default 80, max 100)
• Bluesky holds replies back past a per-post limit and exposes no way to page the rest, so a thread with thousands of replies commonly comes back with a few hundred. Any node returning fewer replies than its own replyCount carries truncated: true with unreturnedReplies and a truncationReason: "depth" (the tree ends there — fetch that node's AT-URI as its own thread to continue) or "unavailable" (no request closes the gap). The response totals the difference for the whole thread
• Read those totals as an upper bound on what is missing, not a count of readable replies — Bluesky's reply counter keeps including replies that have left the index, so a difference of one or two often means nothing is left to fetch
• The parent chain is disclosed the same way. Bluesky stops the chain at parent_height and gives no signal that it did, so the topmost post returned would otherwise be indistinguishable from the start of the conversation. When it is not, that node carries parentChainTruncated: true and the response names its AT-URI — unlike the reply shortfall this one is fully recoverable, since parent_height is honored level for level and fetching that node as its own thread walks further up
• Reply depth rides the author heading (### ↳2 Name (@handle) — two levels below the top-level reply it descends from) rather than a left margin, so a nested reply stays readable markdown. Indenting instead would push every line below the second level past four spaces, which renders the whole nested half of a thread as a code block. The number is stated rather than repeated as a glyph, since a reply can sit nine levels down and a run of nine arrows has to be counted to be read
• Surfaces the author's reply gate when one is set: who may reply, and the AT-URIs of replies the author hid
• Deleted posts surface as notFound: true and posts hidden by a block as blocked: true; both keep the AT-URI Bluesky reported
• AT-URIs come from bsky_search_posts or bsky_get_author_feed

bsky_get_follows

Fetch social graph edges for an account.