API tweet.md para LLMs 2026: 5 Fluxos de Markdown

Se você tem tratado a tweet.md apenas como um truque de reescrita de URL — o truque do navegador em que você troca x.com por tweet.md e o post renderiza como Markdown limpo — você está perdendo a melhor metade. A tweet.md também oferece uma pequena API HTTP bem documentada que pega os mesmos posts, threads e perfis do X e os devolve como Markdown puro que seu LLM pode ingerir diretamente. Sem JSON, sem parsing, sem etapa de limpeza.

O plano gratuito cobre testes casuais (5 requisições de post único por IP por mês civil, apenas thread=off). Qualquer coisa além disso — cadeias de ancestrais, contexto de ramo, dumps de perfil, X Articles — exige uma chave de API paga. Este guia percorre a superfície da API, os quatro métodos de autenticação, os cinco fluxos de LLM que se pagam em uma tarde e quando recorrer ao ThreadGrab em vez disso.

O que a API da tweet.md realmente retorna

A API tem um único propósito: dada uma URL de post do X (ou um handle + ID de post, ou um handle de perfil), devolver um documento Markdown com o texto do post, o handle do autor, o timestamp, links de mídia, estatísticas de engajamento e qualquer tweet citado ou resposta embutida renderizados como blocos Markdown aninhados. A saída é text/markdown, nunca JSON. A tweet.md rejeita explicitamente format=json.

Há três pontos de entrada:

• Reescrita no navegador: substitua x.com por tweet.md em qualquer URL de post. Funciona sem chave no mesmo navegador após o checkout (cookie de sessão). O plano gratuito é apenas de post único.
• Post/thread programático: GET https://tweet.md/{handle}/status/{tweetId} quando você já tem o handle e o ID. Mesmo formato de resposta da reescrita no navegador.
• Programático com URL completa: GET https://tweet.md/i/api/convert?url={encoded_url} quando você só tem a URL completa do x.com. Este é o endpoint que agentes e Shortcuts usam.
• Perfil: GET https://tweet.md/{handle} (navegador) ou GET https://tweet.md/i/api/profile?handle={handle} (programático). Exige créditos.

Os quatro endpoints aceitam os mesmos parâmetros de consulta: format, thread, userinfo, stats, metadata e (para perfis) pinnedpost, latest, replies, articles. Os padrões diferem levemente entre gratuito e pago: o plano gratuito força thread=off e userinfo=off; o plano pago usa como padrão thread=ancestors-20 e userinfo=author quando esses parâmetros são omitidos.

Autenticação — Quatro Métodos, Uma Chave

A tweet.md aceita a mesma chave de API de quatro maneiras diferentes. Escolha a que melhor se adapta ao seu runtime.

A chave se parece com twmd_key_… e é enviada por e-mail após o checkout no Stripe, ou gerada no painel. Os IPs confiáveis permitem pular o cabeçalho inteiramente para IPs de servidor fixos — útil quando você roda um cron em um VPS com endereço estável. A regra de precedência: se uma requisição inclui tanto um cabeçalho Bearer quanto um IP confiável, a chave Bearer vence.

Existe um plano gratuito para testes casuais, mas não é o que agentes de produção querem. O plano gratuito força thread=off e userinfo=off, o que significa que você recebe apenas o post único, sem metadados do autor, sem contexto de respostas. Cinco requisições por IP por mês civil. Qualquer coisa além de um teste rápido exige uma chave paga.

O Endpoint /i/api/convert (Programático)

Este é o endpoint que seu agente chamará com mais frequência. O contrato é simples: passe a URL completa do x.com como parâmetro de consulta e receba um documento Markdown. O cabeçalho carrega a chave Bearer.

curl -H "Authorization: Bearer twmd_key_..." \
  "https://tweet.md/i/api/convert?url=https%3A%2F%2Fx.com%2Fjack%2Fstatus%2F20&thread=branch-8"

A resposta é a thread completa renderizada como Markdown. O parâmetro thread=branch-8 limita a resposta a 8 posts no total: primeiro os ancestrais (a cadeia acima do seu post) e depois as respostas abaixo. Os cabeçalhos de resposta reais carregam os metadados que seu agente deve cobrar:

• X-Tweetmd-Posts-Returned — quantos posts voltaram no corpo
• X-Tweetmd-Credits-Charged — créditos deduzidos nesta chamada
• X-Tweetmd-Thread-Cap — o limite que você pediu (por ex. 8)
• X-Tweetmd-Cap-Hit — se o limite truncou uma thread mais longa

Esses cabeçalhos são anexados apenas à resposta HTTP, nunca ao corpo Markdown. Seu agente pode lê-los para registrar o uso de créditos sem poluir o conteúdo que o LLM ingere.

O Endpoint /i/api/profile (Raspagem de Perfil)

Perfis são cobrados de forma diferente. O perfil base custa 2 créditos, mais 1 crédito por post retornado em qualquer seção ativada (pinned, latest, replies, articles). O plano gratuito não inclui acesso a perfis.

