Documentação da API

Este guia explica como chamar o SEOforGPT por HTTP. Use uma chave de API para servidores e scripts, ou um token de sessão quando chamar pelo navegador.

EntrarDepois de entrar, abra o menu do usuário no canto superior direito e escolha API Keys para criar e gerenciar chaves.

Visão geral

A API Pública v1 é a superfície HTTP para scripts, jobs de CI, ferramentas internas e agentes que precisam listar projetos, rodar fluxos de visibilidade, buscar relatórios, gerar conteúdo ou gerenciar chaves de API.

Toda requisição é vinculada ao usuário autenticado e respeita acesso do plano, cota e limites por rota. Para uso em servidor, prefira uma chave de API. Para chamadas do navegador ou do app, use um JWT de sessão autenticada.

https://www.seoforgpt.io/api/v1

Use quando

Você quer uma API HTTP estável para automação, jobs em segundo plano, ferramentas de CLI ou fluxos com agentes.

Envelope de sucesso

Respostas bem-sucedidas usam { data, meta }.meta.billinginclui pistas de plano e cota.

Arquivo OpenAPI (opcional)

Se você usa ferramentas que importam OpenAPI, como geradores de código ou clientes de API, abra openapi.json em uma nova aba. Ele lista as mesmas rotas desta página em JSON. Ferramentas em nuvem que precisam buscar o arquivo pela internet pública, como alguns Custom GPTs, devem usar https://www.seoforgpt.io/openapi.json. Se você é novo em APIs, pode ignorar OpenAPI e seguir as seções abaixo. Esta página é o guia principal.

Obter uma chave de API

Entre. Depois abra o menu do usuário no canto superior direito e escolha API Keys para criar uma chave. As chaves aparecem apenas uma vez no momento da criação. Você pode ter até 10 chaves.

Entrar para gerenciar chaves

Claude: Para ferramentas de chat em vez de HTTP direto, use o conector hospedado conector MCP em /mcp (OAuth). Isso dá ao assistente as mesmas ações de produto do app, não o formato REST documentado aqui.

Outros assistentes: Se um produto oferece suporte a uma URL MCP remota, é o mesmo endpoint /mcp da nossa docs MCP. Compatibilidade e configuração variam por fornecedor. Se você tiver apenas ações HTTP, conecte uma ação baseada em OpenAPI: use o schema público https://www.seoforgpt.io/openapi.json (prévia openapi.json em uma nova aba) com Bearer e uma chave de API de usuário (sgpt_…). Mais ajuda: Desenvolvedores, Outros assistentes (MCP).

Autenticação

Envie um token bearer no cabeçalho da requisição. Use uma chave de API para scripts e automação no servidor. Use um JWT ao chamar a partir de uma sessão autenticada no navegador ou ao criar, listar ou excluir chaves de API.

Cabeçalho

Authorization: Bearer <your_api_key_or_jwt>

Chaves de API têm formato sgpt_... e são a escolha certa para CI, cron e agentes.
JWTs vêm de uma sessão de usuário autenticada e são obrigatórios para gerenciamento de /keys.

Início rápido

Se você precisa de apenas um fluxo confiável, siga esta ordem: liste projetos, escolha um projeto, rode um fluxo de visibilidade e busque o relatório.

1. Listar projetos
Comece com GET /projects e escolha o projeto com que deseja trabalhar.
2. Rodar visibilidade
Use POST /analyze/project para os prompts salvos do projeto, ou POST /analyze/custom para prompts e marcas ad hoc.
3. Buscar o relatório
Use GET /reports/:id com o data.id retornado ou GET /reports/latest se precisar apenas do relatório mais recente de um projeto.

Fluxos de visibilidade

Estas rotas rodam os mesmos fluxos de visibilidade de marca usados no app. Elas são a API central para monitoramento recorrente e experimentos pontuais de visibilidade.

Todas as rotas de visibilidade consomem cota de visibilidade. Use o data.id retornado com uma rota de relatório. Em execuções assíncronas, consulte até o status retornado ser terminal.

POST /analyze/project (recomendado)

Use quando quiser os prompts salvos do projeto no SEOforGPT. Corpo: apenas projectId. Retorna 202 enquanto jobs multiprovedor rodam, ou 200 quando o relatório já está completo.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/analyze/project \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>"}'

POST /analyze/custom

Use para conjuntos de prompts ad hoc ou uma marca diferente da salva no app. Corpo: projectId, brand, prompts (strings ou objetos { prompt }), além de competitors opcional. Máximo de 20 prompts. Retorna HTTP 200 com um id de relatório do tipo visibility_analysis_api.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/analyze/custom \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","brand":"YourBrand","prompts":["query 1","query 2"]}'

POST /analyze

Dispatcher legado. Ainda é suportado, mas novas integrações devem preferir as rotas explícitas acima. Aceita testId, projectId + brand + prompts, projectId + brand + crawlRecordId, ou apenas projectId.

Relatórios

