Autenticacao

Todas as requisicoes precisam do header X-API-Key ou Authorization: Bearer:

curl https://app.rankforge.com.br/api/v1/credits \
  -H "X-API-Key: rf_live_xxxxxxxxxxxxxxxx"

Chaves tem 3 escopos default:

Scope	Permite
articles:write	Gerar artigos (consome creditos)
jobs:read	Consultar status de jobs
credits:read	Consultar saldo de creditos

Rate Limits

Endpoint	Limite
POST /api/v1/articles	60 requisicoes/min
GET /api/v1/jobs/{id}	120 requisicoes/min
GET /api/v1/credits	60 requisicoes/min

Creditos

Cada chamada que dispara geracao consome creditos do plano vinculado a chave:

Operacao	Custo
Criar artigo	1 credito
Consultar status / saldo	0 (gratis)

Saldo insuficiente retorna HTTP 402 insufficient_credits.

Endpoint: Criar Artigo

POST/api/v1/articles

Gera artigo SEO em modo standalone (sem publicar em CMS). Retorna job_id pra polling.

Body

Campo	Tipo	Default	Descricao
keyword	string	—	Obrigatorio. Palavra-chave principal (max 200 chars)
size	string	medium	short (~800), medium (~1500), long (~2500), xl (~3500), xxl (~5000)
language	string	pt-BR	pt-BR, en-US, es-ES
tone	string	informativo	tom de voz
h2_count	int	5	Numero de subtitulos (3-15)
faq	boolean	false	Incluir secao FAQ com schema.org
summary	boolean	false	Incluir resumo no inicio
conclusion	boolean	true	Incluir conclusao
image_bank	string	ia	ia (Gemini) ou produto
subtitle_images	string	intercalado	todos, intercalado, nenhuma
custom_prompt	string	—	Instrucoes adicionais (max 1000 chars)

Exemplo

curl -X POST https://app.rankforge.com.br/api/v1/articles \
  -H "X-API-Key: rf_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "como gerar leads B2B em 2026",
    "size": "long",
    "h2_count": 7,
    "faq": true,
    "language": "pt-BR"
  }'

Response 202 Accepted

{
  "success": true,
  "job_id": "abc12345-...",
  "status": "pending",
  "status_url": "https://app.rankforge.com.br/api/v1/jobs/abc12345-...",
  "estimated_seconds": 145,
  "credits_consumed": 1,
  "credits_remaining": 49
}

Endpoint: Status do Job

GET/api/v1/jobs/{id}

Consulta status. Faca polling a cada 10-15 segundos ate status === 'completed'.

Response (completed)

{
  "id": "abc12345-...",
  "keyword": "como gerar leads B2B em 2026",
  "status": "completed",
  "created_at": "2026-05-01T20:00:00Z",
  "completed_at": "2026-05-01T20:02:30Z",
  "output": {
    "title": "Como Gerar Leads B2B em 2026: Guia Completo",
    "slug": "como-gerar-leads-b2b-em-2026",
    "meta_description": "Descubra as 7 estrategias mais eficazes...",
    "html": "<h1>Como Gerar Leads B2B em 2026...</h1>...",
    "word_count": 2487,
    "images": [
      {"url": "https://app.rankforge.com.br/uploads/standalone/abc12345/featured.webp", "alt": "..."},
      {"url": "...", "alt": "..."}
    ],
    "preview_url": "https://app.rankforge.com.br/article-preview.php?job_id=abc12345-..."
  }
}

Status possiveis

Status	Significa
pending	Job criado, aguardando processamento
processing	Engine gerando o artigo
completed	Pronto, output disponivel
failed	Falhou (ver error_message) — credito refundado

Endpoint: Saldo

GET/api/v1/credits

Retorna saldo de creditos do plano vinculado a chave.

Response

{
  "monthly_limit": 50,
  "monthly_used": 12,
  "monthly_available": 38,
  "extra_credits": 0,
  "total_available": 38,
  "plan": "professional",
  "subscription_status": "active",
  "renewal_date": "2026-06-01"
}

Codigos de Erro

HTTP	Codigo	Significa
400	invalid_keyword	keyword vazia ou > 200 chars
401	invalid_api_key	Chave invalida, expirada ou revogada
402	insufficient_credits	Saldo insuficiente
403	insufficient_scope	Chave nao tem o scope necessario
429	rate_limit_exceeded	Excedeu rate limit (ver tabela acima)
500	internal_error	Erro do servidor (refund automatico se aplicavel)

Exemplo Completo (Node.js)

const API_KEY = process.env.RANKFORGE_API_KEY;
const BASE = 'https://app.rankforge.com.br/api/v1';

async function generateArticle(keyword) {
  // 1. Cria job
  const create = await fetch(`${BASE}/articles`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ keyword, size: 'long', faq: true })
  });
  const { job_id } = await create.json();

  // 2. Polling ate completed
  while (true) {
    await new Promise(r => setTimeout(r, 10000));
    const status = await fetch(`${BASE}/jobs/${job_id}`, {
      headers: { 'X-API-Key': API_KEY }
    });
    const data = await status.json();
    if (data.status === 'completed') return data.output;
    if (data.status === 'failed') throw new Error(data.error_message);
  }
}

generateArticle('como criar funil B2B 2026').then(article => {
  console.log('Title:', article.title);
  console.log('HTML:', article.html.length, 'chars');
  console.log('Images:', article.images.length);
  // Salvar em arquivo, postar em CMS, etc
});

Suporte

Bug, duvida ou request de feature: chama no email contato@rankforge.com.br