Xt4b

API de leitura

Uma API de conteúdo SEO sobre todos os artigos que planeou.

A API responde à pergunta que um relatório faz: o que publicámos, onde, em que idioma, e o que diz o artigo. Um endpoint por necessidade, uma forma fixa, nada para instalar — e nenhuma forma de uma integração escrever de volta no seu conteúdo.

Comece pelo seu domínio Comece pelo seu domínio
Leia a referência da API

JSON sobre HTTPSChave Bearer ou x-api-keySó de leitura, sempre

O que pode pedir à API de conteúdo?

Dois endpoints, cinco parâmetros, um envelope. É toda a superfície — e é por isso que não há nenhuma biblioteca cliente para manter atualizada.

A versão curta

  • Dois endpoints: uma lista de artigos e um artigo único por id numérico ou pelo seu prefixo `slug:` e o slug.
  • Os filtros são website, status, language, limit (predefinição 100, máximo 200) e offset.
  • Todos os artigos devolvem as mesmas 13 chaves de topo; um campo que ainda não foi gerado é uma string vazia em vez de ausente.
  • A autenticação é uma chave ao nível da conta, enviada como token Bearer ou cabeçalho x-api-key; o limite é de 120 pedidos por minuto.
  • É só de leitura. Nada na API pode alterar um artigo, uma data ou um site.
GET /api/v2/posts
Todos os artigos da conta, do mais recente para o mais antigo, com metadados de paginação. O tamanho de página é 100 por predefinição e aceita até 200; o offset percorre o resto.
GET /api/v2/posts/{id}
Um artigo pelo seu id numérico, ou por slug como `slug:o-seu-slug`, para que um CMS possa procurar um artigo pelo URL que já conhece.
?website=<domain>
Restringe a um site — o domínio principal ou o domínio do blog, sem distinguir maiúsculas. O filtro é aplicado antes da contagem, por isso a paginação mantém-se correta.
?status=published
O estado é comparado exatamente: draft, pending_approval, published, unpublished, in_progress, failed_review. Sem filtro, recebe todos — incluindo o que ainda está à espera.
?language=de
Uma linha editorial. Útil quando o mesmo tema existe em vários mercados e só um deles pertence a este relatório.
120 pedidos / minuto
Por conta, com um cabeçalho Retry-After quando o ultrapassa. Suficiente para uma sincronização noturna e uma pesquisa interna em tempo real; não é um endpoint de scraping.

Dois caminhos, duas formas

/api/v2/posts é o caminho atual, e /api/posts é um alias dele. /api/v1/posts continua a servir a forma plana original, congelada, para que uma integração existente continue a funcionar; os novos clientes devem começar em v2. Só o objeto do artigo difere — autenticação, filtros, códigos de estado e paginação são idênticos.

A referência completa

Todos os parâmetros, todos os campos do payload e todos os códigos de erro — com exemplos que pode copiar — estão na referência abaixo. Esta página é a visita guiada; essa é o contrato. referência da API de posts

Como se apresenta um artigo na transmissão.

Treze chaves de topo, todas sempre presentes. Três agrupam os campos que andam juntos, e o artigo viaja com os seus metadados, para que quem consome nunca tenha de fazer um segundo pedido para saber se um artigo está no ar.

