Skip to content

Bluesky Post API

The Bluesky Post API publishes text and image posts to Bluesky via the AT Protocol. Unlike platforms that use OAuth redirects, Bluesky uses a Bluesky app password flow: the account owner generates an app password in Bluesky settings and submits it once through the connect endpoint. This guide covers the exact connect and publish contract, platform-specific fields, limits, and token refresh behavior so you can validate a request before sending it.

Overview: AT Protocol and app password flow

Bluesky publishing goes through the AT Protocol, and the connection model is the key difference from OAuth-based platforms. The end user creates a Bluesky app password at https://bsky.app/settings/app-passwords, gives it a recognizable name such as the application name, and copies the four-group token in the form xxxx-xxxx-xxxx-xxxx. Leave the option to allow access to direct messages unchecked, because the API never reads or sends direct messages. A regular account password must not be used here: Bluesky's anti-abuse system blocks regular account passwords used over the API, so the app password is the only supported credential for this flow.

Connect account: generate app password, then POST {{API_BASE_URL}}/v1/connect/bluesky/auth

Follow the three steps in order: generate the app password, connect the account, then publish. For the connect step, send POST {{API_BASE_URL}}/v1/connect/bluesky/auth with the x-access-key header and a JSON body containing identifier and password. The identifier field accepts either a handle such as alice.bsky.social or a DID such as did:plc:...; choose a handle when you already know the public handle, and choose a DID when you need a stable identifier that does not depend on the handle. The password field must contain the Bluesky app password generated in step one. On success the response returns success, message, and an integration object; save integration.id because that value is the accountId you pass when posting. Check displayName and platformUserId in the response to confirm you connected the intended account before storing the id.

Publish a post: POST {{API_BASE_URL}}/v1/posts with worked request and response

To publish, send POST {{API_BASE_URL}}/v1/posts with content, a platforms array, and publishNow set to true for immediate publication. Each platform target uses platform set to bluesky and accountId set to the integration.id saved from the connect response. Any web address included in your text is recognised automatically and wrapped as a Bluesky facet, which makes it tappable in the finished post, so separate link fields are unnecessary. On success the response returns success, status set to published, and a platforms array whose Bluesky entry contains success, platformPostId in at:// form, and platformPostUrl. Store platformPostId and platformPostUrl together with your own post record so you can link back to the published post and reconcile retries. If the Bluesky entry reports success as false, treat the post as not published on Bluesky even if other platform targets in the same request succeeded.

Images and alt text using mediaItems and altText

Attach images through the standard mediaItems array on the post request, with each item using type image and a url. A Bluesky post accepts up to 4 images, and each image must be 1 MB or less, which is a hard limit of the Bluesky API. Before publishing, check the count and the byte size of every file; a fifth image or an image over 1 MB will fail the preflight check described below. Provide alt text through platformSpecificData.altText as a string array in the same order as mediaItems, so the first entry describes the first image and the second entry describes the second image. Alt text is strongly encouraged for accessibility, and keeping the order aligned is the most common source of mismatched descriptions, so verify the pairing whenever you reorder mediaItems.

Languages using langs and BCP-47 tags

Declare the post language through platformSpecificData.langs using BCP-47 tags, for example en, en-US, or es. Pass langs as a string array on the Bluesky platform target, such as ["en", "es"] for a bilingual post. When langs is omitted it defaults to ["en"], so single-language English posts can omit the field entirely. Validate each tag before publishing: use a well-formed BCP-47 tag, keep the array order meaningful, and do not mix free-text language names into the field. If the content is primarily in another language, set langs explicitly rather than relying on the English default.

Platform-specific data field map

The platformSpecificData object is passed on the Bluesky entry inside the platforms array, not at the top level of the post request. It currently carries two optional fields: langs for BCP-47 language tags and altText for per-image alt text. Both fields are optional, but their semantics are strict: langs defaults to ["en"] when omitted, and altText entries must align in order with mediaItems. Keep platformSpecificData scoped to the Bluesky target so fields intended for Bluesky do not leak into other platform targets in a multi-platform request. The field map table below is the authoritative summary of types, requiredness, and ordering for this object.

Limits and failure matrix

Run a local preflight checklist before every publish: count graphemes and confirm the total is within 300 graphemes, confirm mediaItems contains at most 4 images, confirm each image is 1 MB or less, confirm altText length and order match mediaItems, and confirm every langs entry is a valid BCP-47 tag. The failure matrix below maps each common failure to its cause and the corrective action. A revoked app password produces an authentication error on the next post, which requires reconnection through POST {{API_BASE_URL}}/v1/connect/bluesky/auth rather than a retry of the post. Video and GIF attachments are not currently supported for Bluesky, so remove those media items instead of attempting to publish them.

Token refresh and reconnection

Bluesky access tokens expire after about 2 hours. Renewal happens in the background: the refresh token obtained from createSession is used to obtain a fresh pair, and that new pair is stored each time a renewal completes. As long as the app password remains valid on the account, the connection therefore continues without manual intervention. You do not need to schedule refresh calls or store tokens yourself. If the user revokes the app password in Bluesky settings, the next post returns an authentication error; in that case ask the user to generate a new app password and reconnect through the same POST {{API_BASE_URL}}/v1/connect/bluesky/auth endpoint, then update the stored accountId from the new integration.id before retrying the post.