As rotas de relatório permitem buscar o relatório mais recente de um projeto ou um relatório específico por id. Relatórios de visibilidade aceitam três visualizações: raw, summary e full.

raw retorna linhas normalizadas de baixo nível.
summary é o relatório compacto padrão.
full retorna o relatório mais rico, no estilo dashboard, com tendências, fontes e lacunas.

GET /reports/latest

Use quando não quiser controlar um id de relatório por conta própria. Parâmetros de query: projectId obrigatório, source=main|custom opcional, view=raw|summary|full opcional.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/latest?projectId=<uuid>&source=main&view=full" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

GET /reports/:id

Busca um id de relatório específico. O data.type retornado é visibility_analysis, visibility_analysis_api ou generated_content. Relatórios de visibilidade aceitam o mesmo parâmetro view.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/REPORT_ID_FROM_PREVIOUS_STEP?view=full" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

Após 202 de /analyze/project, consulte esta rota até data.status ser terminal.

GET /reports/:id/provider-answer

Use esta rota de aprofundamento para buscar uma resposta bruta de provedor e citações depois de ler um relatório full seguro para agentes com answer_detail=summary.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/REPORT_ID/provider-answer?promptKey=<prompt>&provider=openai" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

Helpers seguros para agentes

Estas rotas compõem os novos tools do MCP e retornam respostas compactas para assistentes. Use-as quando precisar de tendência, detalhe de concorrente, brief de cliente ou ações de agência sem baixar um relatório completo.

Method

Route

Uso

GET

/projects/:projectId/visibility-trends

Tendência compacta de score de visibilidade, taxa de aparição e contagem de concorrentes monitorados. Rank fica oculto.

GET

/projects/:projectId/competitors/:competitor

Detalhe compacto de um concorrente, com ameaça baseada em menções e lacunas de visibilidade.

GET

/projects/:projectId/client-brief

Brief para agência com tendência, concorrente, domínios citados, prompts perdidos e três próximas ações.

POST

/projects/:projectId/share-links

Cria um link público de relatório. O corpo aceita timeframe, expiry, presenterName, logoUrl e summary.

GET

/client-workspaces

Lista workspaces de clientes e pitches para contas de agência.

GET

/account-status

Retorna plano, cota, status do workspace e acesso a recursos.

POST

/projects/:projectId/publish-to-cms

Publica um conteúdo gerado existente no CMS conectado.

Geração de conteúdo

Use POST /generate-content quando quiser que o SEOforGPT crie um rascunho a partir do contexto do projeto. Esta rota consome cota de conteúdo e retorna um id de relatório para buscar depois.

POST /generate-content

Corpo: projectId, platform (blog, linkedin, thread), topic, além de metadata e promptType opcionais.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/generate-content \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","platform":"blog","topic":"How to measure AI search visibility"}'

A resposta inclui data.id para GET /reports/:id.
Também retorna context_quality e context_message para você saber se o rascunho usou análise de site concluída.

Prontidão e auxiliares de prompt

Estas rotas são úteis quando você quer saída de prontidão do site ou sugestões de prompts em automações. Elas são rotas reais da API pública, mesmo sendo mais avançadas que os fluxos principais de visibilidade e conteúdo.

POST /readiness

Roda o mesmo fluxo de prontidão de site do app. Corpo: projectId obrigatório, forceRerun opcional e substituição url opcional. A resposta inclui data.id, data.cached e data.result.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/readiness \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","forceRerun":false}'

POST /suggest-prompts

Gera sugestões de prompts a partir de um crawl existente. Corpo: crawlRecordId obrigatório, projectId opcional, brand opcional e competitors opcional. A resposta inclui prompt_count e pode incluir um id de teste salvo em report_url.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/suggest-prompts \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"crawlRecordId":"<uuid>","projectId":"<uuid>"}'

Chaves de API

Rotas de gerenciamento de chaves exigem um JWT de uma sessão autenticada, não uma chave de API. O valor secreto real da chave só é retornado uma vez, no momento da criação.

POST /keys

Cria uma chave de API. Corpo: name opcional e expires_at opcional. Retorna HTTP 201 com data.key.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/keys \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"CI automation","expires_at":"2026-06-01T00:00:00.000Z"}'

GET /keys

Liste suas chaves de API com prefixo, nome, data de criação, último uso e expiração.

DELETE /keys/:id

Exclui uma chave de API pertencente ao usuário autenticado.

Erros e limites

Erros da API retornam um envelope previsível. Respostas com limite de taxa também incluem cabeçalhos de nova tentativa, como Retry-After e X-RateLimit-*.

{
  "error": {
    "code": "BILLING_REQUIRED",
    "message": "content quota exceeded",
    "details": {
      "remaining": 0
    },
    "request_id": "0d2c2e3d-5f04-43e2-a8fb-f5d0b92e7ab1"
  }
}

400: Entrada inválida
401: Token ausente ou inválido
402: Bloqueio de cobrança ou cota
404: Recurso não encontrado
409: Conflito (por exemplo, limite de chaves de API atingido)
429: Limite de taxa excedido
500: Erro do servidor