Bluesky API for Posting in 2026: Auth, Limits and Code

There is nothing to buy and no key to request. The official Bluesky API quick start goes straight from installing a library to logging in with a handle and password: no developer account, no app registration and no plan to pick. Compare that with X, where posting is billed by usage, or LinkedIn, where Company Page access needs an application and a review (see our breakdown of LinkedIn API pricing and access tiers).

What people call a "Bluesky API key" is one of two things. For bots, scripts and command-line tools, it is an app password: a separate password the account owner creates in Bluesky's settings, which you can revoke without touching the main login. For apps where other people sign in, Bluesky asks you to implement OAuth instead. Its OAuth documentation says applications with their own end-user login flow should use OAuth, while single-purpose apps such as bots or CLI tools may keep using app passwords. atproto OAuth involves DPoP, PKCE and PAR, so use one of the SDKs listed there rather than writing the flow by hand.

Posting is two calls. com.atproto.server.createSession takes the handle and the app password and returns the account's DID plus two tokens: accessJwt, which authenticates requests and expires quickly, and refreshJwt, which lasts longer and is only used to get a new access token. Then com.atproto.repo.createRecord writes a record of type app.bsky.feed.post to the account's repository. The only required fields are text and createdAt. The response returns the post's at:// URI and its CID, and that URI is your proof the post exists.

# 1. Log in once with the handle and an app password
curl -X POST https://bsky.social/xrpc/com.atproto.server.createSession \
  -H "Content-Type: application/json" \
  -d '{"identifier": "yourhandle.bsky.social", "password": "xxxx-xxxx-xxxx-xxxx"}'
# -> { "did": "did:plc:...", "accessJwt": "...", "refreshJwt": "...", ... }

# 2. Write the post record
curl -X POST https://bsky.social/xrpc/com.atproto.repo.createRecord \
  -H "Authorization: Bearer $ACCESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "did:plc:...",
    "collection": "app.bsky.feed.post",
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "Hello from the API",
      "createdAt": "2026-10-31T13:00:00Z",
      "langs": ["en"]
    }
  }'
# -> { "uri": "at://did:plc:.../app.bsky.feed.post/3k...", "cid": "bafy..." }

# 3. Later: swap the refresh token for a new pair instead of logging in again
curl -X POST https://bsky.social/xrpc/com.atproto.server.refreshSession \
  -H "Authorization: Bearer $REFRESH_JWT"

Two details from the posts guide save debugging time. Write createdAt as UTC with a trailing Z, which the docs prefer over +00:00. And bsky.social is the entry point for accounts hosted by Bluesky; an account on a self-hosted PDS lives somewhere else, so read the PDS address from the DID document the session returns instead of hardcoding the host. In production you would normally use an SDK (@bsky/sdk for TypeScript, atproto for Python, indigo for Go), which also refreshes the session for you.

The limits live in the lexicons, the JSON schemas that define each record type. These are the numbers that matter when you validate a post before sending it, taken from the app.bsky.feed.post lexicon and the image and video embed lexicons next to it:

Media is never inlined in the post. You upload each file with com.atproto.repo.uploadBlob, get back a blob reference, and put that reference in the embed together with alt text and an aspect ratio. The docs recommend stripping EXIF metadata before upload, which today is the client's job. For video, the video upload guide recommends sending the file to video.bsky.app first and polling app.bsky.video.getJobStatus until it returns the blob. If you skip that and upload the video as a plain blob, processing only starts after the post goes out, and readers see a missing video for a few seconds.

Because the text field is plain text. A URL, an @mention or a #hashtag only becomes interactive when the record carries a facet pointing at that span of text. The facet lexicon defines three features: #link with a uri, #mention with the account's DID (so you resolve the handle first with com.atproto.identity.resolveHandle), and #tag for hashtags, capped at 64 graphemes.

The common bug is the index. byteStart and byteEnd count bytes of the UTF-8 encoded text, start inclusive and end exclusive. JavaScript string indexes count UTF-16 code units, so any accent or emoji before the link shifts the facet and the wrong characters turn blue. Encode the text with TextEncoder (or text.encode("utf-8") in Python) and search the bytes, not the string. If a handle does not resolve, the posts guide suggests skipping that mention and leaving it as plain text rather than failing the post.

Bluesky publishes its numbers on the rate limits page, and requests over a limit get HTTP 429. Writes are counted in points per account: creating a record costs 3 points, updating 2 and deleting 1.

For a posting tool, the write limit is rarely the problem. The session limit is. A cron job that calls createSession before every post runs out at 300 logins a day for that account, and the error looks like an auth failure. Store the refreshJwt, call com.atproto.server.refreshSession when the access token expires, and save the new pair it returns, since the refresh token rotates. The IP limit matters when many accounts post from one server. Our social media API rate limits reference puts these numbers next to the other networks.

The post record has no schedule field, and createRecord publishes the moment it succeeds. So scheduling on Bluesky means running something that holds a valid session and calls createRecord at the chosen time: a queue with delayed jobs, a retry policy for 429s, and a place to store the returned URI so you can show the post went out. createdAt is the time the record says it was written; it does not delay publication.

If you would rather not run that part, this is where PostGate's Bluesky integration fits. Accounts connect with an app password through a hosted page, sessions are refreshed on a schedule, and links, hashtags and resolvable @mentions in the text are turned into facets automatically. You send one scheduled post to the PostGate API and get per-destination delivery status back. One limit to know before you build on it: PostGate publishes Bluesky posts with text and up to four images today, and does not publish Bluesky video yet.

• Count text in graphemes and reject anything over 300 before calling the API.
• Build facets from UTF-8 byte offsets and test them with accented text and emoji before the link.
• Resize images under 1 MB, strip EXIF, and send alt text and an aspect ratio with every image.
• Log in once per account and refresh the session; never call createSession per post.
• Read the PDS host from the session instead of assuming bsky.social.
• For video, check the account email is verified and pre-process through video.bsky.app.
• Back off on HTTP 429 and keep the returned at:// URI as the record of each post.
• Use OAuth, not app passwords, if people outside your team sign in to your app.