Bluesky Long-Form API 2026: Third-Party Tools In

July 9, 2026 · 10 min read · Guide

Bluesky's long-form post format shipped to all users in late May 2026, and the first wave of tooling around it was almost entirely read-side: clients that could render the new embed, mirrors that could pull the post into Markdown, and search surfaces that could index the body. As of early July 2026, the picture is shifting. Bluesky has publicly committed to opening the write side of the long-form API to third-party ingestion tools, with the first stable SDK release targeted for August 2026. This guide is what the write-side playbook looks like in the meantime, for any creator or tool developer who wants to ship a Bluesky long-form publishing path before the official SDK is GA.

The read-side playbook we published on July 6 covered pulling long-form posts into a single inbox and converting them to Markdown. This article is the complement: pushing long-form posts from a third-party tool into Bluesky through the new public write API, with the same Markdown-first discipline on the input side. The two halves together are a portable, script-driven Bluesky content stack that any creator can run on their own infrastructure.

What the Long-Form Write API Actually Is

Bluesky did not introduce a new endpoint for long-form posts. The long-form format lives on top of the existing app.bsky.feed.post record, in a new embeds field that points at an app.bsky.embed.recordWithMedia structure. The body inside the embed is a Markdown document; the public client renders it as a long-scroll card. The same record type, the same XRPC endpoint, the same auth flow. Third-party tools that already know how to write a 280-character post through com.atproto.repo.createRecord can write a long-form post by populating the embed field with the long-form structure, no new SDK required.

For the read side, that is the entire story. For the write side, there are three things to know about what is shipping before the August 2026 SDK:

• Developer preview behind a flag. The write path for the long-form embed structure is live on the public endpoint, but it is gated behind a developer flag in the official SDK. Third-party tools that hit the endpoint directly through the XRPC call can already write long-form posts. Tools that use the official SDK need to set the flag in the client config until the stable release.
• OAuth is the recommended auth for multi-user tools. App passwords still work and are still the lightest path for a personal tool, but anything that writes on behalf of more than one user should use OAuth with a per-app scope. The Bluesky team has confirmed that the OAuth scopes for long-form write are the same as for short-form write; no new scope is being introduced.
• The first stable SDK is targeted for August 2026. That SDK will lock the JSON shape of the long-form embed, document the rate limits, and add the migration guide for tools that were using the developer preview. Until then, treat the JSON shape as stable but expect minor field additions in the SDK release.

For a tool developer shipping in July 2026, the practical path is: use the public endpoint with an app password for your own account, prototype the write call, and be ready to switch to OAuth + the stable SDK once it ships in August. The cost of writing the integration twice is small compared to the cost of waiting for the SDK and missing the first two months of cross-posting traffic.

The Six-Step Write Workflow

The full write workflow, end to end, has six steps. Four of them are script-driven and two are interface-driven. The interface-driven steps (step 1, app password creation; step 5, mirror submission) are the only places a human has to be in the loop, and both are one-time setups. Once they are done, the entire pipeline runs from a single make publish on a Markdown file.

Step 1: Create an app password

An app password is a per-app scoped token that the user can revoke from the Bluesky settings UI without affecting their main session. Generate one at Settings -> App Passwords -> Add App Password, give it a name (e.g. "third-party-longform-publisher"), and copy the one-time-displayed token. Store it in a secrets manager, not in a repo. The token has the same write scope as your main session but is scoped to the app name in the audit log, which is useful when you are debugging a bad write that you did not intend.

# 1. Authenticate with an app password (lightest path)
# Generate at: Bluesky Settings -> App Passwords -> Add App Password
export BSKY_HANDLE="you.bsky.social"
export BSKY_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"

# 2. Create a session via com.atproto.server.createSession
curl -X POST "https://bsky.social/xrpc/com.atproto.server.createSession" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "'"$BSKY_HANDLE"'",
    "password":  "'"$BSKY_APP_PASSWORD"'"
  }'

# Response: {"accessJwt": "...", "did": "did:plc:...", ...}

Step 2: Compose the post body in Markdown

Bluesky long-form bodies are Markdown. Not a subset, not a flavor, not a derivative. Standard CommonMark with GFM extensions for tables and task lists. The body lives in the embed.media.external.description field, with the first 200 characters used as the link preview on the public timeline. The full body is fetched when a reader clicks through.

