Documentação da API

API REST Nexarticle

Integre geração de artigos, criação de imagens e publicação no WordPress no seu workflow.

Início Rápido

Comece com a API do Nexarticle em 3 passos. Você precisa de uma conta e uma chave API ou token de acesso.

1. Obtenha sua chave API

Vá em Configurações → Chaves API no seu dashboard e crie uma nova chave. A chave é exibida apenas uma vez — copie e guarde com segurança.

2. Faça sua primeira requisição

Teste a conexão buscando seu perfil. Substitua YOUR_ACCESS_TOKEN por um token JWT obtido em /auth/login.

bash

curl -X GET https://api.nexarticle.com/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

3. Crie um artigo

Envie uma requisição POST para criar um novo artigo. O artigo será criado como rascunho — depois você pode configurar subtítulos e gerar o conteúdo completo.

bash

curl -X POST https://api.nexarticle.com/api/v1/workspaces/{workspace_id}/articles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Best SEO Strategies for 2025",
    "type": "blog_post",
    "primary_keyword": "SEO strategies",
    "language": "en",
    "tone": "Professional",
    "article_length": "medium"
  }'

Autenticação

A API suporta dois métodos de autenticação: Bearer tokens (JWT) e chaves API. Todos os endpoints com escopo de workspace também requerem o header X-Workspace-Id.

Bearer Token (JWT)

Obtenha um par de tokens chamando POST /auth/login com email e senha. Use o access_token no header Authorization. Tokens expiram em 30 minutos — use /auth/refresh para obter um novo par.

http

Authorization: Bearer YOUR_ACCESS_TOKEN

Chave API

Para acesso programático, crie uma chave API em Configurações → Chaves API. Envie a chave no header X-API-Key. Cada chave tem escopo de um workspace específico.

http

X-API-Key: nxa_your_api_key_here

Chaves API têm o prefixo nxa_ e são exibidas apenas na criação. Guarde-as com segurança.

Header de Workspace

Endpoints com escopo de workspace (artigos, imagens, etc.) requerem o header X-Workspace-Id com o UUID do seu workspace.

http

X-Workspace-Id: your-workspace-uuid

Exemplo de Login (obter token JWT)

bash

curl -X POST https://api.nexarticle.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

# Response:
# {
#   "access_token": "eyJ...",
#   "refresh_token": "eyJ...",
#   "token_type": "bearer"
# }

Artigos

Crie, gerencie e gere artigos otimizados para SEO. Artigos passam por: criar (rascunho) → configurar → gerar → publicar.

POST

/workspaces/{workspace_id}/articles

Criar um novo artigo (rascunho)

GET

/workspaces/{workspace_id}/articles

Listar artigos com filtros (status, tipo, busca)

GET

/articles/{article_id}

Obter detalhes do artigo com produtos

PATCH

/articles/{article_id}

Atualizar título, conteúdo, tags do artigo

DELETE

/articles/{article_id}

Excluir artigo (soft-delete)

POST

/articles/{article_id}/prepare

Gerar título SEO + subtítulos H2/H3

PATCH

/articles/{article_id}/config

Salvar configuração pré-geração (toggles, subtítulos)

POST

/articles/{article_id}/generate

Iniciar pipeline de geração completa do artigo

POST

/articles/{article_id}/regenerate

Regenerar artigo do zero

POST

/articles/{article_id}/publish

Publicar artigo no WordPress

Criar Artigo — Exemplo JavaScript

javascript

const response = await fetch(
  "https://api.nexarticle.com/api/v1/workspaces/{workspace_id}/articles",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "10 Best SEO Tools in 2025",
      type: "listicle",
      primary_keyword: "best SEO tools",
      secondary_keywords: "SEO software, SEO analytics",
      language: "en",
      tone: "Professional",
      article_length: "long",
    }),
  }
);

const article = await response.json();
console.log(article.id); // UUID of the created article

Listar Artigos — Exemplo cURL

bash

# List articles with filters
curl "https://api.nexarticle.com/api/v1/workspaces/{workspace_id}/articles?status=ready&type=blog_post&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Query params: status, type, search, limit (1-100), offset

Imagens

Gere imagens com DALL-E 3. Imagens são processadas de forma assíncrona — consulte pelo ID ou use o endpoint de listagem para verificar o status.

POST

/workspaces/{workspace_id}/images

Gerar uma nova imagem (enfileirada para processamento assíncrono)

GET

/workspaces/{workspace_id}/images

Listar imagens no workspace

GET

/images/{image_id}

Obter detalhes da imagem e URL de download

DELETE

/images/{image_id}

Excluir imagem (soft-delete)

GET

/images/styles

Listar estilos de imagem disponíveis (34 estilos)

Gerar Imagem — Exemplo cURL

bash

curl -X POST "https://api.nexarticle.com/api/v1/workspaces/{workspace_id}/images" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Modern office workspace with plants, minimalist design",
    "provider": "dalle3",
    "model": "dall-e-3",
    "size": "1024x1024",
    "style": "natural"
  }'

WordPress