GET/api/v2/posts?status=published&limit=1
Authorization: Bearer xt4b_••••••••••••
{
  "data": [
    {
      "id": "57",
      "status": "published",
      "slug": "seo-content-cost-per-article",
      "title": "Quanto custa o conteúdo SEO por artigo?",
      "meta": {
        "title": "Quanto custa o conteúdo SEO por artigo?",
        "description": "Three pricing models and what each one hides."
      },
      "searchIntent": "commercial",
      "keywords": {
        "primary": "quanto custa o conteúdo seo",
        "secondary": ["seo content pricing"]
      },
      "images": { "cover": "https://cdn.xt4b.com/…/cover.svg" },
      "language": "pt",
      "website": "xt4b.com",
      "publishedAt": "2026-09-11T09:00:04.118Z"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 7 }
}

A resposta é um envelope com data e pagination. Um artigo único devolve o mesmo objeto em data, por isso um só analisador trata ambos os pedidos.

Os campos que o pipeline ainda não produziu são strings vazias em vez de ausentes: um artigo planeado tem título, metadados, intenção e palavras-chave, e não tem markdown, capa nem data de publicação. Um cliente pode renderizar essa linha sem um único condicional para chaves ausentes.

A forma é um contrato, não uma conveniência. É o que o próprio blog do Xt4b e os seus painéis de Search Console leem, por isso uma nova coluna na base de dados não pode tornar-se silenciosamente num novo campo na sua integração.

O artigo, e o registo em volta dele.

Metade do payload é a peça que um leitor vê; metade é a proveniência de que um editor ou um relatório precisa.

O artigo

  • title — o título sob o qual o artigo é publicado
  • meta.title e meta.description — escritos para a SERP, não retirados do corpo
  • markdown — o artigo como fonte, que é o que edita
  • html — o mesmo artigo renderizado pelo publicador, âncoras de cabeçalho incluídas

O registo

  • id e slug — chaves estáveis em string, e o URL onde o artigo vive
  • status — onde o artigo está no pipeline, e não apenas se está no ar
  • website e language — que site, que mercado
  • publishedAt — data ISO, vazia enquanto ainda está planeado
  • keywords.primary, keywords.secondary e searchIntent — o briefing segundo o qual foi escrito
  • images.cover — a capa gerada

Do zero à sua primeira linha.

Quatro passos, e o quarto é uma linha de curl que pode colar num terminal ou num cron.

  1. 01

    Crie uma conta e ligue um site

    A API é uma janela sobre os seus próprios artigos, por isso precisa de um site e de um plano por trás. A análise gratuita mostra-lhe as pesquisas que faltam a um site antes de ligar algo.

  2. 02

    Copie a chave das Definições

    Uma chave por conta, mostrada na página de definições. Regenerá-la revoga a chave anterior de imediato, que é toda a história de rotação — não há client id, secret nem URL de callback.

  3. 03

    Envie-a como cabeçalho

    `Authorization: Bearer <key>` ou `x-api-key: <key>`. Qualquer uma funciona em todos os endpoints, por isso um script e uma ferramenta de browser podem usar a mais simples.

  4. 04

    Peça o que precisa

    Comece com `?status=published&limit=50` e depois restrinja com `website` e `language` quando conhecer a forma. Pagine com `offset` em vez de pedir artigos um a um.

Veja o que produz os artigos que esta API devolve

Três chamadas, copiar e colar.

A primeira devolve uma página de artigos no ar, a segunda procura um pelo slug do seu URL, a terceira pergunta o que ainda espera aprovação.

Liste o que está no ar, site a site

curl "https://xt4b.com/api/v2/posts?website=xt4b.com\
&status=published&limit=50" \
  -H "Authorization: Bearer $XT4B_API_KEY"

Um artigo, pelo slug do seu URL

curl "https://xt4b.com/api/v2/posts/\
slug:seo-content-cost-per-article" \
  -H "x-api-key: $XT4B_API_KEY"

O que espera por uma decisão

curl "https://xt4b.com/api/v2/posts?status=draft\
&language=de&limit=100&offset=0" \
  -H "Authorization: Bearer $XT4B_API_KEY"

O envelope de erro

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests — retry after 12s."
  }
}
Todos os parâmetros, todos os campos e todos os códigos de erro, com as respostas que recebe de volta

O que as pessoas constroem com isto.

As quatro integrações que surgem primeiro, pela ordem em que costumam ser construídas.

  1. 01

    Um relatório que se constrói sozinho

    Vá buscar os artigos com status=published uma vez por noite e escreva as linhas no seu painel. Sem fazer scraping do seu próprio blog, sem transcrever folhas de cálculo.

  2. 02

    O seu CMS como destino

    Se o blog vive noutro sítio, pegue no markdown (ou no HTML renderizado), nos metadados e nas imagens e publique-o você mesmo. A API é só de leitura, por isso nada aqui pode sobrepor-se ao que os seus editores escreveram.

  3. 03

    Pesquisa interna que é sua

    Filtre por site e idioma para construir uma caixa de pesquisa ou um bloco de artigos relacionados sobre o seu próprio arquivo — incluindo os artigos ainda em rascunho.

  4. 04

    Uma fila de controlo de qualidade

    Peça status=draft ou failed_review e reveja o que o pipeline produziu antes de ir para o ar, usando as suas próprias ferramentas em vez das nossas.

Para editores Para sites WordPress

O que a API não é.

Vale a pena dizê-lo com clareza, porque uma API de leitura é fácil de prometer a mais.

