Posting to Bluesky via API: The Developer Guide to the Decentralized Social Network

What Makes Bluesky Different: The AT Protocol

Bluesky is not just another Twitter clone — it is built on the AT Protocol (Authenticated Transfer Protocol), a fundamentally different architecture for social networking. Where Twitter and Instagram are centralized platforms controlled by a single company, Bluesky is designed as a decentralized, federated network where users own their data, identity, and social graph.

For developers, this means Bluesky's API is radically different from what you are used to. There are no simple OAuth tokens — instead, you work with DIDs (Decentralized Identifiers), facets for rich text with precise byte offsets, blob uploads for media, and AT Protocol records instead of REST-style resources. The learning curve is steep, even for experienced API developers.

What you'll learn in this guide:

• What makes Bluesky's AT Protocol different from traditional social APIs
• How to connect your Bluesky account to Publora (app password setup)
• Posting text with automatic hashtag and URL facets
• Attaching images (up to 4) and video (up to 3 minutes)
• How Publora abstracts the byte offset math, DID resolution, and blob uploads
• Code examples in JavaScript and Python

Why Bluesky Matters for Developers and Brands

Bluesky has been growing rapidly since opening to public signups, attracting a developer-heavy, tech-savvy audience. For brands and developers building social media tools, Bluesky offers several unique advantages.

The Problem: AT Protocol Complexity

While Bluesky's open architecture is a strength, it creates significant complexity for developers who just want to post content. Here is what the AT Protocol requires you to handle when posting directly.

The most painful part of working directly with Bluesky's API is facet creation. Bluesky uses a rich text system where hashtags and URLs must be annotated with precise byte offsets — not character offsets. This means a single emoji (which may be 4 bytes in UTF-8) shifts every subsequent offset. Getting this wrong results in broken links and garbled hashtags.

// What facets look like in raw AT Protocol — you DON'T need this with Publora
const record = {
  $type: 'app.bsky.feed.post',
  text: 'Check out #devtools at https://example.com',
  facets: [
    {
      index: { byteStart: 10, byteEnd: 19 },  // "#devtools"
      features: [{ $type: 'app.bsky.richtext.facet#tag', tag: 'devtools' }]
    },
    {
      index: { byteStart: 23, byteEnd: 43 },  // "https://example.com"
      features: [{ $type: 'app.bsky.richtext.facet#link', uri: 'https://example.com' }]
    }
  ],
  createdAt: new Date().toISOString()
};
// Publora calculates ALL of this automatically from your plain text content

Connect Bluesky to Publora

Connecting Bluesky is straightforward but works differently from OAuth-based platforms. Bluesky uses identifier + app password authentication rather than an OAuth flow.

Step 1: Generate an App Password

1. Open the Bluesky app (web or mobile)
2. Go to Settings → App Passwords
3. Click "Add App Password"
4. Give it a descriptive name (e.g., "Publora Integration")
5. Copy the generated password — you will only see it once

Step 2: Add to Publora Dashboard

1. Open app.publora.com and go to Connections
2. Click "+ Add Connection" and select Bluesky
3. Enter your identifier (your Bluesky handle, e.g., yourname.bsky.social)
4. Enter your app password
5. Click Connect

Your Bluesky account will appear in the Connections list with a platform ID in the format bluesky-did:plc:abc123xyz. The did:plc:... part is your Decentralized Identifier — a permanent, portable identifier that follows you even if you change your handle.

Posting Text to Bluesky

The simplest Bluesky post is a text update. Publora automatically detects and converts hashtags and URLs into clickable Bluesky facets — you just write plain text.

JavaScript

const response = await fetch('https://api.publora.com/api/v1/create-post', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-publora-key': 'sk_YOUR_API_KEY'
  },
  body: JSON.stringify({
    content: 'Just shipped v2.0 of our developer toolkit! Full changelog at https://example.com/changelog #opensource #devtools',
    platforms: ['bluesky-did:plc:abc123xyz']
  })
});

const data = await response.json();
// { "success": true, "postGroupId": "abc123..." }
console.log('Posted to Bluesky:', data.postGroupId);

Python

import requests

API_KEY = 'sk_YOUR_API_KEY'
BASE = 'https://api.publora.com/api/v1'

response = requests.post(
    f'{BASE}/create-post',
    headers={
        'Content-Type': 'application/json',
        'x-publora-key': API_KEY
    },
    json={
        'content': 'Just shipped v2.0 of our developer toolkit! Full changelog at https://example.com/changelog #opensource #devtools',
        'platforms': ['bluesky-did:plc:abc123xyz']
    }
)

data = response.json()
# {"success": True, "postGroupId": "abc123..."}
print(f'Posted to Bluesky: {data["postGroupId"]}')

Posting with Images

Bluesky supports up to 4 images per post. All images are automatically converted to JPEG by Publora before being uploaded to Bluesky, so you can upload PNG, WebP, GIF, or any format supported by sharp.

JavaScript (with alt text)

// Step 1: Create the post with alt text
const response = await fetch('https://api.publora.com/api/v1/create-post', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-publora-key': 'sk_YOUR_API_KEY'
  },
  body: JSON.stringify({
    content: 'New dashboard design is live! Dark mode included. #buildinpublic',
    platforms: ['bluesky-did:plc:abc123xyz'],
    altTexts: ['Screenshot of the new analytics dashboard with dark mode enabled, showing traffic graphs and engagement metrics']
  })
});

const { postGroupId } = await response.json();

// Step 2: Get presigned upload URL
const uploadRes = await fetch(
  `https://api.publora.com/api/v1/upload-media/${postGroupId}?filename=dashboard-dark.png`,
  { headers: { 'x-publora-key': 'sk_YOUR_API_KEY' } }
);
const { uploadUrl } = await uploadRes.json();