curl -H "Authorization: Bearer twmd_key_..." \
  "https://tweet.md/i/api/profile?handle=jack&latest=10&replies=5"

Os padrões são conservadores: post fixado ativado, 5 posts mais recentes, respostas desativadas, artigos desativados. Os parâmetros latest, replies e articles aceitam um intervalo (latest 5-50, replies e articles 5-20). Cada post retornado é +1 crédito. Para um dump de perfil com o post fixado, 10 recentes e 5 respostas, você gasta 2 + 1 + 10 + 5 = 18 créditos para um perfil.

Este é o endpoint que você quer ao construir um pesquisador do X ou um ímã de leads. Puxe o perfil uma vez, receba bio + estatísticas + 10 posts recentes como um único documento Markdown. Seu LLM pode ingerir isso como contexto para um e-mail de prospecção personalizado ou uma análise competitiva.

5 Fluxos Que Realmente Compensam

Cinco padrões aparecem repetidamente em pipelines reais de LLM que usam a tweet.md. A lista não é exaustiva, mas todos pagam um pacote de US$ 5 de créditos em menos de uma tarde.

Fluxo 1: Ingestão RAG a Partir de Listas de Tweets Curadas

O uso de produção mais comum. Você mantém uma lista de URLs de posts do X sobre um tema (frameworks de agentes de IA, conselhos de indie hackers, pesquisa do setor). Num cron, seu script busca cada URL via /i/api/convert com thread=branch-8, divide nos separadores por post, gera os embeddings de cada post com seu modelo e os empurra para o seu vector store. A saída Markdown já é limpa: sem remoção de HTML, sem decodificação de entidades, sem parsing JSON. Sua lógica de chunking pode dividir nos cabeçalhos # 1/N — Post by … que a tweet.md emite.

# Pseudo-pipeline
for url in curated_urls:
    md = requests.get(
        f"https://tweet.md/i/api/convert",
        params={"url": url, "thread": "branch-8", "userinfo": "author"},
        headers={"Authorization": f"Bearer {TWEETMD_API_KEY}"},
    ).text
    for chunk in split_on_post_headers(md):
        embed_and_store(chunk, metadata={"source": url})

Custo: 1 crédito por post na thread retornada, mais 2 para o autor. Para 50 threads com média de 4 posts cada, isso é 50 + (50 × 2) = 150 créditos — bem dentro do pacote de US$ 5.

Fluxo 2: Extração de Citações Para Posts Long-Form

Você está escrevendo um Substack ou um long-form do LinkedIn pesado em pesquisa e quer citar 10 threads específicas do X. Para cada thread citada, busque a URL do post com thread=ancestors para obter a cadeia completa de respostas e depois cite os trechos relevantes. Como a tweet.md retorna Markdown com URLs de origem nos cabeçalhos dos posts, você tem um formato de citação pronto:

> Original post: https://x.com/exampleuser/status/9000000000000000001
> Captured: 2026-05-17T00:00:00.000Z
>
> Shipping notes: what changed in this release and why.

Você pode colar este bloco diretamente no seu artigo com atribuição adequada. O timestamp é o momento da captura, não o do post original, mas a tweet.md também inclui o horário original do post como um campo de metadados separado quando você usa userinfo=author.

Fluxo 3: Uso de Ferramentas por Agentes (Claude Code / Cursor / skills.sh)

A tweet.md publica um SKILL.md oficial em github.com/tweet-md/skill que instala via npx skills add tweet-md/skill. A skill ensina o agente três padrões: (1) reescrever URLs x.com e twitter.com para tweet.md antes de buscar, (2) chamar /i/api/convert quando só tem a URL completa do X, (3) chamar /i/api/profile quando precisa do contexto da bio. Combine a skill com uma chave de API no ambiente do seu agente:

export TWEETMD_API_KEY=twmd_key_...

# In Claude Code / Cursor, the agent will now:
# - rewrite x.com/jack/status/20 → tweet.md/jack/status/20 when fetching
# - call /i/api/convert when it has the full URL
# - log credit usage from X-Tweetmd-Credits-Charged headers

Sem a skill, um agente que encontra uma URL x.com tem três opções ruins: visitar o X diretamente (muro de login + rastreamento), tentar raspar o post (frágil, bloqueado pela detecção de bots do X) ou chamar um fetcher web genérico (retorna HTML, não Markdown, com anúncios e pixels de rastreamento). Com a skill, o agente reescreve a URL e recebe um documento Markdown limpo em uma única chamada HTTP.

Fluxo 4: Sincronização com Obsidian

O parâmetro format=obsidian envolve o mesmo Markdown em frontmatter YAML. O frontmatter inclui source, author, author handle, timestamp do post, timestamp da captura, bio (para perfis), stats e tags. O corpo é o texto do post e os metadados que você obteria com o formato padrão markdown.