The implication for tool developers is that the entire long-form write path can be Markdown-first. The same Markdown file you author for a blog post, a Substack newsletter, or a LinkedIn article can be the source of truth for a Bluesky long-form post, with the title in embed.media.external.title and the body in embed.media.external.description (capped at 200 chars for the preview, with the full body referenced through the canonical URL field). This is the same shape that the read-side playbook used for the mirror, and that symmetry is what makes the two sides composable.

Step 3: Write the record

Once you have the session token and the Markdown body, the write call is a single com.atproto.repo.createRecord POST. The collection is app.bsky.feed.post, the repo is the user's DID, and the record.embed is the long-form structure. The response carries the post URI, which you will need for the mirror step and for the canonical URL field on the citation surface.

# 3. Write a long-form post via the new public write API
# app.bsky.feed.post with embeds field carrying Markdown body
curl -X POST "https://bsky.social/xrpc/com.atproto.repo.createRecord" \
  -H "Authorization: Bearer $BSKY_ACCESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "did:plc:YOUR_DID_HERE",
    "collection": "app.bsky.feed.post",
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "Long-form post title goes here",
      "createdAt": "2026-07-09T12:00:00Z",
      "embed": {
        "$type": "app.bsky.embed.recordWithMedia",
        "media": {
          "$type": "app.bsky.embed.external",
          "external": {
            "uri": "https://yourdomain.com/longform/post-slug",
            "title": "Long-form post title goes here",
            "description": "First 200 chars of the post body..."
          }
        }
      }
    }
  }'

# 4. Capture the post URI from the response
# -> at://did:plc:.../app.bsky.feed.post/3k...xyz

Step 4: Convert Markdown to the embed structure

For a tool that publishes many posts, the conversion from Markdown to the Bluesky embed JSON is the part that gets re-implemented. Below is the working version, in 20 lines of Python, that any third-party tool can drop in. It uses python-frontmatter to read the front matter (title, canonical_url, description) and a regex pass to strip Markdown for the description preview.

# 5. Convert a Markdown long-form body to the embed structure
# This is the part every third-party tool will need to ship before August 2026
import re, json, frontmatter

def md_to_bluesky_embed(md_path, max_desc_len=200):
    """Convert a Markdown file to the Bluesky long-form embed JSON shape."""
    post = frontmatter.load(md_path)
    body = post.content
    # Strip Markdown for description preview
    plain = re.sub(r'[#*_`>\[\]()]', '', body)
    plain = re.sub(r'\s+', ' ', plain).strip()
    description = plain[:max_desc_len]
    return {
        "$type": "app.bsky.embed.recordWithMedia",
        "media": {
            "$type": "app.bsky.embed.external",
            "external": {
                "uri": post.metadata.get("canonical_url", ""),
                "title": post.metadata.get("title", "Untitled"),
                "description": description
            }
        }
    }

embed = md_to_bluesky_embed("post.md")
print(json.dumps(embed, indent=2))

Step 5: Mirror to a citation-ready surface

A Bluesky long-form post is, by default, only indexable inside Bluesky's own search and the AT Protocol firehose. AI agents (GPTBot, ClaudeBot, PerplexityBot) do not crawl the Bluesky app, so a long-form post without an external mirror is invisible to the AI search layer. The fix is to mirror the post to a stable, citation-ready URL on the same day you publish to Bluesky. The mirror should carry the full Markdown body, link back to the Bluesky post, and be submitted to the standard crawl surfaces (sitemap, llms.txt, Bing webmaster, IndexNow).

ThreadGrab is one such mirror, and the publishing path is the same one you would use for any other long-form surface: POST the source URI, the public URL, the title, and the body Markdown to the ingest endpoint. The mirror page goes live within a minute, the sitemap entry is added automatically, and the post is reachable by GPTBot and ClaudeBot within the next crawl cycle.

# 6. Mirror the published long-form on threadgrab.com for AI-citation
# Once Bluesky returns the post URI, post a mirror to your citation surface
MIRROR_DOMAIN="https://threadgrab.com"
BSKY_POST_URI="at://did:plc:abc.../app.bsky.feed.post/3kxyz..."

# Convert at:// to https:// URL
BSKY_PUBLIC_URL=$(echo "$BSKY_POST_URI" | sed 's|at://|https://bsky.app/profile/|; s|/app.bsky.feed.post/|/post/|')

# Write the mirror page (same Markdown, with Bluesky embed linking back)
cat > mirror.html <