Não é um endpoint de geração
Não há nenhum POST que peça um artigo. O conteúdo é planeado e escrito pelo pipeline segundo um plano, e a API reporta o resultado.
Não é um endpoint de publicação
Nada do que envie pode alterar um artigo, uma data ou um site. Se um cliente quiser publicar através do seu próprio CMS, vai buscá-lo e publica-o lá — o modo de falha de uma integração má é um artigo em falta, nunca um artigo errado.
Não são chaves por site
Uma chave por conta, com ?website= como filtro. Mais simples de rodar, e significa que uma integração de agência se configura uma vez e não por cliente.
Não é uma promessa sobre posicionamento
Reporta o que foi publicado e o que um Search Console ligado mostra. Não pode reportar uma posição que ainda não existe, e nada disso garante tráfego ou receita — posicionamento, tráfego e receita não são garantidos por esta ou por qualquer outra API.

Mais sobre conteúdo

Perguntas que os programadores fazem.

Incluindo as duas sobre o que se recusa a fazer.

Há algum endpoint que escreva ou publique?

Não. A API é só de leitura por desenho: expõe o que o pipeline planeou e publicou, e nada nela pode alterar um artigo, uma data ou um site. A publicação acontece no painel, onde uma pessoa toma a decisão.

Como é a autenticação?

Uma chave por conta, mostrada nas suas definições, enviada como `Authorization: Bearer <key>` ou como cabeçalho `x-api-key`. Regenerar a chave revoga a antiga de imediato, e não há dança OAuth, nem client secret, nem nada para instalar.

Preciso de um SDK?

Não. É JSON sobre HTTPS, com um conjunto de filtros e um envelope — uma chamada fetch em qualquer linguagem, ou uma linha de curl num cron. A forma da resposta é fixa: todas as chaves estão presentes em todos os artigos, e os campos que ainda não foram gerados vêm como null em vez de ausentes.

Porque é que o markdown e o HTML renderizado são ambos devolvidos?

Porque a maioria de quem consome precisa de um deles. O markdown é o que edita e guarda; o HTML é o artigo tal como o publicador o renderiza, com âncoras de cabeçalho e links tratados, para que um site possa servir um artigo sem analisar markdown. Nenhum é derivado no momento do pedido — ambos são lidos da linha guardada.

A chave vê todos os sites da conta?

Sim — as chaves são por conta, e os sites são filtrados com ?website=. Para uma agência isso significa uma integração para todos os clientes, com o filtro de site como a única coisa que tem de mudar por relatório.

O que acontece quando atinjo o limite de pedidos?

Recebe um 429 com um cabeçalho Retry-After, e o contador é por conta numa janela fixa de um minuto. Pagine com limit e offset em vez de disparar pedidos por artigo: o limit aceita até 200.

Como obtenho uma chave de API?

É gerada por si: crie uma conta e a chave aparece na página de definições, pronta a copiar. Não há formulário de candidatura, nem cliente OAuth a registar, nem chave por site a distribuir.

Posso filtrar por intervalo de datas?

Não — os filtros são website, status, language, limit e offset. Os artigos chegam do mais recente para o mais antigo, por isso uma janela de datas é uma paginação: leve 200 de cada vez e pare quando publishedAt for mais antigo do que a janela que lhe interessa. É deliberado: um filtro de datas a meio suportado seria pior do que uma paginação honesta.

A API devolve artigos que ainda não estão publicados?

Sim, a menos que os filtre. Uma leitura sem filtro devolve todos os artigos com o seu estado, incluindo rascunhos, artigos à espera de aprovação e os que falharam a revisão — que é o que torna possível uma fila de controlo de qualidade. A maioria das integrações de relatório começa com ?status=published.

Há sandbox ou modo de teste?

Não. Há uma API e uma chave. Como a API é só de leitura, apontá-la a uma conta real é inofensivo — o pior que um erro pode fazer é devolver linhas de que não precisava.

Como são os erros?

O mesmo envelope que os dados: um objeto `error` com um `code` legível por máquina e uma mensagem — invalid_api_key (401), invalid_post_id (400), post_not_found (404), rate_limited (429). Nada devolve uma string solta, por isso um cliente pode ramificar pelo código em vez de analisar prosa.

Posso obter os dados sem usar o blog alojado?

É esse o objetivo de publicar a API. O blog é o destino predefinido porque elimina totalmente o trabalho de integração, mas os mesmos artigos estão disponíveis como dados, por isso um CMS existente, um build de site estático ou um armazém de dados podem ser o destino.

Uma chave, todos os sites

Publique no seu próprio domínio, leia-o como dados.

Crie uma conta e ligue um site: o pipeline produz os artigos, o blog serve-os, e a API entrega-lhe as linhas para o provar.

Automatizar o meu blogComece pelo seu domínio

Markdown e HTML renderizado120 pedidos por minuto3 dias grátis, sem cartão