📋 Sommaire

Quickstart Auth Rate-limits Endpoints Webhooks Errors SDK

⚙️ API v1 · disponible Pro+

API publique ScoreIA · Docs v1

REST API avec auth Bearer token, webhooks signés HMAC, rate-limits par tier. Intègre l'audit GEO, le Revenue Oracle, le Competitor Battle dans ton workflow / CRM / dashboard agence en quelques lignes de code.

⚡ Quickstart en 30 secondes

curl -X POST https://scoreia.ai/api/v1/audit \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://exemple.fr"}'

Réponse :

{
  "success": true,
  "url": "https://exemple.fr",
  "seo_score": 84,
  "geo_score": 67,
  "composite": 75,
  "top_issues": [
    {"text": "Schema Organization manquant", "fix": "Ajouter JSON-LD", "type": "error"},
    {"text": "TL;DR above-the-fold absent", "fix": "Bloc 30-60 mots", "type": "warning"}
  ],
  "calls_this_month": 1,
  "limit": 1000
}

🔑 Authentication

Chaque requête doit inclure le header :

Authorization: Bearer sk_live_YOUR_KEY

Les clés API ont le préfixe sk_live_. Elles sont liées à un tier (free/solo/pro/agency/enterprise) qui détermine ton quota mensuel.

⚠ Comment obtenir une clé ?
· Solo / Pro / Agency : self-service via /api-keys après login (Pro+ uniquement).
· Enterprise : clé délivrée par notre équipe avec SLA + fair-use cap personnalisé. Écris à [email protected] (réponse < 24h).

📊 Rate-limits par tier

Tier	Quota	Période	Endpoints
Free	10	par jour / IP	/audit only (sans token)
Solo (49€)	100	par mois	/audit · /account
Pro (129€)	1 000	par mois	tous v1
Agency (229€)	10 000	par mois	tous v1 + webhooks
Enterprise (499€)	∞	illimité	tous v1 + webhooks priority + SSO

Quand tu dépasses : HTTP 429 quota_exceeded. Le compteur reset le 1er de chaque mois calendaire (ou 30j après inscription).

📡 Endpoints v1

GET/api/v1/health

Public, no auth. Returns server status.

GET/api/v1/account

Tes infos : tier, quota usage, derniers calls.

soloproagencyenterprise

POST/api/v1/audit

Audit Lite (8 signaux + Mini KG) sur une URL.

soloproagencyenterprise

Body :

{"url": "https://exemple.fr", "mode": "free"}

POST/api/v1/revenue-oracle

Projection € sur 30/90/180j selon mutations entity graph.

proagencyenterprise

Body :

{
  "url": "https://exemple.fr",
  "arpu": 240,
  "conversion_pct": 2.0,
  "traffic_mo": 5000,
  "mutations": ["schema_sameas", "co_citations", "eeat_author"],
  "scenario": "realistic"
}

Mutations valides : schema_sameas · schema_person_org · wikidata_entry · co_citations · cross_linking · eeat_author · press_links · video_speakable · news_liveblog

Scenarios : conservative (×0.55) · realistic (×1.0) · ambitious (×1.35)

POST/api/v1/competitor-battle

Toi vs 1-3 concurrents : composite + capture IA + revenue 180j chacun + verdict.

proagencyenterprise

Body :

{
  "target_url": "https://tonsite.fr",
  "competitor_urls": ["https://concurrent1.com", "https://concurrent2.com"],
  "arpu": 240,
  "conversion_pct": 2.0,
  "traffic_mo": 1000
}

🔔 Webhooks (Slack/Discord/custom URL)

Configure une URL qui sera POSTée à chaque événement. Body signé HMAC-SHA256.

POST/api/v1/webhooks

Crée un webhook pour ton compte.

agencyenterprise

Body :

{
  "email": "[email protected]",
  "url": "https://hooks.slack.com/services/T0/B0/XYZ",
  "events": ["audit.complete", "score.drop", "regret.threshold", "competitor.overtake"]
}

Réponse : {ok: true, id: 1, secret: "whsec_...", events: [...]}

GET/api/v1/webhooks

Liste tes webhooks avec last_fired_at + failure_count.

Events disponibles

Event	Trigger	Payload
`audit.complete`	Audit terminé	url, composite, geo, seo
`score.drop`	Score chute > 5 pts vs précédent	url, before, after, delta
`regret.threshold`	Time Travel regret > X €	url, regret_eur, period_months
`competitor.overtake`	Concurrent te dépasse de 10+ pts	your_url, comp_url, your_composite, comp_composite

Vérifier la signature webhook

Chaque POST envoie un header X-ScoreIA-Signature: sha256=.... Calcule HMAC-SHA256 du body avec ton whsec_* :

// Node.js
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody).digest('hex');
const received = req.headers['x-scoreia-signature'].replace('sha256=', '');
if (crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  // Valid signature, process event
}

⚠️ Errors

Status	Code	Cause
200	OK	Success
400	invalid_url	URL invalide ou bloquée (SSRF)
401	unauthorized	Token manquant, invalide, ou révoqué
429	quota_exceeded	Limite mensuelle atteinte (cf rate-limits)
500	audit_failed	Erreur interne (timeout crawler, parse fail)

📚 SDKs (à venir)

JavaScript/TypeScript · npm install @scoreia/sdk · juin 2026
Python · pip install scoreia · juin 2026
OpenAPI 3.0 spec · disponible à /api/v1/openapi.json · v1.1

En attendant, l'API étant REST simple, n'importe quel HTTP client fait l'affaire (curl, fetch, axios, requests, etc.).

✓ Privacy · les payloads d'audit ne sont pas envoyés à des LLMs externes (sauf la version cross-validation 5 LLMs sur tier Pro+ qui appelle Anthropic/OpenAI/Google/xAI/DeepSeek). Aucune donnée user persistée au-delà de la table api_calls (pour le quota).

Tu veux ta clé API ?

Crée ton compte Pro+ (129€/mo) ou contact direct pour Enterprise. Webhooks débloquent à partir d'Agency (229€/mo).

Créer mon compte Voir les tiers 29€/mo à vie