Skip to content

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.

Text post request
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
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

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.

Bluesky posting field map
FieldLocationUse and checks
contentRequestPost text; include URLs here for clickable links; validate against 300 graphemes.
platformsRequestArray of destination objects; captured example uses platform bluesky with accountId bs_123.
accountIdRequest, inside platforms entryIdentifies the connected Bluesky account for the destination.
publishNowRequestCaptured text example sets publishNow to true for immediate publication.
mediaItemsRequestAttaches images; support up to four images per post, each no larger than 1 MB.
platformSpecificDataRequest, inside each platforms[] entryCarries Bluesky-specific options, including the altText array.
altTextRequest, inside platformSpecificDataOne description per corresponding image in mediaItems, in matching order.
postIdResponseIdentifier for the created post in the captured response.
platformPostUrlResponse, inside platforms entryLive Bluesky post URL used to verify successful publication.
platformPostIdPer-platform response identifierNative 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.

Supported formats and limits matrix
Format or behaviorSupportedLimit or check
Text postYesUp to 300 graphemes.
ImagesYesUp to four images; each image no larger than 1 MB.
Alt textYesUse altText in platformSpecificData, aligned with mediaItems.
Clickable linksYesInclude the URL in content; facets are created automatically.
Rich-preview link cardsNot promisedDo not claim a separate card workflow beyond clickable facets.
VideoNoListed as unsupported.
GIFNoListed as unsupported.
Language tagsYesOne or more BCP-47 language tags.
SchedulingYesUse 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.

Text post response with status 202
{
  "success": true,
  "status": "published",
  "postId": "post_abc123",
  "platforms": [
    {
      "platform": "bluesky",
      "success": true,
      "platformPostUrl": "https://bsky.app/profile/example.bsky.social/post/3kabc123"
    }
  ]
}