// Step 3: Upload the image (PNG is fine — Publora converts to JPEG for Bluesky)
const imageBuffer = fs.readFileSync('dashboard-dark.png');
await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'image/png' },
  body: imageBuffer
});

Python (multiple images)

import requests

API_KEY = 'sk_YOUR_API_KEY'
BASE = 'https://api.publora.com/api/v1'

# Step 1: Create post with alt texts for multiple images
resp = requests.post(f'{BASE}/create-post', headers={
    'Content-Type': 'application/json',
    'x-publora-key': API_KEY
}, json={
    'content': 'Before and after our office renovation!',
    'platforms': ['bluesky-did:plc:abc123xyz'],
    'altTexts': [
        'Office before renovation with old furniture and dim lighting',
        'Office after renovation with modern desks and natural light'
    ]
})
post_id = resp.json()['postGroupId']

# Step 2: Upload each image
images = ['before.jpg', 'after.jpg']
for img in images:
    upload_resp = requests.get(
        f'{BASE}/upload-media/{post_id}?filename={img}',
        headers={'x-publora-key': API_KEY}
    )
    upload_url = upload_resp.json()['uploadUrl']

    with open(img, 'rb') as f:
        requests.put(upload_url, headers={'Content-Type': 'image/jpeg'}, data=f)

print(f'Posted with {len(images)} images!')

Image Specifications

Specification	Limit
Max images per post	4
Max size per image	~1 MB (976.56 KB) after JPEG conversion
Max dimensions	2000 x 2000 pixels
Input formats	JPEG, PNG, WebP, GIF, TIFF, BMP (all converted to JPEG)
Output format	JPEG (always, regardless of input)
Alt text limit	2,000 characters per image

Posting Video to Bluesky

Bluesky added video support with specific constraints. Videos must be MP4 format with tiered size limits based on duration.

Duration	Max File Size
Under 60 seconds	50 MB
60 seconds - 3 minutes	100 MB

// Post a video to Bluesky
const response = await fetch('https://api.publora.com/api/v1/create-post', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-publora-key': 'sk_YOUR_API_KEY'
  },
  body: JSON.stringify({
    content: 'Quick demo of our new CLI tool in action #devtools',
    platforms: ['bluesky-did:plc:abc123xyz']
  })
});

const { postGroupId } = await response.json();

// Upload video (MP4 only, max 3 minutes)
const uploadRes = await fetch(
  `https://api.publora.com/api/v1/upload-media/${postGroupId}?filename=demo.mp4`,
  { headers: { 'x-publora-key': 'sk_YOUR_API_KEY' } }
);
const { uploadUrl } = await uploadRes.json();

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'video/mp4' },
  body: fs.readFileSync('demo.mp4')
});

How Publora Abstracts AT Protocol Complexity

To appreciate what Publora handles for you, here is a side-by-side comparison of posting directly via AT Protocol versus using Publora.

Behind the scenes, Publora performs all of the AT Protocol operations for you:

Bluesky Character Limits: What Counts

Bluesky's 300-character limit is strict, and the counting rules matter when you are automating content.

Element	Bluesky	Twitter/X
Character limit	300	280
URL counting	Full length	~23 chars (shortened)
Hashtags	Count toward limit	Count toward limit
Emojis	1 character (display)	2 characters

Cross-Platform Posting: Bluesky + Other Networks

One of the biggest advantages of using Publora is posting to Bluesky alongside other platforms in a single API call. Simply include multiple platform IDs in the platforms array.

// Post to Bluesky, Mastodon, and X simultaneously
const response = await fetch('https://api.publora.com/api/v1/create-post', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-publora-key': 'sk_YOUR_API_KEY'
  },
  body: JSON.stringify({
    content: 'We just open-sourced our API client library! Check it out: https://github.com/example/sdk #opensource',
    platforms: [
      'bluesky-did:plc:abc123xyz',    // Bluesky (300 chars, auto facets)
      'mastodon-123456',               // Mastodon (500 chars)
      'twitter-987654321'              // X/Twitter (280 chars, auto threads)
    ]
  })
});

Publora handles the differences automatically — the 300-character Bluesky limit, Mastodon's 500-character limit, Twitter's 280-character limit with emoji double-counting, and each platform's unique media requirements. If your content exceeds a platform's limit, Publora will either truncate (with a note) or split into threads where supported.

Verifying and Monitoring Posts

After posting, you can verify your Bluesky content through the Publora dashboard or API.

import requests

API_KEY = 'sk_YOUR_API_KEY'
BASE = 'https://api.publora.com/api/v1'

# List recent posts
resp = requests.get(
    f'{BASE}/list-posts?limit=10',
    headers={'x-publora-key': API_KEY}
)

for post in resp.json()['posts']:
    print(f"{post['status']} | {post['content'][:50]}... | {post['platforms']}")

Getting Started in 5 Minutes

Here is the fastest path from zero to your first Bluesky post via the API.

1. Create a Publora account — free trial available
2. Generate a Bluesky app password — Settings → App Passwords in the Bluesky app
3. Connect Bluesky — Publora dashboard → Connections → Add → Bluesky
4. Get your API key — Settings → API Keys → Create Key (docs)
5. Send your first post — Use the JavaScript or Python examples above

Frequently Asked Questions

Further Reading

• Bluesky Platform Reference — Complete API documentation for Bluesky via Publora
• Media Upload Workflow — Presigned URL upload guide for all platforms
• Create Post API Reference — Full endpoint documentation
• Authentication Guide — API key setup and security best practices
• AT Protocol Documentation — Official protocol specification (for the curious)
• MCP Client Setup — Use Bluesky with AI assistants via MCP