Theadx DSP API

Api base endpoint is https://api.theadx.com

All requests must be json format.

Using the DSP from an MCP client (Claude, ChatGPT, Gemini CLI, Cursor…) instead? See the TheAdX DSP MCP server guide. Note that API keys from the panel are for this REST API only; the MCP server logs in with e-mail + password.

For all API calls other than the “login” operation, you must include a valid access token obtained from the “login” operation as “Authorization Bearer” in the headers of all API requests. “Authorization”: “Bearer exampleToken”

General response format

If the "code" value is 1 (msg:"OK"), the response is error-free. Otherwise, an error is assumed to have occurred. The error details are shown in the msg field. If the operation was successful, the data field will contain the response to the request. The response will vary depending on the API that is being requested. The responses you will receive in the data field are shown below.

{
  "code": 1,
  "msg": "OK",
  "data": {
    "accessToken": "exampleToken",
    "accessExpire": 1638297600,
    "refreshAfter": 1638297600
  }
}

API Endpoints Overview

Based on go-zero v1.6.1 routing configuration from /api/internal/handler/routes.go:

Authentication Endpoints

Campaign Management Endpoints (All require authentication)

Site & Domain Management Endpoints (All require authentication)


1. Get Access Token

Açıklama: Kullanıcı giriş bilgileri veya API anahtarları ile sistem erişimi için gerekli access token'ı alır. Bu token diğer tüm API çağrılarında Authorization header'ında kullanılır.

There are two ways to authenticate:

Method Credentials Where to get them Token bound to IP
User login email + password Your DSP panel user No
API key apikey + secretkey DSP panel → Settings → API Access Yes (the IP the token was issued to)

API keys

1. route definition

2. request

email && password or secretkey && apikey pair must be provided

{
	"email": "example@example.com",
	"password": "password123"
}

or

To use these API keys, you must define specific IP addresses. You cannot use them from addresses other than those that are defined. Access tokens created with this method are only valid for the IP address they were created on.

{
	"secretkey": "secret123",
	"apikey": "apikey123"
}

3. response

The access token you get from here should be added to the headers of all API requests as "'Authorization': 'Bearer exampleToken'".

{
	"accessToken": "exampleToken", /* store and use before access expire*/
	"accessExpire": 1638297600, /* token expire date in unixtime*/
	"refreshAfter": 1638297600 /* refresh token after this date , unixtime */
}

A token is valid for 24 hours (accessExpire). Call /user/refreshToken after refreshAfter (half of the lifetime) to get a new one without logging in again. Store the token; do not call /user/login before every request.

4. errors

Errors come back with code: -1 and the reason in msg:

msg Meaning
invalid username or password Wrong email/password, or neither credential pair was sent
invalid apikey or secretkey Pair not found, or the key has been disabled in the panel
you do not have permission to access the API from this IP. <ip> Your IP is not in the key's allowed list (or the key has no IPs). Add <ip> in the panel
api key is disabled (on any authenticated call) The key behind your token was disabled in the panel; generate a new key and log in again
member is suspended / member email is not confirmed / member is not dsp user Account state; contact TheAdX

Example with an API key:

curl -X POST https://api.theadx.com/user/login \
  -H "Content-Type: application/json" \
  -d '{"apikey":"<apikey>","secretkey":"<secretkey>"}'

2. Refresh Token

Açıklama: Mevcut access token'ın süresini yenilemek için kullanılır. Token süresi dolmadan önce yenileyerek kesintisiz API erişimi sağlar.

The new token keeps the properties of the old one: a token issued to an API key stays bound to the same IP (invalid ip address <ip> if called from elsewhere), and the account's state is re-checked. If the key was disabled meanwhile, refresh (like every other call) is refused with api key is disabled.

1. route definition

2. request

send empty string or json as body

{}

3. response

{
	"accessToken": "new-exampleToken", /* store and use before access expire*/
	"accessExpire": 1738297600, /* token expire date in unixtime*/
	"refreshAfter": 1738297600 /* refresh token after this date , unixtime */
}

3. List Campaigns

Açıklama: Kullanıcıya ait kampanyaların listesini getirir. Kampanya durumuna göre filtreleme ve sayfalama desteği sağlar. Aktif, duraklayan veya tüm kampanyaları listeleyebilir.

1. route definition

List user campaigns

2. request

