canonical: https://jentic.com/apis/bsky.app/bsky # Bsky App Bluesky AT Protocol API Bluesky's HTTP API exposes the AT Protocol (atproto) as XRPC endpoints for posting, reading feeds, managing actor profiles, and handling notifications on the bsky.social network. The spec covers session creation, token refresh, timeline and author feed retrieval, post threading, record create and delete on a repository, profile lookup, actor search, notifications listing, and binary blob upload. It is the agent-callable surface for building Bluesky bots, scheduled posting tools, feed analytics, and cross-poster integrations. ## For AI agents Authenticate against bsky.social, post records, read timelines and threads, search actors, and upload blobs on the AT Protocol Bluesky network. ## Scope Does not handle direct messages, moderation appeals, or non-Bluesky AT Protocol app views - use for posting, feed reading, and actor lookup on bsky.social only. ## Capabilities - Authenticate a Bluesky handle and obtain access and refresh tokens via createSession - Retrieve the authenticated user's home timeline and any actor's author feed for content monitoring - Create new posts, likes, reposts, and follows by writing to the repository with createRecord - Fetch a full post thread including parent and reply context for conversation analysis - Search for actors by query and resolve their DIDs and profile metadata - List notifications for the authenticated user and mark engagement state - Upload images and other binary blobs for inclusion in posts via uploadBlob ## Use cases ### Cross-Poster from Other Networks Replicate posts from other social networks to Bluesky by authenticating with createSession, uploading any image attachments via uploadBlob, then writing a feed post record with createRecord on the app.bsky.feed.post collection. The spec exposes the exact XRPC paths needed, so an agent can implement a one-way bridge in under a day. Token refresh through refreshSession keeps long-running bridges alive without re-prompting for credentials. Example prompt: Call createSession with the handle and app password, upload the post image with uploadBlob, then call createRecord with collection app.bsky.feed.post and the text and embed payload ### Feed and Thread Analysis Analyse public Bluesky discussions by pulling an actor's author feed via getAuthorFeed and resolving any thread of interest with getPostThread. Useful for brand mention monitoring, research on conversation structure, and powering dashboards that track replies and engagement. The endpoints return structured records with timestamps and reply references that can be loaded directly into analytics pipelines. Example prompt: Call getAuthorFeed for the target handle, then call getPostThread for each post URI to retrieve full reply context ### Notifications and Engagement Bot Build a notification handler that polls listNotifications, identifies new replies and mentions, and responds with createRecord to post a reply or follow back. Bearer access tokens from createSession authorise the writes, and refreshSession keeps the bot running across the standard token lifetime. Suited to community management bots, support deflection on Bluesky, and engagement automations. Example prompt: Call listNotifications with seenAt set to the last poll time, filter for reply and mention events, then post a reply using createRecord ### AI Agent Posting Through Jentic Allow an AI agent to post to Bluesky on behalf of a user without ever holding the app password. The agent searches Jentic for posting intent, loads the createSession and createRecord schemas, and executes them in sequence. Jentic's vault stores the Bluesky handle and app password, exchanges them for a session token, and forwards only the bearer token at execution time so credentials stay isolated from the agent's context. Example prompt: Use Jentic to search 'post to Bluesky', load createSession then createRecord, and execute with collection app.bsky.feed.post and the agent's drafted text ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /com.atproto.server.createSession | Authenticate a handle and return access and refresh tokens | | POST | /com.atproto.repo.createRecord | Create a post, like, repost, or follow record | | GET | /app.bsky.feed.getTimeline | Get the authenticated user's home timeline | | GET | /app.bsky.feed.getPostThread | Fetch a full post thread including replies | | GET | /app.bsky.actor.getProfile | Look up a profile by handle or DID | | POST | /com.atproto.repo.uploadBlob | Upload a binary blob for use in a post | | GET | /app.bsky.notification.listNotifications | List notifications for the signed-in account | ## Key resources - **Sessions** — Create and refresh authenticated sessions with bsky.social using a handle and app password - **Feeds** — Retrieve the home timeline, an author's feed, and full post threads - **Repository Records** — Create and delete records (posts, likes, follows, reposts) on the user's repository - **Actors** — Look up profile data and search for actors by query - **Notifications** — List notifications for the signed-in user - **Blobs** — Upload binary attachments such as images for use in posts ## Why Jentic - **Setup:** Wiring the Bluesky AT Protocol API by hand means exchanging your handle and app password for a session token at createSession, refreshing that bearer token, and learning the XRPC NSID method names yourself. Through Jentic you install once, import the Bluesky AT Protocol API from the API Directory, store the handle and app password once, and your agent calls it. - **Permission scoping:** Bluesky's XRPC calls address records by NSID method and request body, not by a resource id in the URL path, so scoping is operations-only: limit the agent to the operations it needs, such as reading the timeline and creating a post record. You choose which operations it may call, so uploading blobs is not included unless you add it. - **Credential handling:** Your Bluesky handle and app password are stored once, encrypted, by your own Jentic One instance, which exchanges them for a session token server-side and injects only the bearer token at execution time. The password never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'post to Bluesky', and Jentic returns the matching XRPC operation with its Lexicon-derived schema so the agent calls createRecord without browsing the reference docs. ## Related APIs - **Buffer API** — Schedules posts that are then published to Bluesky and other networks - **Bruzu API** — Generates the share image that Bluesky posts embed - **Buddyyen API** — Alternative social media touchpoint for posting and audience interaction ## FAQ ### What authentication does the Bluesky API use? Bluesky uses HTTP bearer authentication. You exchange a handle and app password for an access token via createSession at /com.atproto.server.createSession, then send Authorization: Bearer on subsequent requests. Through Jentic the handle and app password are stored in the encrypted vault and the session exchange runs server-side, so the raw credentials never enter the agent's context. ### Can I post to Bluesky with this API? Yes. Authenticate with createSession, then call createRecord at /com.atproto.repo.createRecord with collection app.bsky.feed.post and a record containing the text and createdAt timestamp. To attach an image, first call uploadBlob and reference the returned blob in the embed field of the post record. ### What are the rate limits for the Bluesky API? Bluesky enforces per-account and per-IP rate limits that vary by endpoint; createSession is more strictly limited than read endpoints. Limits are not encoded in the spec - check the AT Protocol documentation at docs.bsky.app for current values. When throttled, the API returns a standard error response and clients should back off before retrying. ### How do I fetch a Bluesky thread through Jentic? Install the SDK with pip install jentic, then search for 'fetch a Bluesky thread', load the getPostThread schema, and execute it with the post URI as the uri parameter. Jentic resolves /app.bsky.feed.getPostThread, attaches the bearer token from the active session, and returns the parent and replies. ### Is the Bluesky API free? Yes. Bluesky is free to use with a registered account and an app password generated from the Bluesky settings. There is no paid tier for API access at this time, though rate limits apply. ### Why does Bluesky use XRPC paths instead of REST? Bluesky is built on the AT Protocol, which defines its API surface as XRPC procedures and queries identified by NSIDs like com.atproto.repo.createRecord. The spec maps each NSID to a path so OpenAPI tooling and Jentic can call them like normal HTTP endpoints, but the request and response shapes follow the underlying Lexicon schemas. ### Can I limit what my agent is allowed to do with the Bluesky AT Protocol API? Yes. Because Bluesky's XRPC calls address records by NSID method and request body rather than by a resource id in the URL, scoping is operations-only, and your self-hosted Jentic One instance lets you decide which operations the agent may call. You control your own rules, so you can allow it to read the timeline with getTimeline and create a post with createRecord while withholding uploadBlob or deleteRecord until you add them. The handle and app password stay under your control and are exchanged for a session token server-side, so the agent only ever calls the operations you have granted.