AdSovereign API Documentation

# Create a publisher
curl -X POST "https://api.adsovereign.com/v1/publishers" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example Publisher", "email": "publisher@example.com" }'

# 201 Created
{
  "id": 1042,
  "name": "Example Publisher",
  "email": "publisher@example.com",
  "uid": "pub_8f2a...",
  "disabled": false
}

# Note: PublisherModel accepts "name" and "email" on create.

# Create a site under a publisher (SiteCreateModel)
curl -X POST "https://api.adsovereign.com/v1/publishers/1042/sites" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example News",
    "url": "https://news.example.com",
    "categories": [1]
  }'

# 201 Created
# categories is an array of integer category IDs (see GET /categories).

# Create a mobile app under a publisher
curl -X POST "https://api.adsovereign.com/v1/publishers/1042/apps" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Game",
    "appName": "Example Game",
    "bundle": "com.example.game",
    "appDomain": "example.com",
    "appVer": "1.0.0",
    "storeUrl": "https://play.google.com/store/apps/details?id=com.example.game",
    "categories": [1]
  }'

# 201 Created
# categories is an array of integer category IDs (see GET /categories).

# Create a placement for site 51
curl -X POST "https://api.adsovereign.com/v1/sites/51/placements" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homepage MPU",
    "width": 300, "height": 250,
    "cpm": 1.50, "currency": "USD",
    "markup": 1,
    "type": 1,
    "htmlType": 1,
    "devices": [1, 2],
    "passback": "",
    "settingsDsps": []
  }'

# 201 Created
# type (BannerType) and htmlType use enum values 1-4; currency is one of
# RUB, EUR, USD, GBP; devices is an array of integer device IDs.

# Create an RTB source under a publisher
curl -X POST "https://api.adsovereign.com/v1/publishers/1042/rtb" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example RTB", "markup": 1 }'

# 201 Created

# Create a Header Bidding source under a publisher
curl -X POST "https://api.adsovereign.com/v1/publishers/1042/hb" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example HB" }'

# 201 Created

# Create a Prebid source under a publisher
curl -X POST "https://api.adsovereign.com/v1/publishers/1042/prebid" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example Prebid" }'

# 201 Created

# Create a DSP connection
curl -X POST "https://api.adsovereign.com/v1/dsps" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example DSP",
    "url": "https://bid.exampledsp.com/rtb",
    "currency": "USD",
    "dmpId": "dmp-7",
    "qpsLimit": 5000,
    "gzipSupported": true,
    "trafficTypes": [1, 2],
    "rtb": [11], "hb": [], "prebid": [],
    "sitePlacements": [301, 302],
    "blockedAdvertisers": ["competitor.com"]
  }'

# 201 Created
# rtb, hb, prebid and *Placements are arrays of integer source/placement IDs;
# dmpId is a string; currency is one of RUB, EUR, USD, GBP.

# Create a private deal for DSP 88
curl -X POST "https://api.adsovereign.com/v1/dsps/88/deals" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Premium PMP",
    "cpm": 6.50, "currency": "USD",
    "startDate": "2026-01-01T00:00:00+00:00",
    "endDate": "2026-03-31T23:59:59+00:00",
    "domains": ["news.example.com"],
    "sitePlacements": [301, 302],
    "appPlacements": []
  }'

# 201 Created -> returns deal "uid" used as the deal ID in bid requests
# startDate/endDate are RFC3339 date-times; currency is one of RUB, EUR, USD, GBP.

# Query a report (see Reporting section for the full body)
curl -X POST "https://api.adsovereign.com/v1/report" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-01-01", "to": "2026-01-31",
        "metrics": ["requests","imps","revenue"], "groupBy": ["date"] }'

# Fetch the device reference list
curl -X GET "https://api.adsovereign.com/v1/devices" \
  -H "token: YOUR_API_KEY"

# 200 OK
{ "data": [ { "id": 1, "name": "Mobile" }, { "id": 2, "name": "Desktop" },
            { "id": 3, "name": "Connected TV" } ] }