{
	"status": 1, /*optional,range=[0:2],default=1  0:all campaigns, 1:enabled campaigns, 2:paused/ended campaigns*/ 
	"pagesize": 50, /*optional,default=100 records size in each call*/
	"pageindex": 0 /*optional,default=0*/

}

3. response

{
	"campaigns": [
		{
			"campaignid": 12345, /*unique campaignid*/
			"campaignname": "my campaign name",
			"createdate": 1669279563,/*campaign create date in unixtime format*/
			"startdate": 1609279563,/*campaign start date*/
			"expiredate": 1692434000,/*campaign expiredate in unixtime format */
			"status": 1,/*campaign status 1:'active',2:'pause',3:'deleted',4:'waiting_confirmation',5:'denied' */
			"rtbprice": 1.5, /* max bid price in float must be gretaer than 0*/
			"dailybudget": 100.11,/* total daily budget*/
			"totaltargetedimpressions":100000,/*campaign total targeted impressions*/
			"costmodel": 2, /*1:Daily budget immediate consumption, 2::Daily budget equal divide to day */
			"totalbudget": 1000.00, /*total campaign budget*/
			"totalcost": 11.398, /*total campaign cost*/
			"totalimpshown": 10000,/*Total impressions over campaign*/
			"ecpm":1.1398, /*effective cost per mille*/
			"statustext": "active"
      	}
	],
	"total": 2,
	"page": 1,
	"pageSize": 50
}

4. Campaign Budget Details

Açıklama: Belirli bir kampanyanın bütçe detaylarını getirir. RTB fiyatı, günlük/toplam bütçe, hedeflenen gösterim sayısı ve maliyet modeli gibi finansal bilgileri içerir.

1. route definition

2. request

	{
		"campaignid":12345
	}

3. response

{
	"campaignbudgetdetails":{
		"campaignid": 12345,/*unique campaignid*/
		"rtbprice": 1.5, /* max bid price in float must be gretaer than 0*/
		"totalbudget": 1000.00, /*total campaign budget*/
		"dailybudget": 100.11,/* total daily budget*/
		"totaltargetedimpressions":100000,/*campaign total targeted impressions*/
		"costmodel": 2, /*1:Daily budget immediate consumption, 2::Daily budget equal divide to day */
		"budgettarget": 1,/*1:cpm targeted , 2:cpc targeted*/
		"btmin": -1, /*cpc targeted campaign minumum cpc value,must be lower than rtbprice  */
		"btmax": -1, /*cpc targeted campaign maximum cpc value must be lower than rtbprice  */
		"learnamount": -1, /*cpc targeted campaign cpc learn amount default 1000 */
		"pricetype": 1, /* 1:first price 2:smart price */
		"transferRemaingBudgetToNextDay": false /* transfer remaing daily budget to next day*/
	}
}

5. Campaign Budget Update

Açıklama: Kampanya bütçe ayarlarını günceller. RTB fiyatı, günlük/toplam bütçe, hedeflenen gösterim sayısı ve diğer finansal parametreleri değiştirmek için kullanılır.

  1. route definition

2. request

{
	"campaignid": 12345,/*unique campaignid*/
	"rtbprice": 1.5, /* max bid price in float must be gretaer than 0*/
	"totalbudget": 1000.00, /*total campaign budget*/
	"dailybudget": 100.11,/* total daily budget*/
	"totaltargetedimpressions":100000,/*campaign total targeted impressions*/
	"costmodel": 2, /*1:Daily budget immediate consumption, 2::Daily budget equal divide to day */
	"budgettarget": 1,/*1:cpm targeted , 2:cpc targeted*/
	"btmin": -1, /*cpc targeted campaign minumum cpc value,must be lower than rtbprice  */
	"btmax": -1, /*cpc targeted campaign maximum cpc value must be lower than rtbprice  */
	"learnamount": -1, /*cpc targeted campaign cpc learn amount default 1000 */
	"pricetype": 1, /* 1:first price 2:smart price */
	"transferRemaingBudgetToNextDay": false /* transfer remaing daily budget to next day*/
}
  1. response

return updated values

