De Publisher Revenue Audit API

Voer openbare audits van publisheromzet uit, haal Sulvo-rapporten op en beheer goedgekeurde inventory voor publishers via dezelfde API die ook door de CLI en MCP-server wordt gebruikt.

Gehoste basis-URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsInstallatie van CLI en MCP

Basis

Basis-URL’s

Het openbare audit-endpoint vereist bewust geen authenticatie. Voor Sulvo-accountrapporten en inventory-aanroepen wordt een API-sleutel gebruikt die in het dashboard is gegenereerd.

Openbare audit-API

POST

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

Sulvo-account-API

Bearer-API-sleutel

https://surge.sulvo.com/api

Gehost MCP-endpoint

MCP

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

Openbaar endpoint

Voer een omzetaudit uit

Gebruik dit endpoint voor een indicatieve audit van openbare gegevens voor een publisherdomein. De respons vormt geen bewijs voor omzetverlies en biedt geen garantie op omzetstijging. Toets de bevindingen aan uw eigen rapportage als publisher.

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
      }
    }
  }'

Veld	Opmerkingen
input.domain	Vereist publisherdomein of openbare host. Losse domeinnamen worden genormaliseerd naar HTTPS. Doelen op privénetwerken, ruwe IP-adressen, interne hosts en niet-standaardpoorten worden geweigerd.
input.vertical	Optioneel. Accepteert news, sports, entertainment, technology, education, gaming of other.
input.metrics	Optionele dashboardcontext die de publisher aanlevert, zoals fill rate, viewability, gemiddelde CPM, omzet per sessie, paginaweergaven per maand of sessies per maand.
input.options	Optionele instellingen voor uitvoer en verzameling, waaronder format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel en partnerId.

Authenticatie

Gebruik een Sulvo-API-sleutel voor account-API’s

Genereer een API-sleutel in het Sulvo-dashboard onder Account Settings. Verstuur deze als Bearer-token bij API-verzoeken aan de Sulvo-account-API.

Authorization-header

Authorization: Bearer $SULVO_API_KEY

reports:read

Vereist voor rapportexporten en overzichten van opgeslagen rapporten.

reports:write

Vereist om geavanceerde rapporten aan te maken, bij te werken, uit te voeren of te verwijderen.

inventory:write

Vereist voor het aanmaken en verwijderen van advertentie-eenheden. Het account moet zijn goedgekeurd en eigenaar van de inventory zijn.

Rapporten

Rapporten ophalen

Rapporten worden opgehaald met GET-verzoeken via de basis-URL van de Sulvo-account-API. Datumwaarden zonder tijd worden geïnterpreteerd als grenzen van een volledige UTC-dag.

Rapportverzoek

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	Dagelijks prestatieoverzicht. Ondersteunt filters voor date, domain, ad root en provider.
GET	/api/v1/reports/by-date-and-ad-unit	Dagelijkse prestaties gegroepeerd per advertentie-eenheid.
GET	/api/v1/reports/by-domain-and-ad-unit	Uitsplitsing van prestaties per domein en advertentie-eenheid.
GET	/api/v1/reports/bot-filtering	Rapport over botfiltering voor beoordeling van de accountverkeerskwaliteit.
GET	/api/v1/reports/bot-scores	Rapportage van botscores per datum en gerelateerde dimensies.
GET	/api/v1/reports/invalid-activity	Rapportage van ongeldige activiteit. Een standaardquery voor date/domain is niet vereist.
GET	/api/v1/reports/direct-bidder-analysis	Rapport over directe bieders. Vereist directBidder en kan start/end bevatten.
GET	/api/v1/inventory/ad-units-by-domain	Inventory van advertentie-eenheden gegroepeerd per domein.

Veelgebruikte queryparameters: start, end, herhaalbare domains, herhaalbare adRoots en adProvider. Voor de analyse van directe bieders is ook directBidder vereist.

Geavanceerde rapporten

Geplande of directe e-mailrapporten aanmaken

Geavanceerde rapporten kunnen direct of volgens een terugkerend schema worden uitgevoerd. Ze worden per e-mail verzonden in plaats van inline geretourneerd.

Geavanceerd rapport opslaan

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	Lijst met opgeslagen geavanceerde rapporten voor het geauthenticeerde account.
POST	/api/v2/reports/save-advanced-report	Maak een geavanceerd rapport aan of werk het bij. Vereist reportType, toAddress, immediateRun en ten minste één doel in adRoots of domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Verwijder een opgeslagen geavanceerd rapport op basis van id.

Rapporttypen

adUnit, dimensions, customData

Dimensies

country, device, os

Frequentie

daily, weekly, biweekly, monthly

Inventory

Goedgekeurde advertentie-eenheden aanmaken en verwijderen

Voor schrijfacties op inventory zijn een goedgekeurd Sulvo-account en een door de eigenaar aangemaakte API-sleutel met de scope inventory:write vereist.

Advertentie-eenheid aanmaken

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	Maak één advertentie-eenheid aan met de instellingen domain, type, optioneel size, placement, custom name en focusedAd.
PUT	/api/v2/inventory/interstitial-units	Maak interstitial-advertentie-eenheden voor desktop en/of mobiel aan op een domein.
PUT	/api/v2/inventory/auto-sticky-units	Maak sticky-advertentie-eenheden voor display en/of mobiel aan op een domein.
DELETE	/api/v2/inventory/unit/{adId}	Verwijder een advertentie-eenheid die eigendom is van het geauthenticeerde account.

Ondersteunde typen advertentie-eenheden

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Fouten

Fouten afhandelen

Auditresponsen met een andere status dan 2xx en fouten van de Sulvo-account-API leveren JSON-responsen op die zijn bedoeld voor agent- en CLI-clients.

401

De API-sleutel ontbreekt, is ongeldig of is verlopen voor API-verzoeken voor het account. Voor het openbare audit-endpoint is geen sleutel nodig.

403

De sleutel is geauthenticeerd maar heeft niet de vereiste scope, het account is niet goedgekeurd of de resource hoort bij een ander account.

503 / 504

De openbare auditservice is overbelast of er is een time-out opgetreden bij de audit. Probeer het later opnieuw en houd rekening met Retry-After als die header aanwezig is.

Foutstructuur van de audit

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

Liever een kant-en-klare client?

Het npm-pakket en de MCP-installatie roepen deze endpoints voor u aan en bieden dezelfde workflows voor audits, rapporten en inventory aan compatibele AI-clients.

Bekijk de installatie