Skip to content

Post to Bluesky API in 2026: Step-by-Step Guide

Post to Bluesky API workflows let a script publish text, attach an image with image alt text, set language tags, or schedule delivery without implementing the AT Protocol directly. This guide follows the exact request shapes for connecting an account and creating a post, so you can copy each example, replace the placeholders, and check the result before automating it.

What you need

You need an access key for the x-access-key header, a Bluesky account, and a Bluesky app password. The access key identifies your requests, while the app password is the scoped credential used to connect the Bluesky account. Keep both out of public repositories, and treat the access key like a password. Bluesky's native protocol is the AT Protocol, but this workflow uses the single posting endpoint described below instead of requiring you to manage AT Protocol clients, DID resolution, or PDS endpoint selection yourself.

Step 1: Get your API key

Obtain your access key from the Access Keys page in your dashboard. Every request in the examples below sends it in the x-access-key header, as shown in the Access key header example. If a request is rejected for authentication, check first that the header name is exactly x-access-key, that the placeholder has been replaced with a real key, and that no extra whitespace was introduced when copying the command.

Step 2: Generate a Bluesky app password

This connection flow relies on a Bluesky app password because OAuth is not available for third-party posting here. In a web browser, visit your account preferences, locate the security area for app credentials, and create a new one with a recognizable label such as MyApp. Save the generated value, formatted like xxxx-xxxx-xxxx-xxxx, somewhere secure. That credential permits posting for you, yet it leaves your primary password and account deletion controls untouched, and you may withdraw it whenever you wish from that same preferences area. Never place your regular account password in the connect request.

Step 3: Connect your Bluesky account

There is no OAuth redirect for this connection, so you submit the handle or DID and the app password directly. Send a POST request to /v1/connect/bluesky/credentials with identifier and password in the JSON body, as shown in the Connect a Bluesky account with an app password example. The identifier field accepts either a handle such as alice.bsky.social or a DID such as did:plc:abc123. The password field must contain the app password you just generated, not your main account password. The credential is encrypted at rest and decrypted in memory only when calling Bluesky. Capture integration.id from the response and use it as accountId when posting. You can also complete this connection from the dashboard if you prefer a button-based flow.

Step 4: Post to Bluesky

Use POST /v1/posts with content, a platforms array containing platform bluesky and your accountId, and publishNow set to true, as shown in the Publish a Bluesky post now example. That is the complete publish-now request: the post then appears on your Bluesky profile. Before sending, count the content carefully because Bluesky caps posts at 300 characters, and the request returns a clean error if you exceed that limit. A practical failure check is to validate length in your own code first, then treat an over-limit error as a content problem to fix rather than retrying the same payload.

Adding an image with alt text

To attach an image, add mediaItems at the top level and put an altText array inside platformSpecificData for the Bluesky target, as shown in the Publish with an image and image alt text example. The altText entries line up positionally with mediaItems, so the first alt-text string describes the first image, the second describes the second image, and so on. Write image alt text that describes the image itself rather than repeating the caption. If you have multiple images, keep the arrays the same length and in the same order; a mismatch is the most common failure in this step.

Setting the language

Language metadata helps Bluesky route a post to appropriate language feeds. Supply BCP-47 values through langs inside platformSpecificData for the Bluesky target, as shown in the Publish with BCP-47 language tags example. Pass a single tag for a monolingual post or multiple tags, such as es and en, when the post is bilingual. Choose the tags that match the actual languages in the content, because an incorrect tag can send the post to the wrong language feed.

Scheduling a Bluesky post

To schedule instead of publishing immediately, replace publishNow with scheduledFor and timezone, as shown in the Schedule a Bluesky post example. The scheduledFor value in the example is 2026-05-01T14:00:00 with timezone America/New_York, and the post is queued for delivery at that moment. Use publishNow when you want immediate delivery and scheduledFor plus timezone when you want a specific local time. Scheduled and published posts can be reviewed in the Posts dashboard, where you can filter by status, platform, and date. Before relying on a schedule, double-check the timezone string and confirm the intended local time, since a wrong timezone shifts delivery even when the request succeeds.

Cross-post to Bluesky and other platforms

