Indtægtsaudit for udgivere via API

Kør offentlige, vejledende vurderinger af udgiverindtægter, hent Sulvo-rapporter, og administrer godkendt inventory for udgivere via det samme API, som CLI’en og MCP-serveren bruger.

Hostet basis-URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsOpsætning af CLI og MCP

Grundlæggende

Basis-URL’er

Det offentlige audit-endpoint er bevidst uden autentificering. Sulvo-kontorapporter og inventory-kald bruger en API-nøgle, der er oprettet i dashboardet.

Offentligt API til indtægtsaudit

POST

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

Sulvos konto-API

Bearer API-nøgle

https://surge.sulvo.com/api

Hostet MCP-endpoint

MCP

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

Offentligt endpoint

Kør en indtægtsaudit

Brug dette endpoint til en vejledende vurdering af et udgiverdomæne baseret på offentligt tilgængelige data. Svaret er ikke bevis på tabte indtægter eller en garanteret stigning. Valider fundene med rapportering på udgiversiden.

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	Bemærkninger
input.domain	Påkrævet udgiverdomæne eller offentligt værtsnavn. Domæner uden protokol normaliseres til HTTPS. Private mål, rå IP-adresser, interne værtsnavne og porte uden for standarden afvises.
input.vertical	Valgfrit. Accepterer news, sports, entertainment, technology, education, gaming eller other.
input.metrics	Valgfri kontekst fra udgiverens dashboard, f.eks. fill rate, viewability, gennemsnitlig CPM, indtægter pr. session, månedlige sidevisninger eller månedlige sessioner.
input.options	Valgfrie indstillinger for output og dataindsamling, herunder format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel og partnerId.

Autentificering

Brug en Sulvo API-nøgle til konto-API’er

Opret en API-nøgle i Sulvo-dashboardet under kontoindstillingerne. Send den som Bearer-token i anmodninger til Sulvos konto-API.

Authorization-header

Authorization: Bearer $SULVO_API_KEY

reports:read

Påkrævet for eksport af rapporter og visning af listen over gemte rapporter.

reports:write

Påkrævet for at oprette, opdatere, køre eller slette avancerede rapporter.

inventory:write

Påkrævet for at oprette og slette annonceenheder. Kontoen skal være godkendt og eje inventory.

Rapporter

Læs rapportendpoints

Hent rapporter med GET-anmodninger via basis-URL’en for Sulvos konto-API. Datoer uden klokkeslæt fortolkes som hele dage i UTC.

Rapportanmodning

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	Dagligt overblik over annonceresultater. Understøtter filtre for date, domain, ad root og provider.
GET	/api/v1/reports/by-date-and-ad-unit	Daglige resultater grupperet efter annonceenhed.
GET	/api/v1/reports/by-domain-and-ad-unit	Opdeling af resultater efter domæne og annonceenhed.
GET	/api/v1/reports/bot-filtering	Rapport om botfiltrering til gennemgang af trafikkvaliteten på kontoen.
GET	/api/v1/reports/bot-scores	Rapportering af bot-scorer efter dato og relaterede dimensioner.
GET	/api/v1/reports/invalid-activity	Rapportering af ugyldig aktivitet. Der kræves ingen standardforespørgsel med dato eller domæne.
GET	/api/v1/reports/direct-bidder-analysis	Rapport om direkte budgivere. Kræver directBidder og kan indeholde start/end.
GET	/api/v1/inventory/ad-units-by-domain	Annonceenheder i inventory grupperet efter domæne.

Almindelige forespørgselsparametre: start, end, gentagelig domains, gentagelig adRoots og adProvider. Analyse af direkte budgivere kræver også directBidder.

Avancerede rapporter

Opret planlagte eller øjeblikkelige e-mailrapporter

Avancerede rapporter kan køres med det samme eller gentages efter en plan. De sendes via e-mail i stedet for at blive returneret direkte i svaret.

Gem avanceret 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 gemte avancerede rapporter for den autentificerede konto.
POST	/api/v2/reports/save-advanced-report	Opret eller opdater en avanceret rapport. Kræver reportType, toAddress, immediateRun og mindst ét mål under adRoots eller domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Slet en gemt avanceret rapport med id.

Rapporttyper

adUnit, dimensions, customData

Dimensioner

country, device, os

Frekvens

daily, weekly, biweekly, monthly

Inventory

Opret og slet godkendte annonceenheder

Skrivning til inventory kræver en godkendt Sulvo-konto og en API-nøgle oprettet af kontoejeren med scope inventory:write.

Opret annonceenhed

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	Opret en enkelt annonceenhed med domain, type, valgfri size, placement, custom name og indstillinger for focusedAd.
PUT	/api/v2/inventory/interstitial-units	Opret desktop- og/eller mobilannonceenheder i formatet Interstitial for et domæne.
PUT	/api/v2/inventory/auto-sticky-units	Opret Sticky Display- og/eller Sticky Mobile-annonceenheder for et domæne.
DELETE	/api/v2/inventory/unit/{adId}	Slet en annonceenhed, der ejes af den autentificerede konto.

Understøttede typer af annonceenheder

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Fejl

Fejlhåndtering

Audit-svar med statuskoder uden for 2xx og fejl fra Sulvos konto-API returnerer JSON-data, der er beregnet til agenter og CLI-klienter.

401

API-nøglen mangler, er ugyldig eller er udløbet ved kald til konto-API’et. Det offentlige audit-endpoint kræver ingen nøgle.

403

API-nøglen er autentificeret, men mangler det krævede scope; kontoen er ikke godkendt, eller ressourcen tilhører en anden konto.

503 / 504

Den offentlige audit-tjeneste er overbelastet, eller auditen fik timeout. Prøv igen senere, og følg Retry-After, hvis headeren er til stede.

JSON-struktur for auditfejl

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

Foretrækker du en klient, der er klar til brug?

Med npm-pakken og MCP-opsætningen bliver disse endpoints kaldt for dig, og de samme arbejdsgange for audit, rapporter og inventory stilles til rådighed for kompatible AI-klienter.

Se opsætningen