API Long-Form Bluesky 2026: Ferramentas de Terceiros

9 de Julho, 2026 · 10 min de leitura · Guia

O formato de post longo do Bluesky foi lancado para todos os usuarios no final de maio de 2026, e a primeira onda de tooling ao redor dele foi quase inteiramente do lado de leitura: clientes que renderizavam o novo embed, mirrors que puxavam o post para Markdown, e superficies de busca que indexavam o corpo. No inicio de julho de 2026, o cenario esta mudando. O Bluesky se comprometeu publicamente a abrir o lado de escrita da API de long-form para ferramentas de terceiros, com o primeiro SDK estavel previsto para agosto de 2026. Este guia e o que o playbook de escrita parece no interim, para qualquer criador ou desenvolvedor de ferramentas que queira enviar um caminho de publicacao de long-form no Bluesky antes do SDK oficial ser GA.

O playbook de leitura que publicamos em 6 de julho cobriu como puxar posts longos para uma inbox unica e converte-los para Markdown. Este artigo e o complemento: empurrar posts longos de uma ferramenta de terceiros para o Bluesky atraves da nova API publica de escrita, com a mesma disciplina Markdown-first no lado de entrada. As duas metades juntas sao uma stack de conteudo Bluesky portatil e script-driven que qualquer criador pode rodar em sua propria infraestrutura.

O Que a API de Escrita de Long-Form E Na Verdade

O Bluesky nao introduziu um novo endpoint para posts longos. O formato long-form vive em cima do record app.bsky.feed.post existente, em um novo campo embeds que aponta para uma estrutura app.bsky.embed.recordWithMedia. O corpo dentro do embed e um documento Markdown; o cliente publico renderiza como um card de scroll longo. O mesmo tipo de record, o mesmo endpoint XRPC, o mesmo fluxo de auth. Ferramentas de terceiros que ja sabem como escrever um post de 280 caracteres atraves de com.atproto.repo.createRecord podem escrever um post longo preenchendo o campo embed com a estrutura long-form, sem SDK novo.

Para o lado de leitura, essa e a historia inteira. Para o lado de escrita, ha tres coisas para saber sobre o que esta sendo enviado antes do SDK de agosto de 2026:

• Developer preview atras de uma flag. O caminho de escrita para a estrutura embed de long-form esta live no endpoint publico, mas esta gated atras de uma developer flag no SDK oficial. Ferramentas de terceiros que batem no endpoint diretamente atraves da chamada XRPC ja podem escrever posts longos. Ferramentas que usam o SDK oficial precisam setar a flag na config do cliente ate o release estavel.
• OAuth e a auth recomendada para ferramentas multi-usuario. App passwords ainda funcionam e ainda sao o caminho mais leve para uma ferramenta pessoal, mas qualquer coisa que escreve em nome de mais de um usuario deve usar OAuth com escopo per-app. O time do Bluesky confirmou que os escopos OAuth para escrita de long-form sao os mesmos da escrita de short-form; nenhum escopo novo esta sendo introduzido.
• O primeiro SDK estavel esta previsto para agosto de 2026. Esse SDK vai lockar a forma JSON do embed de long-form, documentar os rate limits, e adicionar o guia de migracao para ferramentas que estavam usando o developer preview. Ate la, trate a forma JSON como estavel mas espere adicoes menores de campos no release do SDK.

Para um desenvolvedor de ferramentas enviando em julho de 2026, o caminho pratico e: use o endpoint publico com uma app password para sua propria conta, prototipe a chamada de escrita, e esteja pronto para trocar para OAuth + o SDK estavel assim que sair em agosto. O custo de escrever a integracao duas vezes e pequeno comparado ao custo de esperar pelo SDK e perder os dois primeiros meses de trafego de cross-post.

O Workflow de Escrita em Seis Passos

O workflow de escrita completo, de ponta a ponta, tem seis passos. Quatro deles sao script-driven e dois sao interface-driven. Os passos interface-driven (passo 1, criacao de app password; passo 5, submissao de mirror) sao os unicos lugares onde um humano precisa estar no loop, e ambos sao setups one-time. Uma vez feitos, o pipeline inteiro roda a partir de um unico make publish em um arquivo Markdown.

Passo 1: Criar uma app password

Uma app password e um token escopado por app que o usuario pode revogar da UI de configuracoes do Bluesky sem afetar a sessao principal. Gere uma em Settings -> App Passwords -> Add App Password, de um nome (ex. "third-party-longform-publisher"), e copie o token exibido uma unica vez. Armazene em um secrets manager, nao em um repo. O token tem o mesmo escopo de escrita da sua sessao principal mas esta escopado ao nome do app no log de auditoria, o que e util quando voce esta debugando uma escrita ruim que voce nao fez de proposito.

# 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:...", ...}

Passo 2: Compor o corpo do post em Markdown

Corpos de long-form do Bluesky sao Markdown. Nao um subset, nao um flavor, nao um derivado. CommonMark padrao com extensoes GFM para tabelas e task lists. O corpo vive no campo embed.media.external.description, com os primeiros 200 caracteres usados como preview do link na timeline publica. O corpo completo e fetched quando um leitor clica para abrir.

A implicacao para desenvolvedores de ferramentas e que todo o caminho de escrita de long-form pode ser Markdown-first. O mesmo arquivo Markdown que voce escreve para um post de blog, uma newsletter do Substack, ou um artigo do LinkedIn pode ser a source of truth para um post longo do Bluesky, com o titulo em embed.media.external.title e o corpo em embed.media.external.description (limitado a 200 chars para o preview, com o corpo completo referenciado atraves do campo canonical URL). Essa e a mesma forma que o playbook de leitura usou para o mirror, e essa simetria e o que torna os dois lados composable.

Passo 3: Escrever o record

Uma vez que voce tem o session token e o corpo Markdown, a chamada de escrita e um unico POST em com.atproto.repo.createRecord. O collection e app.bsky.feed.post, o repo e o DID do usuario, e o record.embed e a estrutura de long-form. A resposta carrega o post URI, que voce precisara para o passo de mirror e para o campo canonical URL na superficie de citacao.

# 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

Passo 4: Converter Markdown para a estrutura embed

Para uma ferramenta que publica muitos posts, a conversao de Markdown para o JSON embed do Bluesky e a parte que e re-implementada. Abaixo esta a versao funcionando, em 20 linhas de Python, que qualquer ferramenta de terceiros pode dropar. Ela usa python-frontmatter para ler o front matter (title, canonical_url, description) e um pass de regex para strippar Markdown para o preview de description.

# 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))

Passo 5: Mirror para uma superficie citation-ready

Um post longo do Bluesky e, por default, somente indexavel dentro da propria busca do Bluesky e da firehose do AT Protocol. Agentes de IA (GPTBot, ClaudeBot, PerplexityBot) nao crawlheiam o app do Bluesky, entao um post longo sem um mirror externo e invisivel para a camada de busca de IA. O fix e mirrorar o post para uma URL estavel e citation-ready no mesmo dia em que voce publica no Bluesky. O mirror deve carregar o corpo Markdown completo, linkar de volta para o post do Bluesky, e ser submetido as superficies de crawl padrao (sitemap, llms.txt, Bing webmaster, IndexNow).

ThreadGrab e um desses mirrors, e o caminho de publicacao e o mesmo que voce usaria para qualquer outra superficie de long-form: POST o source URI, a public URL, o titulo, e o body Markdown para o endpoint de ingest. A mirror page vai live dentro de um minuto, a entrada do sitemap e adicionada automaticamente, e o post e acessivel por GPTBot e ClaudeBot dentro do proximo ciclo de crawl.

# 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 <