# Naia API
> Plataforma de Generative Engine Optimization (GEO) — analise e otimize a visibilidade de marcas em motores de IA.

## Autenticacao
Todas as chamadas requerem header: Authorization: Bearer naia_SUA_API_KEY
Gere sua key em: https://naia.today/dashboard/settings/api

## Base URL
https://naia.today/api/v1

## MCP Server
URL: https://naia.today/api/v1/mcp
Protocolo: JSON-RPC 2.0
Autenticacao: mesma API key no header Authorization

### Configuracao Claude Code
claude mcp add naia-api --transport http --url https://naia.today/api/v1/mcp --header "Authorization: Bearer naia_SUA_KEY"

### Configuracao Cursor / Windsurf (.cursor/mcp.json)
{"mcpServers":{"naia":{"url":"https://naia.today/api/v1/mcp","headers":{"Authorization":"Bearer naia_SUA_KEY"}}}}

## Endpoints

### Marcas (Businesses)
- GET /businesses — Listar marcas do usuario
- POST /businesses — Criar marca {name, category, city, state, country?, url?}
- GET /businesses/:id — Detalhe da marca
- PUT /businesses/:id — Atualizar marca
- DELETE /businesses/:id — Remover marca (soft-delete, scope admin)
- POST /businesses/:id/enrich — Enriquecimento AI (gratis)
- GET /businesses/:id/queries — Search queries configuradas
- PUT /businesses/:id/queries — Atualizar queries {queries: string[]}

### Analises GEO
- POST /analyses — Disparar analise {businessId, models?: string[]}. Retorna {analysisId, pollUrl}. Consome creditos.
- GET /analyses/:id — Status e resultados. Polling ate status="completed".
- GET /analyses/:id/recommendations — Recomendacoes de otimizacao.

### Conteudo
- GET /content?businessId=X — Listar conteudo (paginado: page, pageSize, search)
- POST /content — Gerar conteudo {businessId, templateSlug, topic}. 5 creditos. Templates: blog-post, ultimate-guide, comparison, faq, landing-page, case-study, schema.
- GET /content/:id — Detalhe completo com draft/briefing
- PATCH /content/:id — Aprovar/desaprovar conteudo (toggle)

### Planos de Execucao
- GET /execution-plans?businessId=X — Listar planos com progresso
- POST /execution-plans — Gerar plano {analysisId}. 5 creditos.
- GET /execution-plans/:id — Detalhe com fases e tarefas
- PATCH /execution-plans/:id/tasks/:taskId — Atualizar status {status: backlog|in_progress|review|completed}
- POST /execution-plans/:id/tasks/:taskId/generate — Gerar conteudo da tarefa. 5 creditos.
- POST /execution-plans/:id/tasks/bulk-generate — Gerar em lote {taskIds: string[]}. Max 10, 5 creditos/peca.

### Creditos
- GET /credits — Saldo atual {balance, lifetimePurchased, lifetimeUsed}

### Webhooks
- GET /webhooks — Listar endpoints (scope admin)
- POST /webhooks — Registrar {url, events}. HTTPS obrigatorio. Secret retornado 1x.
- DELETE /webhooks?id=X — Remover endpoint (scope admin)
- Eventos: analysis.completed, analysis.failed, content.completed, content.failed, execution_plan.ready
- Assinatura: X-Naia-Signature: sha256=HMAC

### API Keys
- GET /keys — Listar keys (scope admin)
- POST /keys — Criar key {name, scopes}. Key retornada 1x. Scopes: read, write, admin.
- DELETE /keys?id=X — Revogar key (scope admin)

## Scopes
- read: GET endpoints
- write: POST, PUT, PATCH endpoints
- admin: DELETE + gerenciamento de keys/webhooks

## Rate Limit
200 req/min por API key (configuravel). Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

## Custos
- Analise GEO: variavel (por modelo selecionado)
- Plano de execucao: 5 creditos
- Conteudo (por peca): 5 creditos
- Enriquecimento: gratis
- Leitura (GET): gratis

## MCP Tools Disponiveis
list_businesses, get_business, create_business, preview_business, confirm_create_business, trigger_analysis, get_analysis, get_recommendations, list_content, get_content, create_content, approve_content, get_credits, list_execution_plans, get_execution_plan, create_execution_plan, generate_task_content, update_task_status, get_queries, update_queries

## Agent Skill (Claude Code / SkillsMP)
https://github.com/arielvdl/naia-skills

## Documentacao completa
https://naia.today/developers