REST · JSON · OpenAPI 3.1v1

Crea sobre tus datos de Searvia

Lee rankings, visibilidad en IA, salud del sitio, reseñas, fichas de tiendas y estimaciones de mercado desde tus propios scripts, paneles y apps. La API ejecuta las mismas herramientas que el servidor MCP de Searvia, así que los límites del plan, los créditos y el alcance de la cuenta son idénticos.

Tus proyectos

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

Archivo OpenAPI Crea una clave de API

Autenticación

Crea una clave en Ajustes › API y MCP y envíala como token Bearer. Una clave pertenece a una sola cuenta y solo ve los datos de esa cuenta. La misma clave sirve para el servidor MCP; las apps conectadas con OAuth también pueden usar la API, y las conexiones de solo lectura no pueden cambiar nada.

Límites y créditos

Por clave, por minuto
60 lecturas, 30 cambios y 10 llamadas que usan créditos o eliminan.
Por mes
Las llamadas a la API y a MCP comparten un límite mensual: 100 en Free, 1000 en Indie, ilimitadas desde Starter.
Créditos
Las llamadas marcadas como "Usa créditos" los descuentan del saldo de la cuenta al instante, sin vista previa. Si no hay créditos suficientes, la llamada devuelve 402 y no se ejecuta nada.

Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Si alcanzas un límite, recibes 429 con Retry-After.

Respuestas, errores y páginas

Resultado

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

Error

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

Las listas aceptan page y per_page (hasta 200) y envían un encabezado Link con las páginas siguiente y anterior. Códigos de error: unauthenticated, payment_required, forbidden, not_found, validation_failed, rate_limited, unavailable y server_error.

Endpoints

Account

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

Projects

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

Rankings

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

Domains

GET	/domain-analyses	Domain analyses of the account.	Lectura
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.	Lectura

Site health

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

AI visibility

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

Apps

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

Market

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

Reports

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

Los campos de ruta, consulta y cuerpo de cada endpoint están en el archivo OpenAPI; impórtalo en Postman, Insomnia o un generador de código.

Paneles y registros

Conector de Looker Studio
Rankings diarios, respuestas de visibilidad en IA y puntuaciones de salud del sitio como fuentes de datos de Looker Studio, basadas en los endpoints de informes. Cada fila es una palabra clave y un día, una respuesta de IA o una auditoría.
Configurar el conector
Registro de auditoría
Cada cambio y gasto de créditos hecho con una clave se registra con el nombre de la clave, el objetivo, la IP y el resultado, junto a los cambios del panel y de MCP. Los propietarios y administradores lo consultan en Ajustes › Seguridad o en /audit-logs.
Sobre el registro de auditoría