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
}
}
Based on go-zero v1.6.1 routing configuration from /api/internal/handler/routes.go:
POST /user/login - Get access token (no auth required)POST /user/refreshToken - Refresh access token (auth required)POST /campaigns/list - List campaignsPOST /campaigns/budgetDetails - Get campaign budget detailsPOST /campaigns/budgetUpdate - Update campaign budgetPOST /campaigns/campaignStatusUpdate - Update campaign statusPOST /campaigns/stats - Get campaign statisticsPOST /campaigns/banners - List campaign bannersPOST /campaigns/bannerPriceUpdate - Update banner pricePOST /campaigns/bannerStatusUpdate - Update banner statusPOST /campaigns/bannerStats - Get banner statisticsPOST /campaigns/bannerstatics - Get banner static information POST /campaigns/bannerSiteStats - Get banner site statisticsPOST /campaigns/bannerSiteStatsAll - Get all banner site statisticsPOST /campaigns/bannerSitePriceUpdate - Bulk update banner site pricesPOST /campaigns/siteStats - Get site statisticsPOST /campaigns/blockDomain - Block domainPOST /campaigns/unblockDomain - Unblock domainPOST /campaigns/blockUrl - Block URLPOST /campaigns/unblockUrl - Unblock URLPOST /campaigns/priceupdate - Site-based price updateAçı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
Ayarlar → API Erişimi). Contact your TheAdX account manager if you do not see it.apikey (32 hex characters, public) and secretkey (64 hex characters, keep it secret). You can create as many keys as you need and give each a name (e.g. per integration or per server).* as the IP to allow any address (not recommended). CIDR ranges and IPv6 are not supported; add each address separately. IPs can be added and removed at any time and take effect immediately.api key is disabled. Disabled keys stay listed for reference./user/refreshToken) must come from that same IP; otherwise the API answers you cant use current auth token for this ip. Tokens obtained with email/password are not IP-bound.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"
}
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.
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>"}'
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.
send empty string or json as body
{}
{
"accessToken": "new-exampleToken", /* store and use before access expire*/
"accessExpire": 1738297600, /* token expire date in unixtime*/
"refreshAfter": 1738297600 /* refresh token after this date , unixtime */
}
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.
List user campaigns
{
"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*/
}
{
"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
}
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.
{
"campaignid":12345
}
{
"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*/
}
}
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.
{
"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*/
}
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*/
}
Açıklama: Kampanyanın aktif/pasif durumunu değiştirir. Kampanyayı başlatmak, durdurmak veya yeniden etkinleştirmek için kullanılır.
{
"campaignid":12345,
"enabled":true
}
returns updated response
{
"campaignid":12345,
"enabled":true
}
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.
{
"campaignid":12345,
"status":0 /*optional,default=0 0:list all banners 1:active, 2:paused*/
}
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,
}
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.
{
"bannerid":123456,
"price":5.50
}
returns updated data
{
"bannerid":123456,
"price":5.50
}
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.
{
"bannerid":123456,
"enabled":true
}
returns updated data
{
"bannerid":123456,
"enabled":true
}
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.
{
"campaignid": 12345,
"datefrom": "2023-12-01", /*optional*/
"dateto": "2023-12-31" /*optional*/
}
{
"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*/
}
}
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.
{
"campaignid": 12345,
"datefrom": "2023-12-01", /*optional*/
"dateto": "2023-12-31" /*optional*/
}
{
"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*/
}
}
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.
{
"campaignid": 12345,
"bannerid": 123456,
"datefrom": "2023-01-01", /*optional*/
"dateto": "2023-01-31", /*optional*/
"pagesize": 50, /* optional,default=100 */
"pageindex": 0 /* optional,defaul=0*/
}
{
"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
}
]
}
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.
{
"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 */
}
{
"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
}
]
}
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.
{
"bannerid": 123456,
"domain": "example.com"
}
{
"bannerid": 123456,
"domain": "example.com",
"blocked": true
}
Açıklama: Daha önce engellenmiş bir domain'in engelini kaldırır. Banner'ın o domain'de tekrar gösterilmesine izin verir.
{
"bannerid": 123456,
"domain": "example.com"
}
{
"bannerid": 123456,
"domain": "example.com",
"blocked": false
}
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.
{
"bannerid": 123456,
"url": "https://example.com/page"
}
{
"bannerid": 123456,
"url": "https://example.com/page",
"blocked": true
}
Açıklama: Daha önce engellenmiş bir URL'nin engelini kaldırır. Banner'ın o spesifik sayfada tekrar gösterilmesine izin verir.
{
"bannerid": 123456,
"url": "https://example.com/page"
}
{
"bannerid": 123456,
"url": "https://example.com/page",
"blocked": false
}
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.
{
"bannerid": 123456,
"siteid": 6789,
"price": 2.50
}
{
"bannerid": 123456,
"siteid": 6789,
"price": 2.50
}
Açıklama: Banner'ın detaylı performans istatistiklerini getirir. Gösterim, tıklama, maliyet oranları ve video metrikleri dahil kapsamlı analiz sağlar.
{
"bannerid": 123456,
"datefrom": "2023-01-01", /* optional */
"dateto": "2023-01-31" /* optional */
}
{
"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
}
}
Açıklama: Banner'ın statik bilgilerini getirir. Banner özellikleri, engellenmiş siteler/URL'ler, CTR hedefleme gibi konfigürasyon detaylarını içerir.
{
"bannerid": 123456
}
{
"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
}
}
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.
{
"campaignid": 12345,
"datefrom": "2023-01-01", /* optional */
"dateto": "2023-01-31", /* optional */
"pagesize": 50, /* optional,default=100 */
"pageindex": 0 /* optional,default=0 */
}
{
"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
}
]
}
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.
{
"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:
s (string): Site adı/domainb (int32): Banner IDp (float32): Yeni fiyat değeri{
"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:
updatedcount: Güncellenen kayıt sayısıresults: Güncellenen kayıtların listesi