REST · JSON · OpenAPI 3.1v1

Construisez sur vos données Searvia

Lisez classements, visibilité IA, santé du site, avis, fiches de stores et estimations de marché depuis vos propres scripts, tableaux de bord et apps. L'API exécute les mêmes outils que le serveur MCP Searvia : limites du plan, crédits et périmètre du compte sont identiques.

Vos projets

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

Fichier OpenAPI Créer une clé API

Authentification

Créez une clé dans Paramètres › API et MCP et envoyez-la comme jeton Bearer. Une clé appartient à un seul compte et ne voit que les données de ce compte. La même clé fonctionne pour le serveur MCP ; les apps connectées via OAuth peuvent aussi utiliser l'API, et les connexions en lecture seule ne peuvent rien modifier.

Limites et crédits

Par clé, par minute
60 lectures, 30 modifications et 10 appels qui utilisent des crédits ou suppriment.
Par mois
Les appels API et MCP partagent une limite mensuelle : 100 en Free, 1 000 en Indie, illimité à partir de Starter.
Crédits
Les appels marqués « Utilise des crédits » les prélèvent immédiatement du solde du compte, sans aperçu. Sans crédits suffisants, l'appel renvoie 402 et rien n'est exécuté.

Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Quand vous atteignez une limite, vous recevez 429 avec Retry-After.

Réponses, erreurs et pages

Résultat

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

Erreur

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

Les listes acceptent page et per_page (jusqu'à 200) et envoient un en-tête Link avec les pages suivante et précédente. Codes d'erreur : unauthenticated, payment_required, forbidden, not_found, validation_failed, rate_limited, unavailable et server_error.

Endpoints

Account

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

Projects

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

Rankings

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

Domains

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

Site health

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

AI visibility

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

Apps

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

Market

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

Reports

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

Les champs de chemin, de requête et de corps de chaque endpoint figurent dans le fichier OpenAPI ; importez-le dans Postman, Insomnia ou un générateur de code.

Tableaux de bord et enregistrements

Connecteur Looker Studio
Classements quotidiens, réponses de visibilité IA et scores de santé du site comme sources de données Looker Studio, basés sur les endpoints de rapports. Chaque ligne correspond à un mot-clé et un jour, une réponse IA ou un audit.
Configurer le connecteur
Journal d'audit
Chaque modification et dépense de crédits effectuée avec une clé est enregistrée avec le nom de la clé, la cible, l'IP et le résultat, à côté des changements du panneau et de MCP. Les propriétaires et admins la consultent dans Paramètres › Sécurité ou sur /audit-logs.
À propos du journal d'audit