API de Publicação

O RankBloom escreve conteúdo de blog otimizado para SEO nos sites que você conecta a ele. A API de Publicação é o caminho pelo qual esse conteúdo pronto sai do RankBloom e chega aonde você quiser — um site WordPress, um CMS, uma plataforma de automação ou o seu próprio código.

É a mesma API por trás do plugin oficial para WordPress e das integrações com Zapier e Make.

URL base

https://app.getrankbloom.com/api/publish

Autenticação

Toda requisição leva um token de conexão. Crie um no RankBloom em Conexões: selecione o site, escolha a plataforma e clique em Criar conexão. O token aparece uma única vez e fica guardado apenas como hash, então guarde uma cópia na hora de criá-lo.

Cada token vale para um único site. Envie-o em qualquer um destes cabeçalhos:

Authorization: Bearer rb_live_xxxxxxxx
X-RankBloom-Token: rb_live_xxxxxxxx
X-API-KEY: rb_live_xxxxxxxx

Os três são aceitos porque hospedagens compartilhadas e gerenciadas costumam remover o Authorization, e algumas plataformas de automação enviam o cabeçalho X-API-KEY por padrão.

Nunca coloque o token na query string. Ele ficaria registrado nos logs de acesso e em todos os proxies do caminho. A API não lê o token de lá.

Revogar uma conexão tem efeito imediato. Tokens revogados e desconhecidos devolvem a mesma resposta, então ninguém consegue usar a diferença para descobrir tokens válidos.

Endpoints

GET /v1/ping

Verifica um token e informa a que ele está vinculado. Use como teste de conexão.

curl https://app.getrankbloom.com/api/publish/v1/ping \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

{
  "ok": true,
  "contract_version": 1,
  "label": "Example Site",
  "connection": { "id": "…", "name": "Make — Example Site", "platform": "make" },
  "site": { "id": "…", "name": "Example Site", "url": "https://example.com" }
}

label é um nome simples e legível para a conexão. As plataformas de automação usam esse valor para identificar a conta conectada.

GET /v1/posts

Posts recentes do site conectado, do mais novo para o mais antigo. Somente leitura — nunca altera o estado, então dá para consultar em intervalos regulares sem risco.

Parâmetro	Tipo	Padrão	Observações
`limit`	integer	25	Máximo de 100
`offset`	integer	0	Pula essa quantidade de posts
`since`	ISO 8601	—	Somente posts criados nesse momento ou depois

curl "https://app.getrankbloom.com/api/publish/v1/posts?limit=100&offset=0" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

{
  "ok": true,
  "contract_version": 1,
  "count": 46,
  "limit": 100,
  "offset": 0,
  "posts": [ … ]
}

Paginação. Aumente o offset em limit para recuar pelo arquivo. Não existe contagem total: uma página menor que limit significa que você chegou ao fim. Os resultados são ordenados por data de criação e depois por id, então a paginação continua estável mesmo quando dois posts têm o mesmo horário.

POST /v1/status

Diga ao RankBloom o que aconteceu com um post. É isso que transforma “entregamos” em “está no ar” e impede que o post seja oferecido de novo.

curl -X POST https://app.getrankbloom.com/api/publish/v1/status \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "b86cbffe-…",
    "status": "delivered",
    "external_url": "https://example.com/my-post",
    "external_id": "123"
  }'

Campo	Obrigatório	Observações
`post_id`	sim	O `id` de `/v1/posts`
`status`	sim	`delivered`, `failed` ou `skipped`
`external_url`	não	Onde foi publicado
`external_id`	não	O id do próprio sistema remoto
`error`	não	Por que falhou, se falhou

Um token só pode reportar posts do próprio site.

O payload do post

Um único formato canônico, versionado por contract_version.

Campo	Tipo	Observações
`id`	string	Estável. Use como chave de idempotência
`title`, `slug`, `excerpt`	string	`slug` é o valor final, já sem duplicatas
`content_html`, `content_md`	string	O corpo do post, nos dois formatos
`meta_title`, `meta_description`	string	Metadados de SEO
`primary_keyword`, `keywords`, `category`, `tags`	string / array	Taxonomia
`canonical_url`	string	Canônica, quando definida
`schema_json_ld`	object	Já convertido, nunca uma string JSON
`featured_image_url`	string	Imagem hospedada, pronta para usar
`audio_url`	string	Narração, quando o post tem
`audio_duration_seconds`, `audio_voice`	number / string	Detalhes da narração
`status`	string	`published` ou `draft`
`author`, `author_title`, `author_url`	string	Assinatura do autor
`created_at`, `published_at`	ISO 8601	Datas e horários

Todas as chaves estão sempre presentes. Um valor que não se aplica volta como null — ele nunca é omitido. Um post sem narração simplesmente traz audio_url: null; esse é o caso normal, não um erro. Escreva a sua integração esperando nulls, e não chaves ausentes.

O contrato é somente aditivo. Os campos nunca são renomeados, nem mudam de tipo, nem são removidos, porque integrações já em produção continuam pedindo a versão 1 indefinidamente. Uma mudança incompatível sairia como uma versão nova, servida ao lado desta.

Erros

Os erros retornam o status HTTP correspondente e um corpo JSON com uma mensagem legível.

{ "ok": false, "error": "Invalid or revoked connection token." }

Status	Significado
`400`	Falta um campo obrigatório ou ele está malformado
`401`	Token ausente, desconhecido ou revogado
`404`	O post não pertence a esta conexão

Integrações prontas

Você não precisa escrever código. A mesma API já vem pronta para:

WordPress — o plugin oficial Get RankBloom. Conecte com um clique, sem precisar colar nenhum token.
Make — um app personalizado com Watch Posts como gatilho e Mark Post as Published como ação.
Zapier — New Post como gatilho e Mark Post as Published como ação.

Suporte

Dúvidas sobre a API ou algo funcionando diferente do documentado — escreva para support@getrankbloom.com.