Publisher Revenue Audit API 레퍼런스

CLI와 MCP 서버가 사용하는 것과 같은 API를 통해 공개 퍼블리셔 수익 점검을 실행하고, Sulvo 리포트를 가져오며, 승인된 퍼블리셔 인벤토리를 관리하세요.

호스팅 기본 URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI 및 MCP 설정

기본 사항

기본 URL

공개 감사 엔드포인트에는 의도적으로 인증이 필요하지 않습니다. Sulvo 계정 리포트 및 인벤토리 호출에는 대시보드에서 생성한 API 키를 사용합니다.

공개 감사 API

POST

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

Sulvo 계정 API

Bearer API 키

https://surge.sulvo.com/api

호스팅 MCP 엔드포인트

MCP

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

공개 엔드포인트

수익 감사 실행

이 엔드포인트를 사용해 퍼블리셔 도메인의 공개 근거를 바탕으로 개괄적인 점검을 실행하세요. 응답은 수익 손실의 증거나 보장된 상승 효과가 아닙니다. 진단 결과를 퍼블리셔 측 리포팅과 대조해 확인하세요.

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

필드	참고 사항
input.domain	필수 항목입니다. 퍼블리셔 도메인 또는 공개 호스트를 입력하세요. 프로토콜이 없는 도메인은 HTTPS로 정규화됩니다. 비공개 대상, IP 주소 자체, 내부 호스트, 비표준 포트는 거부됩니다.
input.vertical	선택 항목입니다. news, sports, entertainment, technology, education, gaming 또는 other 값을 받습니다.
input.metrics	선택 항목입니다. 필레이트, 뷰어빌리티, 평균 CPM, 세션당 수익, 월간 페이지뷰 또는 월간 세션 등의 퍼블리셔 제공 대시보드 맥락을 입력할 수 있습니다.
input.options	선택 항목인 출력 및 수집 제어값입니다. format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel, partnerId 등이 포함됩니다.

인증

계정 API에 Sulvo API 키 사용

Sulvo 대시보드의 계정 설정에서 API 키를 생성하세요. Sulvo 계정 API 요청에 Bearer 토큰으로 전송하세요.

Authorization 헤더

Authorization: Bearer $SULVO_API_KEY

reports:read

리포트 내보내기와 저장된 리포트 목록 조회에 필요합니다.

reports:write

고급 리포트 생성, 업데이트, 실행 또는 삭제에 필요합니다.

inventory:write

광고 단위 생성 및 삭제에 필요합니다. 계정은 승인을 받아야 하며 해당 인벤토리를 소유해야 합니다.

리포트

리포트 엔드포인트 조회

리포트 조회에는 Sulvo 계정 API 기본 경로의 GET 요청을 사용합니다. 날짜만 입력하면 하루 전체를 UTC 기준으로 해석합니다.

리포트 요청

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	일별 실적 요약입니다. date, domain, ad root, provider 필터를 지원합니다.
GET	/api/v1/reports/by-date-and-ad-unit	광고 단위별 일일 실적입니다.
GET	/api/v1/reports/by-domain-and-ad-unit	도메인 및 광고 단위별 실적 분석입니다.
GET	/api/v1/reports/bot-filtering	계정 트래픽 품질 검토를 위한 봇 필터링 리포트입니다.
GET	/api/v1/reports/bot-scores	날짜 및 관련 차원별 봇 점수 리포팅입니다.
GET	/api/v1/reports/invalid-activity	유효하지 않은 활동 리포팅입니다. 표준 date/domain 쿼리는 필요하지 않습니다.
GET	/api/v1/reports/direct-bidder-analysis	직접 입찰자 리포트입니다. directBidder가 필요하며 start/end를 포함할 수 있습니다.
GET	/api/v1/inventory/ad-units-by-domain	도메인별로 그룹화한 광고 단위 인벤토리입니다.

공통 쿼리 매개변수: start, end, 반복 입력 가능한 domains, 반복 입력 가능한 adRoots, adProvider. 직접 입찰자 분석에는 directBidder도 필요합니다.

고급 리포트

예약 또는 즉시 이메일 리포트 생성

고급 리포트는 즉시 실행하거나 일정에 따라 반복 실행할 수 있습니다. 결과는 인라인으로 반환되지 않고 이메일로 전달됩니다.

고급 리포트 저장

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	인증된 계정에 저장된 고급 리포트 목록을 표시합니다.
POST	/api/v2/reports/save-advanced-report	고급 리포트를 생성하거나 업데이트합니다. reportType, toAddress, immediateRun 및 adRoots 또는 domains 대상 중 하나 이상이 필요합니다.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	id로 저장된 고급 리포트를 삭제합니다.

리포트 유형

adUnit, dimensions, customData

차원

country, device, os

주기

daily, weekly, biweekly, monthly

인벤토리

승인된 광고 단위 생성 및 삭제

인벤토리 쓰기 작업을 하려면 승인된 Sulvo 계정과 inventory:write scope가 있는 소유자 발급 API 키가 필요합니다.

광고 단위 생성

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	domain, type, 선택적 size, placement, custom name, focusedAd 설정을 사용해 광고 단위 하나를 생성합니다.
PUT	/api/v2/inventory/interstitial-units	도메인에 데스크톱 및/또는 모바일 전면 광고 단위를 생성합니다.
PUT	/api/v2/inventory/auto-sticky-units	도메인에 스티키 디스플레이 및/또는 스티키 모바일 단위를 생성합니다.
DELETE	/api/v2/inventory/unit/{adId}	인증된 계정이 소유한 광고 단위를 삭제합니다.

지원되는 광고 단위 유형

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

오류

오류 처리

2xx가 아닌 감사 응답과 Sulvo 계정 API 오류는 에이전트 및 CLI 클라이언트용으로 설계된 JSON 본문을 반환합니다.

401

계정 API 호출에 API 키가 없거나 유효하지 않거나 만료되었습니다. 공개 감사 엔드포인트에는 키가 필요하지 않습니다.

403

키 인증은 완료되었지만 필수 scope가 없거나, 계정이 승인되지 않았거나, 리소스가 다른 계정에 속합니다.

503 / 504

공개 감사 서비스가 과부하 상태이거나 감사 요청 시간이 초과되었습니다. 나중에 다시 시도하고 Retry-After가 있으면 이를 준수하세요.

감사 오류 응답 형식

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

패키지 클라이언트를 선호하시나요?

npm 패키지와 MCP 설정은 이러한 엔드포인트를 대신 호출하고, 호환되는 AI 클라이언트에 동일한 감사, 리포트, 인벤토리 워크플로를 제공합니다.

설정 보기