Bluesky and Mastodon posting API guide

Use an app password for Bluesky and never your main password. Slugs follow the handle, for example bluesky-myhandle-bsky-social and mastodon-myaccount. Quick references are on the Bluesky and Mastodon pages.

The 1 MB image limit is the one that catches people. Bluesky's lexicon rejects image blobs of 1,000,000 bytes or more when the record is created, so a normal phone photo fails. Socifyr checks every image before upload: a file already under the limit passes through untouched, and a larger one is re-encoded as a JPEG with progressively smaller dimensions and quality until it fits under roughly 976 KB. You send the original and the post publishes.

Text over 300 characters becomes a thread. The splitter prefers paragraph breaks, then sentences, then words, so each post reads on its own.

Mastodon posts do not auto-thread. Text beyond 500 characters is not split for you, so shorten it or split it yourself and post the parts in order.

curl -X POST https://api.socifyr.com/api/content/text \
  -H "Authorization: Bearer sk_your_key" \
  -H "X-Workspace-Id: <workspaceId>" \
  -H "Content-Type: application/json" \
  -d '{
    "connections": ["bluesky-myhandle-bsky-social", "mastodon-myaccount"],
    "text": "Hello from the open social web"
  }'

await socifyr.uploads.text({
  connections: ['bluesky-myhandle-bsky-social', 'mastodon-myaccount'],
  text: 'Quiet announcement for followers',
  platformOptions: {
    'mastodon-myaccount': { visibility: 'private' },
  },
})

When you cross-post, write for the tighter limit. For this pair that is 300 characters. Socifyr exposes getEffectiveCaptionLimit in @socifyr/shared to compute the minimum across a set of platforms. More patterns in cross-posting to multiple platforms with one API call.

• Using the main Bluesky password. Create an app password and revoke it in Bluesky if you need to cut access.
• Wrong instance URL. The Mastodon connection is tied to one instance. A token from another server will not work.
• A token without write scope. Tick both read and write when you create the Mastodon application.
• Oversized media on a small instance. Use the instance's own limit if it is lower than 8 MB images or 40 MB video.
• Hitting the daily cap. Both platforms are capped in Socifyr (50 and 100 posts per rolling 24 hours). See daily posting limits per platform.

• Bluesky links. URLs in your text are detected and turned into clickable link facets, so you do not need to format them. Count them toward the 300 characters.
• Bluesky images and video are uploaded as blobs and attached to the record. The adapter sends them without alt text by default.
• Bluesky first comment. Supported, so you can keep hashtags or a link out of the main post.
• Mastodon visibility defaults to public. Set unlisted, private or direct per post when the audience matters.
• Mastodon video is limited to 40 MB and images to 8 MB each, but a small instance can set lower limits than that.

If accessibility matters to your audience, check your posts in a platform client after publishing. Alt text is something to verify rather than assume.

Bluesky is the lower-friction start if you want threading handled for you: write a long post and it becomes a connected thread. Mastodon is the better fit if you want per-post visibility control or you already belong to an instance. Many teams connect both and treat them as one open-web channel, writing to the 300-character limit so the same text fits either. Both connect with simple credentials, neither requires an OAuth app review, and neither needs a scheduled reconnect in the way Instagram does, which makes them good first platforms for an agent you are still testing.