Publisher Revenue Audit API

Kjør offentlige kontroller av utgiverinntekter, hent Sulvo-rapporter og administrer godkjent utgiverannonsebeholdning gjennom det samme API-et som CLI og MCP-serveren bruker.

Basisadresse for hostet API

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsOppsett av CLI og MCP

Grunnleggende

Basisadresser

Det offentlige audit-endepunktet er med hensikt åpent uten autentisering. Sulvo-kontorapporter og kall for annonsebeholdning bruker en API-nøkkel som opprettes i dashbordet.

Offentlig audit-API

POST

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

Sulvo-konto-API

Bearer API-nøkkel

https://surge.sulvo.com/api

Hostet MCP-endepunkt

MCP

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

Offentlig endepunkt

Kjør en inntektsaudit

Bruk dette endepunktet til en veiledende kontroll av offentlig tilgjengelige data på et utgiverdomene. Svaret er ikke et bevis på inntektstap eller en garantert økning. Valider funnene mot rapporteringen på utgiversiden.

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

Felt	Merknader
input.domain	Påkrevd. Utgiverens domene eller offentlige vert. Domenenavn uten protokoll normaliseres til HTTPS. Private mål, rå IP-adresser, interne verter og porter som ikke er standard, avvises.
input.vertical	Valgfritt. Godtar news, sports, entertainment, technology, education, gaming eller other.
input.metrics	Valgfritt. Kontekst fra utgiverens dashbord, for eksempel fyllingsgrad, synlighet, gjennomsnittlig CPM, inntekt per økt, månedlige sidevisninger eller månedlige økter.
input.options	Valgfritt. Kontroller for utdata og innsamling, blant annet format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel og partnerId.

Autentisering

Bruk en Sulvo API-nøkkel for konto-API-er

Opprett en API-nøkkel i Sulvo-dashbordet under Account Settings. Send den som et Bearer-token i forespørsler til Sulvos konto-API.

Authorization-header

Authorization: Bearer $SULVO_API_KEY

reports:read

Påkrevd for rapporteksport og visning av listen over lagrede rapporter.

reports:write

Påkrevd for å opprette, oppdatere, kjøre eller slette avanserte rapporter.

inventory:write

Påkrevd for å opprette og slette annonseenheter. Kontoen må være godkjent og eie annonsebeholdningen.

Rapporter

Les rapportendepunkter

Rapportendepunkter for lesing bruker GET-forespørsler under Sulvos konto-API-basisadresse. Datoer uten klokkeslett tolkes som hele UTC-dager.

Rapportforespørsel

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 ytelsesoppsummering. Støtter filtre for dato, domene, annonserot og leverandør.
GET	/api/v1/reports/by-date-and-ad-unit	Daglig ytelse gruppert etter annonseenhet.
GET	/api/v1/reports/by-domain-and-ad-unit	Ytelsesfordeling etter domene og annonseenhet.
GET	/api/v1/reports/bot-filtering	Rapport om botfiltrering for gjennomgang av kontotrafikkens kvalitet.
GET	/api/v1/reports/bot-scores	Rapportering av botpoeng etter dato og tilknyttede dimensjoner.
GET	/api/v1/reports/invalid-activity	Rapportering av ugyldig aktivitet. Ingen standardspørring for dato eller domene er påkrevd.
GET	/api/v1/reports/direct-bidder-analysis	Rapport for direkte budgivere. Krever directBidder og kan inkludere start/end.
GET	/api/v1/inventory/ad-units-by-domain	Annonseenheter i beholdningen, gruppert etter domene.

Vanlige spørringsparametere: start, end, repeterbare domains, repeterbare adRoots og adProvider. Analyse av direkte budgivere krever også directBidder.

Avanserte rapporter

Opprett e-postrapporter som kjøres straks eller etter en tidsplan

Avanserte rapporter kan kjøres med én gang eller gjentas etter en tidsplan. De sendes på e-post i stedet for å returneres i svaret.

Lagre avansert 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	Vis lagrede avanserte rapporter for den autentiserte kontoen.
POST	/api/v2/reports/save-advanced-report	Opprett eller oppdater en avansert rapport. Krever reportType, toAddress, immediateRun og minst ett av målene adRoots eller domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Slett en lagret avansert rapport etter id.

Rapporttyper

adUnit, dimensions, customData

Dimensjoner

country, device, os

Frekvens

daily, weekly, biweekly, monthly

Annonsebeholdning

Opprett og slett godkjente annonseenheter

Skriving til annonsebeholdningen krever en godkjent Sulvo-konto og en API-nøkkel opprettet av kontoeieren med omfanget inventory:write.

Opprett annonseenhet

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	Opprett én annonseenhet med innstillingene domain, type, valgfri size, placement, custom name og focusedAd.
PUT	/api/v2/inventory/interstitial-units	Opprett interstitial-enheter for desktop og/eller mobil for et domene.
PUT	/api/v2/inventory/auto-sticky-units	Opprett sticky display-enheter og/eller sticky mobilenheter for et domene.
DELETE	/api/v2/inventory/unit/{adId}	Slett en annonseenhet som eies av den autentiserte kontoen.

Støttede typer annonseenheter

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Feil

Feilhåndtering

Audit-svar som ikke har 2xx-status, og feil fra Sulvos konto-API, returnerer JSON-innhold laget for agent- og CLI-klienter.

401

API-nøkkelen mangler, er ugyldig eller har utløpt for kall til konto-API-et. Det offentlige audit-endepunktet krever ingen nøkkel.

403

Nøkkelen ble autentisert, men mangler nødvendig omfang, kontoen er ikke godkjent eller ressursen tilhører en annen konto.

503 / 504

Den offentlige audit-tjenesten er overbelastet, eller audit-kallet fikk tidsavbrudd. Prøv igjen senere, og følg Retry-After hvis den er oppgitt.

Audit-feilstruktur

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

Foretrekker du en ferdigpakket klient?

Sulvos npm-pakke og MCP-oppsett kaller disse endepunktene for deg og gir kompatible AI-klienter tilgang til de samme arbeidsflytene for audit, rapportering og annonsebeholdning.

Se oppsettet