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.
| Field | Type | Required | Values and constraints | Description |
|---|---|---|---|---|
| langs | string[] | No | BCP-47 language tags, e.g. ["en"], ["en-US", "es"] | Language tags for the post. Defaults to ["en"] when omitted. |
| altText | string[] | No | One entry per image, same order as mediaItems | Alt text for each image. Strongly encouraged for accessibility. |
Captured source contract; origin modularized as {{API_BASE_URL}}.
| Limit | Value |
|---|---|
| Character limit | 300 graphemes per post |
| Images per post | 4 |
| Image size | 1 MB max each |
| Video / GIF | Not currently supported |
Captured source contract.
| Failure | Cause | Check and corrective action |
|---|---|---|
| Authentication error on next post | User revoked the app password in Bluesky settings | Generate a new Bluesky app password and reconnect via POST {{API_BASE_URL}}/v1/connect/bluesky/auth; update accountId from the new integration.id. |
| Image rejected | Image over 1 MB | Compress or resize the image to 1 MB or less before retrying. |
| Image rejected | More than 4 images in mediaItems | Reduce mediaItems to at most 4 images. |
| Post rejected | Content exceeds 300 graphemes | Shorten content and recount graphemes before retrying. |
| Media rejected | Video or GIF attached | Remove 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 | Output | Use |
|---|---|---|
| integration.id from connect response | accountId in POST {{API_BASE_URL}}/v1/posts platforms entry | Identifies the connected Bluesky account for publishing. |
| platformPostId in publish response | at://did:plc:.../app.bsky.feed.post/... identifier | Stable Bluesky post identifier for reconciliation. |
| platformPostUrl in publish response | https://bsky.app/profile/did:plc:.../post/... URL | Public 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"].
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"
}'{
"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..."
}
}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
}'{
"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..."
}
]
}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": "bluesky",
"accountId": "<integration id>",
"platformSpecificData": {
"langs": ["en", "es"]
}
}{
"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..."
}
}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
}'