Bluesky platformSpecificData field map
FieldTypeRequiredValues and constraintsDescription
langsstring[]NoBCP-47 language tags, e.g. ["en"], ["en-US", "es"]Language tags for the post. Defaults to ["en"] when omitted.
altTextstring[]NoOne entry per image, same order as mediaItemsAlt text for each image. Strongly encouraged for accessibility.

Captured source contract; origin modularized as {{API_BASE_URL}}.

Bluesky post limits
LimitValue
Character limit300 graphemes per post
Images per post4
Image size1 MB max each
Video / GIFNot currently supported

Captured source contract.

Failure matrix and preflight checks
FailureCauseCheck and corrective action
Authentication error on next postUser revoked the app password in Bluesky settingsGenerate a new Bluesky app password and reconnect via POST {{API_BASE_URL}}/v1/connect/bluesky/auth; update accountId from the new integration.id.
Image rejectedImage over 1 MBCompress or resize the image to 1 MB or less before retrying.
Image rejectedMore than 4 images in mediaItemsReduce mediaItems to at most 4 images.
Post rejectedContent exceeds 300 graphemesShorten content and recount graphemes before retrying.
Media rejectedVideo or GIF attachedRemove video/GIF items; video and GIF are not currently supported for Bluesky.

Derived from captured source limits and token refresh behavior; no additional error codes invented.

Input contract and response mapping
InputOutputUse
integration.id from connect responseaccountId in POST {{API_BASE_URL}}/v1/posts platforms entryIdentifies the connected Bluesky account for publishing.
platformPostId in publish responseat://did:plc:.../app.bsky.feed.post/... identifierStable Bluesky post identifier for reconciliation.
platformPostUrl in publish responsehttps://bsky.app/profile/did:plc:.../post/... URLPublic link to the published post.

Captured source contract.

Frequently asked questions

Should identifier be a handle or a DID?

Use the handle when you know the public handle, such as alice.bsky.social. Use a DID, such as did:plc:..., when you need a stable identifier that does not depend on the handle.

Can I connect with my regular Bluesky account password?

No. Use a Bluesky app password generated in account settings. Regular account passwords used over the API are blocked by Bluesky's anti-abuse system.

What happens if the app password is revoked?

Generate a new app password and reconnect through POST {{API_BASE_URL}}/v1/connect/bluesky/auth, then update the stored accountId from the new integration.id before retrying the post.

How many images can a Bluesky post contain?

A post can contain up to 4 images, each 1 MB or less. Video and GIF are not currently supported.

How do I declare the language of a post?

Set platformSpecificData.langs to BCP-47 tags such as ["en", "es"]. When omitted, langs defaults to ["en"].

Connect a Bluesky account with an app password
curl -X POST {{API_BASE_URL}}/v1/connect/bluesky/auth \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "alice.bsky.social",
    "password":   "xxxx-xxxx-xxxx-xxxx"
  }'
Connect response showing integration id
{
	"success": true,
	"message": "Bluesky connected.",
	"integration": {
		"id": "65ab...",
		"platform": "bluesky",
		"platformUserId": "did:plc:...",
		"displayName": "@alice.bsky.social",
		"imageUrl": "https://example.com/avatar.png",
		"createdAt": "2026-04-24T..."
	}
}
Publish a text post to Bluesky
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "bluesky", "accountId": "<integration id>" }
    ],
    "publishNow": true
  }'
Publish response with platform post id and url
{
	"success": true,
	"status": "published",
	"platforms": [
		{
			"platform": "bluesky",
			"success": true,
			"platformPostId": "at://did:plc:.../app.bsky.feed.post/3kabc...",
			"platformPostUrl": "https://bsky.app/profile/did:plc:.../post/3kabc..."
		}
	]
}
Publish a post with images and alt text
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "bluesky",
        "accountId": "<integration id>",
        "platformSpecificData": {
          "altText": ["Pink sunset over the bay", "Same scene 30 minutes later"]
        }
      }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/sunset-1.jpg" },
      { "type": "image", "url": "https://cdn.example.com/sunset-2.jpg" }
    ],
    "publishNow": true
  }'
Platform target with language tags
{
	"platform": "bluesky",
	"accountId": "<integration id>",
	"platformSpecificData": {
		"langs": ["en", "es"]
	}
}
Connect response with integration id
{
	"success": true,
	"message": "Bluesky connected.",
	"integration": {
		"id": "65ab...",
		"platform": "bluesky",
		"platformUserId": "did:plc:...",
		"displayName": "@alice.bsky.social",
		"imageUrl": "{{MEDIA_BASE_URL}}/...",
		"createdAt": "2026-04-24T..."
	}
}
Publish a basic Bluesky post
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "bluesky", "accountId": "<integration id>" }
    ],
    "publishNow": true
  }'