{
	"campaignid": 12345,/*unique campaignid*/
	"rtbprice": 1.5, /* max bid price in float must be gretaer than 0*/
	"totalbudget": 1000.00, /*total campaign budget*/
	"dailybudget": 100.11,/* total daily budget*/
	"totaltargetedimpressions":100000,/*campaign total targeted impressions*/
	"costmodel": 2, /*1:Daily budget immediate consumption, 2::Daily budget equal divide to day */
	"budgettarget": 1,/*1:cpm targeted , 2:cpc targeted*/
	"btmin": -1, /*cpc targeted campaign minumum cpc value,must be lower than rtbprice  */
	"btmax": -1, /*cpc targeted campaign maximum cpc value must be lower than rtbprice  */
	"learnamount": -1, /*cpc targeted campaign cpc learn amount default 1000 */
	"pricetype": 1, /* 1:first price 2:smart price */
	"transferRemaingBudgetToNextDay": false /* transfer remaing daily budget to next day*/
}

6. Campaign Status Update

Açıklama: Kampanyanın aktif/pasif durumunu değiştirir. Kampanyayı başlatmak, durdurmak veya yeniden etkinleştirmek için kullanılır.

  1. route definition
  1. request
 {
	"campaignid":12345,
	"enabled":true
}
  1. response

returns updated response

 {
	"campaignid":12345,
	"enabled":true
}

7. Campaign Banners

Açıklama: Belirli bir kampanyaya ait banner'ların listesini getirir. Banner durumuna göre filtreleme yapılabilir ve her banner'ın performans metrikleri (gösterim, tıklama, maliyet) ile birlikte döner.

1. route definition

2. request

{
	"campaignid":12345,
	"status":0 /*optional,default=0 0:list all banners 1:active, 2:paused*/
}

3. response

adtypes:

1:"image",3:"video",14:"code",15:"html5",16:"native",17:"mastheadvideo",18:"videoretargeting",19:"popunder",20:"voice",21:"imageretargeting",22:"smartv",23:"tv"
{
	"banners": [
     	{
			"id": 123456,
			"bannername": "sample_creative.jpg",
			"price":2, /*This field is visible if a specific price is set for it. If there is no price set, the campaign's rtbprice field is used.*/
			"adtype": 1,
			"width": 250,
			"height": 250,
			"status": 1,
			"imp": 181243,
			"click": 91,
			"cost": 125.69843
      	},
	],
	"total":1,
}
 

8. Banner Price Update

Açıklama: Belirli bir banner için özel fiyat belirler. Banner bazında farklı RTB fiyatları ayarlamak için kullanılır. Eğer banner fiyatı belirlenmemişse kampanya RTB fiyatı kullanılır.

1. route definition

2. request

{
	"bannerid":123456,
	"price":5.50
}

3. response

returns updated data

{
	"bannerid":123456,
	"price":5.50
}

9. Banner Status Update

Açıklama: Banner'ın aktif/pasif durumunu değiştirir. Belirli banner'ları kampanya içinde aktif etmek veya devre dışı bırakmak için kullanılır.

1. route definition

2. request

{
	"bannerid":123456,
	"enabled":true
}

3. response

returns updated data

{
	"bannerid":123456,
	"enabled":true
}

10. Campaign Stats

Açıklama: Kampanya performans istatistiklerini getirir. Belirli tarih aralığında kampanyanın gösterim, tıklama, maliyet ve video metrikleri (ilk çeyrek, orta nokta vb.) hakkında detaylı bilgi sağlar.

  1. route definition
  1. request
{
	"campaignid": 12345,
	"datefrom": "2023-12-01", /*optional*/
	"dateto": "2023-12-31" /*optional*/
}
  1. response
 {
    "campaignstats": {
      "campaignid": 12345,
      "campaignname": "my campaign",
      "imp": 70031,
      "click": 86,
      "cost": 100.00424,
      "firstquartile": 44852, /*video creative stats*/
      "midpoint": 36409,/*video creative stats*/
      "thirdquartile": 32167,/*video creative stats*/
      "complete": 29172,/*video creative stats*/
      "skip": 7592,/*video creative stats*/
      "viewability": 79 /*  viewability average*/
    }
  }

11. Banner Stats

Açıklama: Banner bazında performans istatistiklerini getirir. Belirli tarih aralığında banner'ın gösterim, tıklama, maliyet ve video metrikleri hakkında detaylı analiz sağlar.

  1. route definition

2. request

