Bluesky Posting API
The Bluesky Posting API lets you publish to Bluesky from a product, automation, agency workflow, or AI system with one REST request, without building the AT Protocol flow yourself.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "bluesky",
"accountId": "bs_123"
}
],
"publishNow": true
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
Send text through POST {{API_BASE_URL}}/v1/posts, attach images via mediaItems, add clickable links, and confirm delivery from the response. The same request shape can reach other networks, with separate copy per network where needed.
Exact posting contract and how to verify publication
Send Bluesky posts to POST {{API_BASE_URL}}/v1/posts. In the worked text example, content carries the message, platforms holds an object with platform set to bluesky and accountId set to bs_123, and publishNow is true. The example response returns HTTP 202 and includes success, status published, postId, plus a platforms entry with platformPostUrl. Match those names and values exactly. Confirmation comes from a successful Bluesky entry together with a present platformPostUrl; keep postId for later lookup. A missing platformPostUrl means publication is not verified, even if the request was accepted.
Field map for text, images, links, language, and scheduling
Put the message in content and choose the destination through platforms. The example shows platforms as an array whose object contains platform and accountId, with publishNow governing immediate sending in that example. Attach pictures via mediaItems, with a maximum of four per post. Descriptions for those pictures go in an altText array inside platformSpecificData, ordered to match mediaItems. Place a URL inside content for a clickable link; publishing creates the needed facets. Mark language with BCP-47 tags. For later delivery, use scheduling with explicit timezone information so timing does not depend on a server clock.
Limits, unsupported formats, and failure checks
Check length against 300 graphemes before sending, so an oversized post is stopped locally. Check the picture count against four and each file against 1 MB. Video and GIF are unsupported, so block those formats in your upload flow rather than relying on a platform error. Do not advertise rich-preview link cards: supported link handling here is automatic URL detection in content and creation of clickable facets. For queued posts, confirm scheduled state, timezone, and final time before release, and revise content, media, platform options, or time while the post is still scheduled.
Unified endpoint versus direct AT Protocol, and cross-platform publishing
Pick the unified endpoint when one posting shape across Bluesky and other networks is preferable to maintaining direct protocol layers. Direct work leaves your team responsible for sign-in and session upkeep, account identifier resolution, data-server communication, record creation, image-data upload, link-facet construction, short-lived credential refresh, and platform-rule checks. Stay direct only when control over those layers is required and your team can maintain them. For multi-network sending, use one request with shared copy when it suits every network, or supply network-specific copy when length, tone, or media differ.
Using the endpoint from developer, no-code, and AI-agent stacks
The contract stays the same across stacks. Server code can call the REST endpoint directly. No-code tools can trigger the identical request from existing automations. AI agents can invoke the same posting and scheduling operations through tool-calling or a hosted MCP-style interface, as long as they receive the exact request shape and verification steps above. Whatever the stack, leave field names unchanged and check the response before telling a user the post succeeded.
Other platforms and capabilities beyond publishing
Bluesky shares its posting shape with other destinations, including Twitter / X, Instagram, YouTube, Facebook, TikTok, Threads, Pinterest, LinkedIn, and Google Business, each with its own platform value and account. Once posting works, separate workflows can add scheduling for chosen times, analytics for engagement and reach, comments for reading and replying, and messaging for direct conversations. Each extension has its own contract; do not assume posting fields cover it.
| Field | Location | Use and checks |
|---|---|---|
| content | Request | Post text; include URLs here for clickable links; validate against 300 graphemes. |
| platforms | Request | Array of destination objects; captured example uses platform bluesky with accountId bs_123. |
| accountId | Request, inside platforms entry | Identifies the connected Bluesky account for the destination. |
| publishNow | Request | Captured text example sets publishNow to true for immediate publication. |
| mediaItems | Request | Attaches images; support up to four images per post, each no larger than 1 MB. |
| platformSpecificData | Request, inside each platforms[] entry | Carries Bluesky-specific options, including the altText array. |
| altText | Request, inside platformSpecificData | One description per corresponding image in mediaItems, in matching order. |
| postId | Response | Identifier for the created post in the captured response. |
| platformPostUrl | Response, inside platforms entry | Live Bluesky post URL used to verify successful publication. |
| platformPostId | Per-platform response identifier | Native Bluesky post ID described in the publication-verification FAQ; not shown in the captured example, and type/format not specified. |
Field map is limited to fields evidenced in the captured text example and FAQ prose; full schemas for image, scheduling, language, and per-platform variants were not supplied.
| Format or behavior | Supported | Limit or check |
|---|---|---|
| Text post | Yes | Up to 300 graphemes. |
| Images | Yes | Up to four images; each image no larger than 1 MB. |
| Alt text | Yes | Use altText in platformSpecificData, aligned with mediaItems. |
| Clickable links | Yes | Include the URL in content; facets are created automatically. |
| Rich-preview link cards | Not promised | Do not claim a separate card workflow beyond clickable facets. |
| Video | No | Listed as unsupported. |
| GIF | No | Listed as unsupported. |
| Language tags | Yes | One or more BCP-47 language tags. |
| Scheduling | Yes | Use timezone support and verify scheduled state before publication. |
Link-card behavior is held to the narrower supported description: automatic clickable URL facets only, not a separate rich-preview card workflow.
Frequently asked questions
What can I publish with the Bluesky Posting API?
Text-only posts and posts with up to four images are supported. Clickable URLs, per-image alt text, and BCP-47 language tags are also available.
Why use a unified endpoint instead of the AT Protocol directly?
Going direct means your team owns the whole protocol stack: signing in and keeping sessions alive, resolving account identifiers, talking to the data server, creating the underlying records, uploading image data, building link facets, refreshing short-lived credentials, and checking platform rules. A unified endpoint moves those steps behind one posting call that shares its shape with other networks.
What is the Bluesky character limit?
Bluesky posts support up to 300 graphemes. Count graphemes rather than raw bytes or code points when validating content before sending it.
Can I publish images to Bluesky?
Yes. Attach images through mediaItems. The publishing flow handles Bluesky blob upload and image embedding.
How many images can I publish in one Bluesky post?
Up to four images per post. Each image can be no larger than 1 MB, so check file size before submitting the request.
Can I add alt text to Bluesky images?
Yes. Inside platformSpecificData, supply altText as an array whose entries line up, in order, with the items you placed in mediaItems. Alt text is strongly encouraged for accessibility.
Can I publish videos to Bluesky?
No. Video publishing is listed as unsupported for Bluesky through this endpoint.
Can I publish GIFs to Bluesky?
No. GIF publishing is listed as unsupported for Bluesky through this endpoint.
Can I publish links to Bluesky?
Yes. Include the URL in the content field. URLs are automatically detected and converted to the facets required for clickable links.
Does this support Bluesky link cards?
Only automatic clickable URL facets are described as supported. A separate rich-preview link card workflow is not promised here.
Can I set the language of a Bluesky post?
Yes. One or more BCP-47 language tags can be included with a post.
Can I edit or reschedule a Bluesky post before it publishes?
Yes. While a post remains scheduled, scheduled content, media, platform options, or publishing time can be updated through the scheduling workflow.
How do I know whether my Bluesky post published?
Check status and the successful Bluesky result, then retain its live platformPostUrl. Keep the saved request postId separate from the native Bluesky platformPostId when that identifier is returned. The displayed response example contains postId and platformPostUrl but does not show platformPostId; do not infer its type or format from the example.
Who is the Bluesky Posting API for?
Product teams building automated social publishing fit this endpoint, including SaaS operators, agency teams, automation creators, and AI builders who need one maintained posting interface.
{
"success": true,
"status": "published",
"postId": "post_abc123",
"platforms": [
{
"platform": "bluesky",
"success": true,
"platformPostUrl": "https://bsky.app/profile/example.bsky.social/post/3kabc123"
}
]
}