---
source: https://x.com/jack/status/20
author: "jack"
author_handle: jack
posted: 2006-03-21T20:50:14.000Z
captured: 2026-05-17T00:00:00.000Z
tags: [x-post, tweetmd]
---

# X Post — jack — 2006-03-21
Post ID: 20
Source: https://x.com/jack/status/20
...

Num cron diário, seu script de sincronização percorre uma pasta de URLs salvas do X, busca cada uma com format=obsidian e grava o resultado no seu vault. O plugin Dataview do Obsidian pode então indexar posts por autor, por tag ou por data. O frontmatter é a única coisa que distingue isso de uma sincronização Markdown simples — se você quiser apenas Markdown puro, omita format.

Fluxo 5: Apple Shortcuts no iOS

O Shortcut pré-construído instala a partir da página de docs da tweet.md e executa uma única ação HTTP. A chave aqui é o cabeçalho x-ios-apikey — a tweet.md detecta requisições com chave iOS e retorna text/html com quebras de linha convertidas em <br>, que é o que os Shortcuts conseguem copiar para uma nota com limpeza.

GET https://tweet.md/jack/status/20
Headers:
  x-ios-apikey: twmd_key_...

O Shortcut aceita entrada da Share Sheet, recorre ao Clipboard se você o abriu diretamente, reescreve x.com para tweet.md na URL, chama o endpoint com o cabeçalho iOS e copia o Markdown retornado para a área de transferência. A partir daí você cola no Apple Notes, no Obsidian Mobile ou em qualquer app que aceite texto. O Shortcut armazena sua chave localmente; não compartilhe uma cópia personalizada.

Resumo do Escopo de Thread

O parâmetro thread é a parte mais confusa da API. Os quatro valores mapeiam quatro escopos de conversa, e o sufixo -N limita a resposta. Escolha o menor escopo que dá ao seu LLM o contexto de que ele precisa.

A sintaxe do limite é scope-N, onde N vai de 2 a 500 (padrão 20). branch-8 significa: gastar até 8 posts em ancestrais primeiro e depois respostas abaixo, não importa o tamanho real da thread. Se seu post tem 12 ancestrais, branch-8 gasta todos os 8 na cadeia ascendente e ignora as respostas abaixo. Se seu post tem 3 ancestrais, branch-8 gasta 3 para cima e 5 para baixo. full e conversation são aliases de branch e all.

format=markdown vs format=obsidian

O formato padrão markdown retorna o corpo do post com stats, mídia, citações e X Articles completos quando presentes. É o que você quer ao alimentar um LLM ou salvar em uma nota de texto puro.

O formato obsidian adiciona frontmatter YAML no topo: source, author, author_handle, posted, captured, bio opcional para perfis, bloco stats opcional e tags. O corpo é idêntico ao formato markdown. Use obsidian quando quiser consultas do Dataview por autor ou data, ou quando quiser que a visão de grafo do Obsidian mostre conexões entre autores e tópicos.

Nenhum dos formatos retorna JSON. A tweet.md rejeita deliberadamente format=json — a filosofia do projeto é que Markdown é o formato de intercâmbio canônico para consumidores de LLM, e o envolvimento com JSON adiciona custo de parsing sem agregar valor.

Matemática de Preços — Qual Pacote Comprar

Três pacotes de créditos, US$ 5 / US$ 19 / US$ 49. O custo por crédito cai conforme o pacote cresce, mas o valor em dólares é a decisão real. Aqui está a matemática do ponto de equilíbrio.

"Fetch de post único" assume thread=off e userinfo=off, então 1 crédito por chamada. "Thread branch-8" assume 8 posts retornados (8 créditos) + 2 do metadado do autor = 10 créditos por chamada. "Dump de perfil" assume fixado + 10 recentes + 5 respostas = 18 créditos por chamada (2 base + 1 fixado + 10 recentes + 5 respostas).

O pacote de US$ 19 é o ponto de partida certo para a maioria dos criadores individuais: 2.200 créditos cobrem cerca de 138 dumps de perfil ou 275 threads branch-8. O pacote de US$ 49 é para equipes que rodam vários crons diários ou agentes que ingerem dezenas de threads por dia. O pacote de US$ 5 é para testar a API antes de se comprometer.

Quando Combinar a tweet.md com o ThreadGrab

A tweet.md e o ThreadGrab são complementares, não concorrentes. A versão curta: a tweet.md lê o post, o ThreadGrab guarda o post.

A divisão natural de trabalho: tweet.md para o caminho de leitura e o loop de agente (seu LLM busca um post, resume, responde a uma pergunta sobre ele), ThreadGrab para o caminho de guardar (você encontra uma thread que vale preservar e a salva no seu próprio armazenamento com mídia e histórico de versões). A maioria dos criadores ativos acaba usando ambos — tweet.md para as dezenas de leituras descartáveis por dia, ThreadGrab para as poucas threads por semana que merecem uma cópia permanente.

FAQ