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 | Location | Type as shown | Requiredness as captured | Notes |
|---|---|---|---|---|
| identifier | POST /v1/connect/bluesky/credentials body | string | Required in example | Handle such as alice.bsky.social or DID such as did:plc:abc123 |
| password | POST /v1/connect/bluesky/credentials body | string | Required in example | Bluesky app password, not the main account password |
| integration.id | Connect response | string as described | Returned value | Use as accountId when posting |
| content | POST /v1/posts body | string | Required in example | Bluesky limit: 300 characters |
| platforms | POST /v1/posts body | array | Required in example | One entry per target platform |
| platforms[].platform | POST /v1/posts body | string | Required in example | Use bluesky for Bluesky |
| platforms[].accountId | POST /v1/posts body | string | Required in example | Value captured as integration.id from connect |
| publishNow | POST /v1/posts body | boolean | Used for immediate publish | Set true to publish now |
| scheduledFor | POST /v1/posts body | string | Used instead of publishNow for scheduling | Example: 2026-05-01T14:00:00 |
| timezone | POST /v1/posts body | string | Used with scheduledFor | Example: America/New_York |
| mediaItems | POST /v1/posts body | array | Optional in examples | Each item has type image and url |
| platformSpecificData.altText | platforms[] entry | array of strings | Optional | Maps positionally to mediaItems |
| platformSpecificData.langs | platforms[] entry | array of strings | Optional | BCP-47 tags such as es, en |
As captured in source examples; response schemas and status codes not captured.
| Check | Failure to avoid | How to verify |
|---|---|---|
| Content length | Exceeding 300 characters for Bluesky | Count characters before sending; fix content if over the cap |
| Credential type | Using the main account password instead of a Bluesky app password | Generate an app password in account preferences under the security area for app credentials |
| identifier format | Sending neither a handle nor a DID | Use alice.bsky.social style handle or did:plc:... style DID |
| Alt text alignment | altText order or count not matching mediaItems | Keep arrays aligned positionally, one description per image |
| Language tags | langs not matching the post language | Use BCP-47 tags for the actual languages in the content |
| Scheduling fields | Using publishNow and scheduledFor inconsistently | Use publishNow for immediate delivery or scheduledFor plus timezone for scheduling |
Validation guidance derived from captured limits and field descriptions; error payloads not captured.
-H "x-access-key: YOUR_API_KEY"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"
}'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
}'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
}'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
}'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"
}'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
}'