{
	"campaignid": 12345,
	"datefrom": "2023-12-01", /*optional*/
	"dateto": "2023-12-31" /*optional*/
}
  1. response
 {
    "campaignstats": {
      "id": 12345, /*bannerid*/
      "campaignname": "my campaign",
      "imp": 70031,
      "click": 86,
      "cost": 100.00424,
      "firstquartile": 44852, /*video creative stats*/
      "midpoint": 36409,/*video creative stats*/
      "thirdquartile": 32167,/*video creative stats*/
      "complete": 29172,/*video creative stats*/
      "skip": 7592,/*video creative stats*/
      "viewability": 79 /*  viewability average*/
    }
  }

12. Banner Site Stats

Açıklama: Belirli bir banner'ın hangi sitelerde nasıl performans gösterdiğini analiz eder. Site bazında banner performansını karşılaştırmak ve optimizasyon yapmak için kullanılır.

1. route definition

  1. request
{
	"campaignid": 12345,
	"bannerid": 123456,
	"datefrom": "2023-01-01", /*optional*/
	"dateto": "2023-01-31", /*optional*/
	"pagesize": 50, /* optional,default=100 */
	"pageindex": 0  /* optional,defaul=0*/
}
  1. response
{
	"bannersitestats":[ 
			{
				"id": 123456,
				"bannername": "my banner",
				"width": 300,
				"height": 250,
				"siteid": 6789,
				"sitename": "example.com",
				"imp": 1000,
				"click": 50,
				"cost": 10.5,
				"ctr": 0.05,
				"ecpc": 0.21,
				"ecpm": 2.1,
				"request": 2000,
				"firstquartile": 500,
				"midpoint": 300,
				"thirdquartile": 200,
				"complete": 100,
				"skip": 50,
				"vcr": 0.5,
				"start": 100
			}
		]
 
}

13. Site Stats

Açıklama: Kampanya genelinde site bazlı performans istatistiklerini getirir. Hangi sitelerin daha iyi performans gösterdiğini analiz etmek ve site hedeflemesi optimize etmek için kullanılır.

1. route definition

2. request


{
	"campaignid": 12345,
	"sitename": "example.com", /* optional */
	"datefrom": "2023-01-01", /* optional */
	"dateto": "2023-01-31", /* optional */
	"pagesize": 50, /* optional,default=100 */
	"pageindex": 0 /* optional,default=0 */
}

3. response

{
	"sitestats":[
		{
		"siteid": 12345,
		"sitename": "example.com",
		"impression": 1000,
		"click": 50,
		"cost": 10.5,
		"ctr": 0.05,
		"ecpc": 0.21,
		"ecpm": 2.1,
		"request": 2000,
		"firstquartile": 500,
		"midpoint": 300,
		"thirdquartile": 200,
		"complete": 100,
		"skip": 50,
		"vcr": 0.5,
		"start": 100
		}
	]
}

14. Block Domain

Açıklama: Belirli bir domain'i banner için engeller. Bu domain'lerde banner gösterilmesini önlemek için kullanılır. Marka güvenliği ve hedefleme kontrolü sağlar.

1. route definition

2. request

{
	"bannerid": 123456,
	"domain": "example.com"
}

3. response

{
	"bannerid": 123456,
	"domain": "example.com",
	"blocked": true
}

15. Unblock Domain

Açıklama: Daha önce engellenmiş bir domain'in engelini kaldırır. Banner'ın o domain'de tekrar gösterilmesine izin verir.

1. route definition

2. request

{
	"bannerid": 123456,
	"domain": "example.com"
}

3. response

{
	"bannerid": 123456,
	"domain": "example.com",
	"blocked": false
}

16. Block URL

Açıklama: Belirli bir URL'yi banner için engeller. Spesifik sayfaların banner gösterimine kapatılması için kullanılır. Domain engellemesinden daha detaylı kontrol sağlar.

1. route definition

2. request

{
	"bannerid": 123456,
	"url": "https://example.com/page"
}

3. response

{
	"bannerid": 123456,
	"url": "https://example.com/page",
	"blocked": true
}

17. Unblock URL

Açıklama: Daha önce engellenmiş bir URL'nin engelini kaldırır. Banner'ın o spesifik sayfada tekrar gösterilmesine izin verir.

1. route definition

2. request

{
	"bannerid": 123456,
	"url": "https://example.com/page"
}

3. response

{
	"bannerid": 123456,
	"url": "https://example.com/page",
	"blocked": false
}

18. Site Based Price Update

Açıklama: Belirli site ve banner kombinasyonu için özel fiyat belirler. Site performansına göre fiyat optimizasyonu yapmak için kullanılır.