Conecte sites WordPress e publique artigos diretamente com blocos Gutenberg e metadados Yoast SEO.

POST

/workspaces/{workspace_id}/wordpress-sites

Adicionar conexão com site WordPress

GET

/workspaces/{workspace_id}/wordpress-sites

Listar sites WordPress conectados

POST

/wordpress-sites/{site_id}/test

Testar conexão com um site WordPress

POST

/wordpress-sites/{site_id}/sync-categories

Sincronizar categorias do WordPress para cache

POST

/articles/{article_id}/publish

Publicar um artigo no WordPress

Publicar no WordPress — Exemplo cURL

bash

curl -X POST "https://api.nexarticle.com/api/v1/articles/{article_id}/publish" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wordpress_site_id": "site-uuid",
    "status": "publish",
    "category_id": 5,
    "tags": "seo, content marketing"
  }'

Automações

Crie e gerencie campanhas de conteúdo automatizadas. O Autopilot gera artigos em um cronograma com otimização SEO completa.

apiDocs.automations.crudHeading

POST

/api/v1/automations

Criar uma nova campanha de automação com palavras-chave, modelo de IA e cronograma

GET

/api/v1/automations

Listar todas as automações do workspace (paginado)

GET

/api/v1/automations/{id}

Obter informações detalhadas da automação incluindo resumo dos itens

PATCH

/api/v1/automations/{id}

Atualizar configurações da automação (apenas rascunho ou pausada)

DELETE

/api/v1/automations/{id}

Excluir uma automação e todos os seus itens (apenas admin)

apiDocs.automations.lifecycleHeading

POST

/api/v1/automations/{id}/start

Iniciar uma automação em rascunho ou agendada

POST

/api/v1/automations/{id}/pause

Pausar uma automação em execução

POST

/api/v1/automations/{id}/resume

Retomar uma automação pausada

POST

/api/v1/automations/{id}/cancel

Cancelar uma automação — opcionalmente excluir artigos rascunho (apenas admin)

apiDocs.automations.itemsHeading

GET

/api/v1/automations/{id}/items

Listar itens de uma automação (filtrável por status)

PATCH

/api/v1/automations/{id}/items/{item_id}

Atualizar título ou data agendada de um item

POST

/api/v1/automations/{id}/items/reorder

Reordenar itens fornecendo nova ordem de posição

apiDocs.automations.aiHeading

POST

/api/v1/automations/expand-with-titles

Gerar pares de palavra-chave + título a partir de um tópico usando IA

POST

/api/v1/automations/estimate-cost

Estimar contagem de palavras e custo para uma campanha

POST

/api/v1/automations/{id}/add-keywords

Adicionar novas palavras-chave a uma campanha existente (evergreen)

apiDocs.automations.createExample

bash

curl -X POST "https://api.nexarticle.com/api/v1/automations" \
  -H "X-API-Key: nxa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly SEO Blog Posts",
    "mode": "drip",
    "article_type": "blog_post",
    "language": "en",
    "tone": "Professional",
    "article_length": "long",
    "keywords": ["best seo tools", "content marketing tips"],
    "interval_hours": 168,
    "total_articles": 10
  }'

apiDocs.automations.expandExample

javascript

const response = await fetch(
  "https://api.nexarticle.com/api/v1/automations/expand-with-titles",
  {
    method: "POST",
    headers: {
      "X-API-Key": "nxa_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      seed_keyword: "content marketing",
      count: 5,
      article_type: "blog_post",
    }),
  }
);

const { keywords } = await response.json();
// [{ keyword: "content marketing strategy", title: "..." }, ...]

apiDocs.automations.lifecycleExample

bash

# Start an automation campaign
curl -X POST "https://api.nexarticle.com/api/v1/automations/{id}/start" \
  -H "X-API-Key: nxa_your_api_key"

# Pause a running campaign
curl -X POST "https://api.nexarticle.com/api/v1/automations/{id}/pause" \
  -H "X-API-Key: nxa_your_api_key"

# Resume a paused campaign
curl -X POST "https://api.nexarticle.com/api/v1/automations/{id}/resume" \
  -H "X-API-Key: nxa_your_api_key"

Códigos de Erro

A API retorna códigos de status HTTP padrão. Respostas de erro incluem um campo detail com uma mensagem legível.

Código	Significado
`200`	Sucesso — requisição completada
`201`	Recurso criado com sucesso
`202`	Requisição aceita — processando de forma assíncrona (geração, publicação)
`400`	Corpo da requisição ou parâmetros inválidos
`401`	Token de autenticação ausente ou inválido
`402`	Limite do plano excedido — upgrade necessário
`403`	Permissões insuficientes para esta ação
`404`	Recurso não encontrado
`429`	Limite de requisições excedido — reduza a frequência
`500`	Erro interno do servidor — tente novamente mais tarde

Formato da Resposta de Erro

json

{
  "detail": "Article not found"
}

URL Base

text

https://api.nexarticle.com/api/v1

Todos os endpoints são relativos a esta URL base. Em desenvolvimento, use http://localhost:8000/api/v1.