Ang Publisher Revenue Audit API

Magpatakbo ng mga pampublikong pagsusuri sa kita ng publisher, kunin ang mga ulat ng Sulvo, at pamahalaan ang naaprubahang inventory ng publisher sa parehong API na ginagamit ng CLI at MCP server.

Naka-host na base URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsSetup ng CLI at MCP

Mga batayan

Mga base URL

Sadyang walang authentication ang pampublikong audit endpoint. Gumagamit ng API key na ginawa sa dashboard ang mga ulat at tawag sa inventory ng Sulvo account.

Pampublikong API ng audit

POST

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

API ng Sulvo account

API key na Bearer

https://surge.sulvo.com/api

Naka-host na MCP endpoint

MCP

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

Pampublikong endpoint

Magpatakbo ng audit ng kita

Gamitin ang endpoint na ito para sa paunang pagsusuri ng pampublikong ebidensya tungkol sa domain ng publisher. Hindi patunay ng pagkawala ng kita o garantisadong pagtaas ang tugon; kumpirmahin ang mga natuklasan gamit ang reporting sa panig ng 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
      }
    }
  }'

Field	Mga tala
input.domain	Kinakailangan ang domain ng publisher o pampublikong host. Awtomatikong ginagawang HTTPS ang mga domain na walang scheme. Tinatanggihan ang mga pribadong target, raw IP, internal host, at hindi karaniwang port.
input.vertical	Opsyonal. Tumatanggap ng news, sports, entertainment, technology, education, gaming, o other.
input.metrics	Opsyonal na konteksto mula sa dashboard na ibinigay ng publisher, gaya ng fill rate, viewability, average CPM, revenue per session, buwanang pageview, o buwanang session.
input.options	Opsyonal na mga kontrol sa output at pangongolekta, kabilang ang format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel, at partnerId.

Pagpapatunay

Gumamit ng Sulvo API key para sa mga account API

Gumawa ng API key sa Sulvo dashboard sa ilalim ng Account Settings. Ipadala ito bilang Bearer token sa mga kahilingan sa Sulvo account API.

Header na Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Kinakailangan para mag-export ng mga ulat at maglista ng mga naka-save na ulat.

reports:write

Kinakailangan para gumawa, mag-update, magpatakbo, o magtanggal ng mga advanced na ulat.

inventory:write

Kinakailangan para gumawa at magtanggal ng ad unit. Dapat naaprubahan ang account at pag-aari nito ang inventory.

Mga ulat

Mga endpoint para magbasa ng ulat

Ginagamit ang mga GET request sa base URL ng Sulvo account API para magbasa ng mga ulat. Itinuturing na saklaw ng buong araw sa UTC ang mga value na petsa lang ang laman.

Kahilingan sa ulat

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	Buod ng arawang performance. May mga filter para sa date, domain, ad root, at provider.
GET	/api/v1/reports/by-date-and-ad-unit	Arawang performance na pinangkat ayon sa ad unit.
GET	/api/v1/reports/by-domain-and-ad-unit	Pagkakahati ng performance ayon sa domain at ad unit.
GET	/api/v1/reports/bot-filtering	Ulat sa pag-filter ng bot para suriin ang kalidad ng traffic ng account.
GET	/api/v1/reports/bot-scores	Reporting ng mga score ng bot ayon sa petsa at mga kaugnay na dimensyon.
GET	/api/v1/reports/invalid-activity	Reporting ng invalid na aktibidad. Hindi kailangan ang karaniwang query na petsa/domain.
GET	/api/v1/reports/direct-bidder-analysis	Ulat ng direct bidder. Kailangan ang directBidder at maaari nitong isama ang start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventory ng ad unit na pinangkat ayon sa domain.

Mga karaniwang query parameter: start, end, nauulit na domains, nauulit na adRoots, at adProvider. Kailangan din ang directBidder para sa pagsusuri ng direct bidder.

Mga advanced na ulat

Gumawa ng mga naka-iskedyul o agarang ulat sa email

Maaaring patakbuhin agad o ulitin ayon sa iskedyul ang mga advanced na ulat. Ipinapadala ang mga ito sa email sa halip na ibalik sa mismong tugon.

I-save ang advanced na ulat

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	Ilista ang mga naka-save na advanced na ulat para sa account na napatunayan ang pagkakakilanlan.
POST	/api/v2/reports/save-advanced-report	Gumawa o mag-update ng advanced na ulat. Kailangan ang reportType, toAddress, immediateRun, at kahit isang target na adRoots o domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Magtanggal ng naka-save na advanced na ulat ayon sa id.

Mga uri ng ulat

adUnit, dimensions, customData

Mga dimensyon

country, device, os

Dalas

daily, weekly, biweekly, monthly

Inventory

Gumawa at magtanggal ng mga naaprubahang ad unit

Kailangan ng mga pagsulat sa inventory ang naaprubahang Sulvo account at API key na ginawa ng may-ari na may scope na inventory:write.

Gumawa ng ad unit

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	Gumawa ng isang ad unit gamit ang domain, type, opsyonal na size, placement, custom name, at mga setting ng focusedAd.
PUT	/api/v2/inventory/interstitial-units	Gumawa ng mga interstitial unit para sa desktop, mobile, o pareho para sa isang domain.
PUT	/api/v2/inventory/auto-sticky-units	Gumawa ng sticky display unit, sticky mobile unit, o pareho para sa isang domain.
DELETE	/api/v2/inventory/unit/{adId}	Magtanggal ng ad unit na pag-aari ng account na napatunayan ang pagkakakilanlan.

Mga sinusuportahang uri ng ad unit

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Mga error

Paghawak sa mga error

Nagbabalik ng mga JSON body para sa mga agent at CLI client ang mga tugon sa audit na hindi 2xx at mga pagkabigo ng Sulvo account API.

401

Wala, hindi wasto, o paso na ang API key sa mga tawag sa account API. Hindi kailangan ng key ang pampublikong audit endpoint.

403

Napatunayan ang pagkakakilanlan gamit ang key, pero wala itong kinakailangang scope, hindi naaprubahan ang account, o pag-aari ng ibang account ang resource.

503 / 504

Puno na ang pampublikong audit service o nag-time out ang audit. Subukan muli mamaya at sundin ang Retry-After kapag naroon ito.

Estruktura ng error sa audit

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

Mas gusto mo ba ng naka-package na client?

Tumatawag para sa iyo sa mga endpoint na ito ang npm package at MCP setup. Nagbibigay-daan din ang mga ito para magamit ng mga katugmang AI client ang parehong workflow para sa audit, ulat, at inventory.

Tingnan ang setup