1. route definition

2. request

{
	"bannerid": 123456,
	"siteid": 6789,
	"price": 2.50
}

3. response

{
	"bannerid": 123456,
	"siteid": 6789,
	"price": 2.50
}

19. Banner Statistics

Açıklama: Banner'ın detaylı performans istatistiklerini getirir. Gösterim, tıklama, maliyet oranları ve video metrikleri dahil kapsamlı analiz sağlar.

1. route definition

2. request

{
	"bannerid": 123456,
	"datefrom": "2023-01-01", /* optional */
	"dateto": "2023-01-31" /* optional */
}

3. response

{
	"bannerstatistics": {
		"bannerid": 123456,
		"bannername": "my banner",
		"imp": 1000,
		"click": 50,
		"cost": 10.5,
		"ctr": 0.05,
		"ecpc": 0.21,
		"ecpm": 2.1,
		"firstquartile": 500,
		"midpoint": 300,
		"thirdquartile": 200,
		"complete": 100,
		"skip": 50,
		"vcr": 0.5,
		"start": 100,
		"viewability": 75
	}
}

20. Banner Statics

Açıklama: Banner'ın statik bilgilerini getirir. Banner özellikleri, engellenmiş siteler/URL'ler, CTR hedefleme gibi konfigürasyon detaylarını içerir.

1. route definition

2. request

{
	"bannerid": 123456
}

3. response

{
	"bannerstatics": {
		"bannerid": 123456,
		"bannername": "my banner",
		"adtype": 1,
		"width": 300,
		"height": 250,
		"status": 1,
		"clickurl": "https://example.com/landing",
		"price": 2.0,
		"block_sites": "badsite1.com,badsite2.com",
		"unblock_sites": "goodsite1.com,goodsite2.com",
		"block_urls": "https://badsite.com/page1,https://badsite.com/page2",
		"unblock_urls": "https://goodsite.com/page1,https://goodsite.com/page2",
		"ctrtargeting": 1.2
	}
}

21. Banner Site Stats All

Açıklama: Kampanya genelinde tüm banner'ların site bazlı performansını toplu olarak getirir. Kapsamlı site-banner performans analizi için kullanılır. Engellenen siteler filtrelenir.

1. route definition

2. request

{
	"campaignid": 12345,
	"datefrom": "2023-01-01", /* optional */
	"dateto": "2023-01-31", /* optional */
	"pagesize": 50, /* optional,default=100 */
	"pageindex": 0 /* optional,default=0 */
}

3. response

{
	"bannersitestats":[
		{
			"id": 123456,
			"bannername": "",
			"width": 300,
			"height": 250,
			"siteid": 0,
			"sitename": "example.com",
			"imp": 1000,
			"click": 50,
			"cost": 10.5,
			"ctr": 0.05,
			"ecpc": 0.21,
			"ecpm": 2.1,
			"request": 2000,
			"firstquartile": 500,
			"midpoint": 300,
			"thirdquartile": 200,
			"complete": 100,
			"skip": 50,
			"vcr": 0.5,
			"start": 100
		}
	]
}

22. Banner Site Price Bulk Update

Açıklama: Birden fazla banner için site bazlı fiyat güncellemesi yapar. Toplu operasyon ile performanslı bir şekilde çok sayıda banner-site kombinasyonu için fiyat ayarlaması yapılabilir. JSON array formatında site adı, banner ID ve fiyat bilgilerini alır.

1. route definition

2. request

{
	"priceupdates": [
		{"s": "milliyet.com.tr", "b": 187286, "p": 6.65},
		{"s": "milliyet.com.tr", "b": 187287, "p": 6.65},
		{"s": "milliyet.com.tr", "b": 187288, "p": 6.65},
		{"s": "example.com", "b": 187289, "p": 8.50},
		{"s": "news.com", "b": 187290, "p": 4.25}
	]
}

Request Parameters:

3. response

{
	"updatedcount": 5,
	"results": [
		{"s": "milliyet.com.tr", "b": 187286, "p": 6.65},
		{"s": "milliyet.com.tr", "b": 187287, "p": 6.65},
		{"s": "milliyet.com.tr", "b": 187288, "p": 6.65},
		{"s": "example.com", "b": 187289, "p": 8.50},
		{"s": "news.com", "b": 187290, "p": 4.25}
	]
}

Response Fields: