Dokumentation för Publisher Revenue Audit API

Kör offentliga granskningar av utgivares intäkter, hämta Sulvo-rapporter och hantera godkända annonslager för utgivare via samma API-gränssnitt som CLI och MCP-servern använder.

Hostad basadress

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI- och MCP-konfiguration

Grunderna

Basadresser

Den offentliga gransknings-endpointen kräver avsiktligt ingen autentisering. Rapporter för Sulvo-konton och anrop för annonslager använder en API-nyckel som genererats i kontrollpanelen.

Offentligt gransknings-API

POST

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

Sulvo-konto-API

Bearer API-nyckel

https://surge.sulvo.com/api

Hostad MCP-endpoint

MCP

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

Offentlig endpoint

Kör en intäktsgranskning

Använd den här endpointen för en vägledande granskning av offentligt tillgängligt underlag för en utgivardomän. Svaret är inte ett bevis på intäktsbortfall eller garanterad ökning. Stäm av resultaten mot rapporteringen på utgivarsidan.

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

Fält	Anteckningar
input.domain	Obligatorisk utgivardomän eller offentlig värd. Domäner utan schema normaliseras till HTTPS. Privata mål, råa IP-adresser, interna värdar och portar som inte följer standard avvisas.
input.vertical	Valfritt. Godtar news, sports, entertainment, technology, education, gaming eller other.
input.metrics	Valfri kontext från utgivarens kontrollpanel, till exempel fyllnadsgrad, viewability, genomsnittlig CPM, intäkt per session, sidvisningar per månad eller sessioner per månad.
input.options	Valfria kontroller för utdata och insamling, inklusive format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel och partnerId.

Autentisering

Använd en Sulvo API-nyckel för konto-API:er

Skapa en API-nyckel i Sulvos kontrollpanel under Account Settings. Skicka den som en Bearer-token i API-anrop till Sulvo-konton.

Authorization-header

Authorization: Bearer $SULVO_API_KEY

reports:read

Krävs för rapportexporter och listning av sparade rapporter.

reports:write

Krävs för att skapa, uppdatera, köra eller ta bort avancerade rapporter.

inventory:write

Krävs för att skapa och ta bort annonsenheter. Kontot måste vara godkänt och äga annonslagret.

Rapporter

Läs rapport-endpoints

GET-anrop mot basadressen för Sulvo-konto-API:et används för att läsa rapporter. Värden som bara innehåller ett datum tolkas som hela dagar i UTC.

Rapportanrop

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	Daglig sammanfattning av prestanda. Stöder filter för datum, domän, annonsrot och leverantör.
GET	/api/v1/reports/by-date-and-ad-unit	Daglig prestanda grupperad efter annonsenhet.
GET	/api/v1/reports/by-domain-and-ad-unit	Uppdelning av prestanda efter domän och annonsenhet.
GET	/api/v1/reports/bot-filtering	Rapport om botfiltrering för granskning av kontots trafikkvalitet.
GET	/api/v1/reports/bot-scores	Rapportering av botpoäng efter datum och relaterade dimensioner.
GET	/api/v1/reports/invalid-activity	Rapportering av ogiltig aktivitet. Ingen standardfråga med datum eller domän krävs.
GET	/api/v1/reports/direct-bidder-analysis	Rapport om direktbudgivare. Kräver directBidder och kan innehålla start/end.
GET	/api/v1/inventory/ad-units-by-domain	Annonslager för annonsenheter grupperat efter domän.

Vanliga frågeparametrar: start, end, domains och adRoots som kan upprepas samt adProvider. Analys av direktbudgivare kräver även directBidder.

Avancerade rapporter

Skapa schemalagda eller omedelbara e-postrapporter

Avancerade rapporter kan köras direkt eller återkomma enligt ett schema. De skickas via e-post i stället för att returneras direkt i svaret.

Spara avancerad rapport

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	Lista sparade avancerade rapporter för det autentiserade kontot.
POST	/api/v2/reports/save-advanced-report	Skapa eller uppdatera en avancerad rapport. Kräver reportType, toAddress, immediateRun och minst ett mål i adRoots eller domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Ta bort en sparad avancerad rapport med dess id.

Rapporttyper

adUnit, dimensions, customData

Dimensioner

country, device, os

Frekvens

daily, weekly, biweekly, monthly

Annonslager

Skapa och ta bort godkända annonsenheter

Ändringar i annonslagret kräver ett godkänt Sulvo-konto och en API-nyckel som skapats av kontoägaren med behörighetsomfattningen inventory:write.

Skapa annonsenhet

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	Skapa en annonsenhet med domän, typ, valfri storlek, placering, anpassat namn och inställningar för focusedAd.
PUT	/api/v2/inventory/interstitial-units	Skapa interstitial-enheter för datorer och/eller mobiler för en domän.
PUT	/api/v2/inventory/auto-sticky-units	Skapa sticky display-enheter och/eller sticky-enheter för mobiler för en domän.
DELETE	/api/v2/inventory/unit/{adId}	Ta bort en annonsenhet som ägs av det autentiserade kontot.

Typer av annonsenheter som stöds

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Fel

Felhantering

Granskningssvar som inte är 2xx och fel från Sulvo-konto-API:et returnerar JSON-svar som är avsedda för agent- och CLI-klienter.

401

API-nyckeln saknas, är ogiltig eller har gått ut för anrop till konto-API:et. Den offentliga gransknings-endpointen kräver ingen nyckel.

403

Nyckeln autentiserades men saknar nödvändig behörighetsomfattning, kontot är inte godkänt eller resursen tillhör ett annat konto.

503 / 504

Den offentliga granskningstjänsten är överbelastad eller så tog granskningen för lång tid. Försök igen senare och följ Retry-After om den finns.

Felstruktur för granskning

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

Föredrar du en paketerad klient?

npm-paketet och MCP-konfigurationen anropar dessa endpoints åt dig och ger kompatibla AI-klienter tillgång till samma arbetsflöden för granskning, rapportering och annonslager.

Visa konfigurationen