The same POST /v1/posts shape works for cross-posting: add more entries to the platforms array and the same content is sent to each target, as shown in the Cross-post to Bluesky and other platforms example. Each entry carries its own platform and accountId, so Bluesky, Twitter, and LinkedIn can each receive the post in one request. The service adapts content and media to each platform's rules, including Bluesky's 300 characters cap, Twitter's 280-character cap, and LinkedIn's longer-form limit. When cross-posting, check the strictest applicable limit first and confirm that shared mediaItems work for every target before sending.

What's next

You now have the full flow: connect with a Bluesky app password, publish now, add an image with image alt text, set langs, schedule with scheduledFor and timezone, and cross-post through the platforms array. Use the field map and validation matrix below as a pre-flight checklist, then run one real post through the examples before wiring the calls into automation. For the complete field reference, see the Bluesky posting API page and the API docs.

Field map for connect and post requests
FieldLocationType as shownRequiredness as capturedNotes
identifierPOST /v1/connect/bluesky/credentials bodystringRequired in exampleHandle such as alice.bsky.social or DID such as did:plc:abc123
passwordPOST /v1/connect/bluesky/credentials bodystringRequired in exampleBluesky app password, not the main account password
integration.idConnect responsestring as describedReturned valueUse as accountId when posting
contentPOST /v1/posts bodystringRequired in exampleBluesky limit: 300 characters
platformsPOST /v1/posts bodyarrayRequired in exampleOne entry per target platform
platforms[].platformPOST /v1/posts bodystringRequired in exampleUse bluesky for Bluesky
platforms[].accountIdPOST /v1/posts bodystringRequired in exampleValue captured as integration.id from connect
publishNowPOST /v1/posts bodybooleanUsed for immediate publishSet true to publish now
scheduledForPOST /v1/posts bodystringUsed instead of publishNow for schedulingExample: 2026-05-01T14:00:00
timezonePOST /v1/posts bodystringUsed with scheduledForExample: America/New_York
mediaItemsPOST /v1/posts bodyarrayOptional in examplesEach item has type image and url
platformSpecificData.altTextplatforms[] entryarray of stringsOptionalMaps positionally to mediaItems
platformSpecificData.langsplatforms[] entryarray of stringsOptionalBCP-47 tags such as es, en

As captured in source examples; response schemas and status codes not captured.

Validation and failure matrix
CheckFailure to avoidHow to verify
Content lengthExceeding 300 characters for BlueskyCount characters before sending; fix content if over the cap
Credential typeUsing the main account password instead of a Bluesky app passwordGenerate an app password in account preferences under the security area for app credentials
identifier formatSending neither a handle nor a DIDUse alice.bsky.social style handle or did:plc:... style DID
Alt text alignmentaltText order or count not matching mediaItemsKeep arrays aligned positionally, one description per image
Language tagslangs not matching the post languageUse BCP-47 tags for the actual languages in the content
Scheduling fieldsUsing publishNow and scheduledFor inconsistentlyUse publishNow for immediate delivery or scheduledFor plus timezone for scheduling

Validation guidance derived from captured limits and field descriptions; error payloads not captured.

Access key header
-H "x-access-key: YOUR_API_KEY"
Connect a Bluesky account with an app password
curl -X POST {{API_BASE_URL}}/v1/connect/bluesky/credentials \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "alice.bsky.social",
    "password": "xxxx-xxxx-xxxx-xxxx"
  }'
Publish a Bluesky post now
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": "your-account-id" }
    ],
    "publishNow": true
  }'
Publish with an image and image 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.",
    "mediaItems": [
      { "type": "image", "url": "https://your-cdn.com/sunset.jpg" }
    ],
    "platforms": [
      {
        "platform": "bluesky",
        "accountId": "your-account-id",
        "platformSpecificData": {
          "altText": ["Orange-pink sunset over the Pacific Ocean with silhouetted cliffs"]
        }
      }
    ],
    "publishNow": true
  }'
Publish with BCP-47 language tags
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": "your-account-id",
        "platformSpecificData": {
          "langs": ["es", "en"]
        }
      }
    ],
    "publishNow": true
  }'
Schedule a 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": "your-account-id" }
    ],
    "scheduledFor": "2026-05-01T14:00:00",
    "timezone": "America/New_York"
  }'
Cross-post to Bluesky and other platforms
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": "acc_bsky_123" },
      { "platform": "twitter",  "accountId": "acc_tw_456" },
      { "platform": "linkedin", "accountId": "acc_li_789" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://your-cdn.com/launch.png" }
    ],
    "publishNow": true
  }'