Publisher Revenue Audit API Docs

Basics

Base URLs

The public audit endpoint is intentionally unauthenticated. Sulvo account reports and inventory calls use a dashboard-generated API key.

Public audit API

POST

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

Sulvo account API

Bearer API key

https://surge.sulvo.com/api

Hosted MCP endpoint

MCP

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

Public Endpoint

Run a revenue audit

Use this endpoint for a directional public-evidence screen of a publisher domain. The response is not proof of revenue loss or guaranteed lift; validate findings against publisher-side reporting.

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	Notes
input.domain	Required publisher domain or public host. Bare domains are normalized to HTTPS. Private targets, raw IPs, internal hosts, and non-standard ports are rejected.
input.vertical	Optional. Accepts news, sports, entertainment, technology, education, gaming, or other.
input.metrics	Optional publisher-supplied dashboard context such as fill rate, viewability, average CPM, revenue per session, monthly pageviews, or monthly sessions.
input.options	Optional output and collection controls, including format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel, and partnerId.

Authentication

Use a Sulvo API key for account APIs

Generate an API key in the Sulvo dashboard under Account Settings. Send it as a Bearer token on Sulvo account API requests.

Authorization header

Authorization: Bearer $SULVO_API_KEY

reports:read

Required for report exports and saved-report listing.

reports:write

Required to create, update, run, or delete advanced reports.

inventory:write

Required for ad-unit creation and deletion. The account must be approved and own the inventory.

Reports

Read report endpoints

Read reports use GET requests under the Sulvo account API base. Date-only values are interpreted as full UTC-day bounds.

Report request

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	Daily performance summary. Supports date, domain, ad root, and provider filters.
GET	/api/v1/reports/by-date-and-ad-unit	Daily performance grouped by ad unit.
GET	/api/v1/reports/by-domain-and-ad-unit	Domain and ad-unit performance breakdown.
GET	/api/v1/reports/bot-filtering	Bot filtering report for account traffic quality review.
GET	/api/v1/reports/bot-scores	Bot score reporting by date and related dimensions.
GET	/api/v1/reports/invalid-activity	Invalid activity reporting. No standard date/domain query is required.
GET	/api/v1/reports/direct-bidder-analysis	Direct bidder report. Requires directBidder and can include start/end.
GET	/api/v1/inventory/ad-units-by-domain	Ad-unit inventory grouped by domain.

Common query parameters: start, end, repeatable domains, repeatable adRoots, and adProvider. Direct bidder analysis also requires directBidder.

Advanced Reports

Create scheduled or immediate email reports

Advanced reports can run immediately or recur on a schedule. They are delivered by email rather than returned inline.

Save advanced report

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	List saved advanced reports for the authenticated account.
POST	/api/v2/reports/save-advanced-report	Create or update an advanced report. Requires reportType, toAddress, immediateRun, and at least one adRoots or domains target.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Delete a saved advanced report by id.

Report types

adUnit, dimensions, customData

Dimensions

country, device, os

Frequency

daily, weekly, biweekly, monthly

Inventory

Create and delete approved ad units

Inventory writes require an approved Sulvo account and an owner-minted API key with inventory:write scope.

Create 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	Create a single ad unit with domain, type, optional size, placement, custom name, and focusedAd settings.
PUT	/api/v2/inventory/interstitial-units	Create desktop and/or mobile interstitial units for a domain.
PUT	/api/v2/inventory/auto-sticky-units	Create sticky display and/or sticky mobile units for a domain.
DELETE	/api/v2/inventory/unit/{adId}	Delete an ad unit owned by the authenticated account.

Supported ad unit types

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Errors

Error handling

Non-2xx audit responses and Sulvo account API failures return JSON bodies designed for agent and CLI clients.

401

The API key is missing, invalid, or expired for account API calls. The public audit endpoint does not require a key.

403

The key authenticated but lacks the required scope, the account is not approved, or the resource belongs to a different account.

503 / 504

The public audit service is saturated or the audit timed out. Retry later and respect Retry-After when present.

Audit error envelope

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

MCP and CLI

Prefer a packaged client?

The npm package and MCP setup call these endpoints for you and expose the same audit, report, and inventory workflows to compatible AI clients.

View setup