Référence de Publisher Revenue Audit API

Lancez des analyses publiques de revenus d’éditeurs, récupérez des rapports Sulvo et gérez l’inventaire approuvé des éditeurs via la même interface API que celle utilisée par la CLI et le serveur MCP.

URL de base hébergée

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsConfiguration CLI et MCP

Notions de base

URL de base

L’endpoint d’audit public ne nécessite volontairement aucune authentification. Les appels aux rapports de compte et à l’inventaire Sulvo utilisent une clé API générée dans le tableau de bord.

API d’audit public

POST

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-audits

API de compte Sulvo

Clé API Bearer

https://surge.sulvo.com/api

Endpoint MCP hébergé

MCP

https://publisher-revenue-audit.sulvo.com/mcp

Endpoint public

Lancer un audit des revenus

Utilisez cet endpoint pour obtenir une analyse indicative fondée sur les indices publics d’un domaine éditeur. La réponse ne prouve pas une perte de revenus et ne garantit aucune hausse. Validez les constats avec vos rapports côté éditeur.

cURL

curl -X POST https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-audits \
  -H "content-type: application/json" \
  -d '{
    "tool": "run_publisher_revenue_audit",
    "input": {
      "domain": "example.com",
      "vertical": "news",
      "options": {
        "format": "json",
        "compact": true,
        "maxPages": 2,
        "enablePageSpeed": true
      }
    }
  }'

Champ	Remarques
input.domain	Domaine d’éditeur ou hôte public obligatoire. Les domaines seuls sont normalisés en HTTPS. Les cibles privées, adresses IP brutes, hôtes internes et ports non standard sont refusés.
input.vertical	Facultatif. Accepte news, sports, entertainment, technology, education, gaming ou other.
input.metrics	Contexte facultatif fourni par l’éditeur, par exemple taux de remplissage, visibilité, CPM moyen, revenus par session, pages vues mensuelles ou sessions mensuelles.
input.options	Options facultatives de sortie et de collecte, notamment format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel et partnerId.

Authentification

Utiliser une clé API Sulvo pour les API de compte

Générez une clé API dans le tableau de bord Sulvo, sous Account Settings. Envoyez-la comme jeton Bearer dans les requêtes aux API de compte Sulvo.

En-tête Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Requis pour exporter des rapports et répertorier les rapports enregistrés.

reports:write

Requis pour créer, mettre à jour, exécuter ou supprimer des rapports avancés.

inventory:write

Requis pour créer et supprimer des blocs publicitaires. Le compte doit être approuvé et posséder l’inventaire.

Rapports

Consulter les endpoints de rapports

Les requêtes de lecture des rapports utilisent la méthode GET sous l’URL de base de l’API de compte Sulvo. Les dates seules sont interprétées comme des journées complètes en UTC.

Requête de rapport

curl "https://surge.sulvo.com/api/v1/reports/by-date?start=2026-06-01&end=2026-06-07&domains=example.com" \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "accept: application/json"

Method	Path	Notes
GET	/api/v1/reports/by-date	Synthèse des performances quotidiennes. Accepte les filtres par date, domaine, racine publicitaire et fournisseur.
GET	/api/v1/reports/by-date-and-ad-unit	Performances quotidiennes regroupées par bloc publicitaire.
GET	/api/v1/reports/by-domain-and-ad-unit	Ventilation des performances par domaine et par bloc publicitaire.
GET	/api/v1/reports/bot-filtering	Rapport de filtrage des robots pour examiner la qualité du trafic du compte.
GET	/api/v1/reports/bot-scores	Rapport des scores de robots par date et dimensions associées.
GET	/api/v1/reports/invalid-activity	Rapport sur l’activité invalide. Aucune requête standard par date ou domaine n’est requise.
GET	/api/v1/reports/direct-bidder-analysis	Rapport sur les enchérisseurs directs. Nécessite directBidder et peut inclure start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventaire des blocs publicitaires regroupé par domaine.

Paramètres de requête courants : start, end, domains répétable, adRoots répétable et adProvider. L’analyse des enchérisseurs directs nécessite aussi directBidder.

Rapports avancés

Créer des rapports par e-mail, planifiés ou immédiats

Les rapports avancés peuvent être exécutés immédiatement ou selon un calendrier récurrent. Ils sont envoyés par e-mail au lieu d’être renvoyés directement dans la réponse.

Enregistrer un rapport avancé

curl -X POST https://surge.sulvo.com/api/v2/reports/save-advanced-report \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "reportType": "dimensions",
    "toAddress": "publisher@example.com",
    "immediateRun": true,
    "domains": ["example.com"],
    "dimensions": ["country", "device"],
    "start": "2026-06-01",
    "end": "2026-06-07"
  }'

Method	Path	Notes
GET	/api/v2/reports/advanced-reports	Répertorier les rapports avancés enregistrés pour le compte authentifié.
POST	/api/v2/reports/save-advanced-report	Créer ou mettre à jour un rapport avancé. Nécessite reportType, toAddress, immediateRun et au moins une cible adRoots ou domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Supprimer un rapport avancé enregistré à partir de son identifiant.

Types de rapport

adUnit, dimensions, customData

Dimensions

country, device, os

Fréquence

daily, weekly, biweekly, monthly

Inventaire

Créer et supprimer des blocs publicitaires approuvés

La modification de l’inventaire nécessite un compte Sulvo approuvé et une clé API créée par son propriétaire, dotée du périmètre inventory:write.

Créer un bloc publicitaire

curl -X PUT https://surge.sulvo.com/api/v2/inventory/unit \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "domain": "example.com",
    "type": "display",
    "size": { "width": 300, "height": 250 }
  }'

Method	Path	Notes
PUT	/api/v2/inventory/unit	Créer un bloc publicitaire unique avec domaine, type, taille facultative, emplacement, nom personnalisé et paramètres focusedAd.
PUT	/api/v2/inventory/interstitial-units	Créer des blocs interstitiels pour ordinateur et/ou mobile pour un domaine.
PUT	/api/v2/inventory/auto-sticky-units	Créer des blocs sticky display et/ou sticky mobile pour un domaine.
DELETE	/api/v2/inventory/unit/{adId}	Supprimer un bloc publicitaire appartenant au compte authentifié.

Types de blocs publicitaires pris en charge

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Erreurs

Gestion des erreurs

Les réponses d’audit hors de la plage 2xx et les échecs des API de compte Sulvo renvoient des corps JSON conçus pour les clients agent et CLI.

401

La clé API est absente, invalide ou expirée pour les appels aux API de compte. L’endpoint d’audit public ne nécessite pas de clé.

403

La clé a été authentifiée, mais l’accès reste refusé si le périmètre requis lui manque, si le compte n’est pas approuvé ou si la ressource appartient à un autre compte.

503 / 504

Le service d’audit public est saturé ou l’audit a dépassé le délai imparti. Réessayez plus tard et respectez Retry-After lorsqu’il est présent.

Enveloppe d’erreur d’audit

{
  "error": {
    "code": "audit_capacity_exceeded",
    "message": "Audit capacity is currently exhausted. Retry later."
  }
}

Vous préférez un client sous forme de package ?

Le package npm et la configuration MCP appellent ces endpoints à votre place et exposent les mêmes flux d’audit, de rapports et d’inventaire aux clients IA compatibles.

Voir la configuration