REST · JSON · OpenAPI 3.1v1

Crie com os seus dados do Searvia

Leia rankings, visibilidade em IA, saúde do site, avaliações, fichas das lojas e estimativas de mercado a partir dos seus próprios scripts, dashboards e apps. A API executa as mesmas ferramentas do servidor MCP do Searvia, então limites do plano, créditos e escopo da conta são idênticos.

Seus projetos

curl https://searvia.com/api/v1/projects \
  -H "Authorization: Bearer $SEARVIA_API_KEY"

Arquivo OpenAPI Crie uma chave de API

Autenticação

Crie uma chave em Configurações › API e MCP e envie-a como token Bearer. Cada chave pertence a uma conta e vê apenas os dados dela. A mesma chave funciona no servidor MCP; apps conectados com OAuth também podem usar a API, e conexões somente leitura não podem alterar nada.

Limites e créditos

Por chave, por minuto
60 leituras, 30 alterações e 10 chamadas que usam créditos ou excluem.
Por mês
Chamadas de API e MCP compartilham um limite mensal: 100 no Free, 1.000 no Indie, ilimitado a partir do Starter.
Créditos
Chamadas marcadas como "Usa créditos" debitam do saldo da conta na hora, sem prévia. Sem créditos suficientes, a chamada retorna 402 e nada é executado.

Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Ao atingir um limite, você recebe 429 com Retry-After.

Respostas, erros e páginas

Resultado

{
  "data": [ ... ],
  "meta": { "page": 1, "per_page": 50, "total": 120, "last_page": 3 }
}

Erro

{
  "error": {
    "status": 422,
    "code": "validation_failed",
    "message": "Missing required field: keywords.",
    "errors": { "keywords": ["The keywords field is required."] }
  }
}

As listas aceitam page e per_page (até 200) e enviam um cabeçalho Link com as páginas seguinte e anterior. Códigos de erro: unauthenticated, payment_required, forbidden, not_found, validation_failed, rate_limited, unavailable e server_error.

Endpoints

Account

GET	/account/usage	Plan, credits, quotas and this month's API and MCP calls.	Leitura
GET	/audit-logs	Audit log of the account (owners and admins).	Leitura

Projects

GET	/projects	Projects (websites and apps) of the account.	Leitura
GET	/projects/{project_id}	Overview of one project: rankings, visibility, reviews and open growth actions.	Leitura
GET	/projects/{project_id}/competitors	Tracked competitors of a project.	Leitura

Rankings

GET	/projects/{project_id}/keywords	Tracked keywords with current rank, 1 and 7 day change, popularity, difficulty and daily history.	Leitura
POST	/projects/{project_id}/keywords	Track keywords (within the plan quota; the first check runs right away).	Alterar
DELETE	/projects/{project_id}/keywords	Stop tracking keywords (by text or id).	Exclui
POST	/projects/{project_id}/rankings/refresh	Check rankings now.	Alterar
GET	/keywords/{keyword_id}/history	Daily rank history of one keyword with competitor ranks.	Leitura

Domains

GET	/domain-analyses	Domain analyses of the account.	Leitura
POST	/domain-analyses	Analyze a domain (uses credits): traffic, keywords, top pages, page types, competitors and backlinks.	Usa créditos
GET	/domain-analyses/{analysis_id}	One domain analysis.	Leitura

Site health

GET	/projects/{project_id}/site-health	Latest site audit, AI discoverability, security scan and page speed of a website project.	Leitura
POST	/projects/{project_id}/site-audits	Start a site audit (at most once an hour).	Alterar
GET	/site-audits/{audit_id}	Issues and pages of one site audit.	Leitura
GET	/projects/{project_id}/backlinks	Backlink summary with new and lost links.	Leitura

AI visibility

GET	/projects/{project_id}/ai-visibility	AI visibility summary, questions and latest answers of a project.	Leitura
POST	/projects/{project_id}/ai-visibility/questions	Track AI questions (one per line in `prompts`).	Alterar
GET	/ai-visibility/questions/{prompt_id}	Timeline and answers of one AI question.	Leitura

Apps

GET	/projects/{project_id}/reviews	Store reviews of an app project.	Leitura
GET	/projects/{project_id}/metadata	Store listing of an app project per language (including the App Store keyword field when connected).	Leitura

Market

GET	/market/apps/{app_id}	Estimated revenue, downloads and chart history of any App Store app.	Leitura
GET	/market/top-earning	Top earning or fastest growing apps by country and category.	Leitura
GET	/market/new-winners	Recently released apps that already earn.	Leitura

Reports

GET	/projects/{project_id}/reports/rankings	One row per keyword and day: rank, checked depth and competitor ranks.	Leitura
GET	/projects/{project_id}/reports/ai-visibility	One row per AI answer: question, platform, mentioned, cited, source position and sentiment.	Leitura
GET	/projects/{project_id}/reports/site-health	One row per site audit: health score, AI discoverability score, errors, warnings and pages.	Leitura

Os campos de caminho, query e corpo de cada endpoint estão no arquivo OpenAPI; importe-o no Postman, no Insomnia ou em um gerador de código.

Dashboards e registros

Conector do Looker Studio
Rankings diários, respostas de visibilidade em IA e pontuações de saúde do site como fontes de dados do Looker Studio, criadas sobre os endpoints de relatórios. Cada linha é uma palavra-chave e dia, uma resposta de IA ou uma auditoria.
Configurar o conector
Registro de auditoria
Toda alteração e gasto de créditos feito com uma chave é registrado com nome da chave, alvo, IP e resultado, junto com as alterações do painel e do MCP. Proprietários e administradores podem ver em Configurações › Segurança ou em /audit-logs.
Sobre o registro de auditoria