L'API Pharone vous permet de lancer des audits programmatiquement, de suivre leur progression en temps réel via SSE, et de récupérer les résultats complets.

Base URL

https://api.pharone.ai

Tous les exemples ci-dessous utilisent cette URL de base.

Endpoints

POST /api/audit

Lance un audit sur une URL. Retourne immédiatement un audit_id — le traitement se fait en arrière-plan.

Body :

{ "url": "https://www.example.com" }

Réponse 202 :

{ "audit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }

Erreur 422 (URL invalide ou SSRF bloquée) :

{
  "detail": [
    { "loc": ["body", "url"], "msg": "URL invalide ou accès refusé", "type": "value_error" }
  ]
}

Exemple :

curl -X POST https://api.pharone.ai/api/audit \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com"}'

Ouvre un flux Server-Sent Events pour suivre la progression de l'audit en temps réel. Reconnectable — si le client se déconnecte, il reçoit un événement sync à la reconnexion qui rejoue l'état complet.

Headers de réponse :

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Événements SSE :

Événement	Quand	Données
`sync`	Connexion / reconnexion	État complet (phase, agents, scores, pages)
`crawl_start`	Début du crawl	`{ url, audit_id }`
`crawl_done`	Fin du crawl	`{ pages_count, sitemap_found, robots_found, llms_txt_found, business_type, site_alerts[] }`
`agent_start`	Début d'un agent	`{ agent_id }`
`agent_done`	Fin d'un agent	`{ agent_id, score, checks[], tokens_used }`
`complete`	Audit terminé	`{ audit_id, overall_score, ai_score, pages_audited, agents{}, total_issues, total_tokens }`
`error`	Erreur fatale	`{ message, audit_id }`

Structure de l'événement sync :

{
  "type": "sync",
  "data": {
    "phase": "agents",
    "agents_completed": ["technical", "on_page"],
    "agents_pending": ["content", "schema", "performance", "images", "links", "ai_readiness", "aeo", "sitemap", "visual"],
    "agents_scores": { "technical": 72, "on_page": 65 },
    "pages_crawled": 8,
    "pages_total": 10
  }
}

Exemple JavaScript :

const source = new EventSource(`/api/audit/${auditId}/stream`);

source.addEventListener('agent_done', (e) => {
  const { agent_id, score } = JSON.parse(e.data);
  console.log(`${agent_id}: ${score}/100`);
});

source.addEventListener('complete', (e) => {
  const result = JSON.parse(e.data);
  console.log(`Score global: ${result.overall_score}/100`);
  source.close();
});

GET /api/audit/{id}

Récupère le résultat complet d'un audit terminé.

Réponse 200 :

{
  "audit_id": "a1b2c3d4-...",
  "url": "https://www.example.com",
  "started_at": "2026-03-01T14:32:00Z",
  "finished_at": "2026-03-01T14:34:15Z",
  "overall_score": 68,
  "ai_score": 52,
  "status": "complete",
  "agents": {
    "technical": {
      "agent_id": "technical",
      "score": 72,
      "issues": [
        {
          "priority": "high",
          "title": "Balise canonical absente sur 3 pages",
          "detail": "Les pages /about, /services et /contact n'ont pas de balise canonical.",
          "recommendation": "Ajouter <link rel=\"canonical\" href=\"[url-canonique]\"> dans le <head> de chaque page.",
          "affected_urls": ["/about", "/services", "/contact"]
        }
      ],
      "checks": [
        {
          "name": "robots.txt accessible",
          "status": "pass",
          "detail": "Fichier présent et valide à https://www.example.com/robots.txt"
        }
      ],
      "tokens_used": 1240,
      "score_confidence": "high",
      "score_justification": "Site bien structuré techniquement avec quelques issues de canonical à corriger."
    }
  },
  "progress": {
    "phase": "complete",
    "agents_completed": ["technical", "content", "on_page", "schema", "performance", "images", "links", "ai_readiness", "aeo", "sitemap", "visual"],
    "agents_pending": [],
    "pages_crawled": 10,
    "pages_total": 10
  }
}

Erreur 404 : audit introuvable.

GET /api/audits

Récupère la liste de tous les audits (plus récents en premier).

Réponse 200 :

[
  {
    "audit_id": "a1b2c3d4-...",
    "url": "https://www.example.com",
    "started_at": "2026-03-01T14:32:00Z",
    "finished_at": "2026-03-01T14:34:15Z",
    "overall_score": 68,
    "status": "complete"
  }
]

POST /api/audit/{id}/retry/{agent_id}

Relance un agent spécifique sans répéter le crawl. Utile quand un agent a échoué (timeout, erreur réseau).

agent_id valides : technical, content, on_page, schema, performance, images, links, ai_readiness, aeo, sitemap, visual

Réponse 202 :

{ "status": "retrying", "agent_id": "technical" }

Après cette requête, reconnectez-vous au stream SSE pour suivre la progression.

Exemple :

curl -X POST https://api.pharone.ai/api/audit/a1b2c3d4/retry/technical

DELETE /api/audit/{id}

Supprime un audit de la base de données.

Réponse : 204 No Content

GET /health

Vérifie l'état du serveur et de la base de données.

Réponse 200 :

{ "status": "ok", "db": "ok" }

Structures de données

AuditStatus

Valeur	Signification
`running`	Audit en cours
`complete`	Audit terminé avec succès
`error`	Audit terminé avec une erreur fatale

IssuePriority

Valeur	Couleur	Description
`critical`	🔴 Rouge	Bloque l'indexation ou cause une pénalité
`high`	🟠 Orange	Impact significatif sur le classement
`medium`	🟡 Jaune	Opportunité d'optimisation
`low`	⚪ Gris	Amélioration mineure

CheckStatus

Valeur	Signification
`pass`	Vérification réussie
`fail`	Problème détecté
`warn`	Avertissement
`info`	Information (pas d'impact direct)

BusinessType

Détecté automatiquement pendant le crawl pour adapter les recommandations :

Valeur	Signification
`local`	Commerce local, artisan, restaurant
`saas`	Application SaaS, logiciel
`ecommerce`	Boutique en ligne
`publisher`	Blog, média, site éditorial
`agency`	Agence, cabinet de conseil
`other`	Autre

Codes d'erreur HTTP

Code	Signification
`202`	Audit lancé en arrière-plan
`204`	Suppression réussie
`404`	Audit introuvable
`422`	Validation échouée (URL invalide, SSRF bloquée)
`500`	Erreur serveur interne

Limites et plans

Plan	Audits/mois	Pages/audit	Rétention
Starter	5	100	30 jours
Growth	Illimité	500	90 jours
Pro	Illimité	2 000	Illimitée

Intégration complète — exemple Node.js

async function runAudit(url) {
  // 1. Lancer l'audit
  const res = await fetch('https://api.pharone.ai/api/audit', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url }),
  });
  const { audit_id } = await res.json();

  // 2. Suivre la progression
  await new Promise((resolve, reject) => {
    const source = new EventSource(`https://api.pharone.ai/api/audit/${audit_id}/stream`);

    source.addEventListener('agent_done', (e) => {
      const { agent_id, score } = JSON.parse(e.data);
      console.log(`✓ ${agent_id}: ${score}/100`);
    });

    source.addEventListener('complete', (e) => {
      source.close();
      resolve(JSON.parse(e.data));
    });

    source.addEventListener('error', (e) => {
      source.close();
      reject(new Error(e.data ? JSON.parse(e.data).message : 'Erreur inconnue'));
    });
  });

  // 3. Récupérer le résultat complet
  const report = await fetch(`https://api.pharone.ai/api/audit/${audit_id}`);
  return report.json();
}

// Usage
const result = await runAudit('https://www.example.com');
console.log(`Score global : ${result.overall_score}/100`);

Référence API

Base URL

Endpoints

POST /api/audit

GET /api/audit/{id}/stream

GET /api/audit/{id}

GET /api/audits

POST /api/audit/{id}/retry/{agent_id}

DELETE /api/audit/{id}

GET /health

Structures de données

AuditStatus

IssuePriority

CheckStatus

BusinessType

Codes d'erreur HTTP

Limites et plans

Intégration complète — exemple Node.js