{"openapi":"3.1.0","info":{"title":"adspends API","description":"REST access to the adspends EU Meta ad-intelligence database: ads, advertisers (brands), landing pages, tracked brands and saved boards. All spend figures are estimates in EUR derived from EU transparency reach (€30 CPM). Authenticate every request with \"Authorization: Bearer <api key>\". Calls are charged in API credits (1 per returned result for list endpoints, fixed costs for detail endpoints; errors are free). GET /usage (free) shows your balance and the cost table; the X-Credits-* response headers show the cost and remaining credits of each call. Valid marketId / categoryId / niche values: GET /markets, /categories, /niches (free).","version":"1.0.0"},"servers":[{"url":"https://app.adspends.com/api/v1"}],"externalDocs":{"url":"https://app.adspends.com/api/v1/docs"},"paths":{"/ads":{"get":{"operationId":"ads-searchAds","summary":"Search and browse ads","description":"MCP tool: `search_ads` · Credits: 1 credit per returned result (min 1, max 50) · Response size: ≈ 9 tokens + ≈ 290 per result","tags":["ads"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":200}},{"in":"query","name":"advertiserId","schema":{"type":"string"}},{"in":"query","name":"platform","schema":{"type":"string","enum":["all","INSTAGRAM","FACEBOOK","AUDIENCE_NETWORK","MESSENGER","THREADS"]}},{"in":"query","name":"creativeType","schema":{"type":"string","enum":["all","image","video","carousel"]}},{"in":"query","name":"active","schema":{"type":"boolean"}},{"in":"query","name":"dateRange","schema":{"type":"string","enum":["last_7_days","last_14_days","last_30_days","last_90_days","last_6_months","this_year","last_year","last_2_years","all"]}},{"in":"query","name":"language","schema":{"type":"string","maxLength":8}},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["reach:desc","relevance:desc","date:asc","date:desc"]}},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","category"],"additionalProperties":false},"reach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"EU transparency reach (impressions) — the basis for spend estimates."},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated spend in EUR, derived from reach at a €30 CPM. An estimate, not billing data."},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"relevanceScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Internal 0-100 performance rank."},"dateDelivered":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the ad was first seen delivering — use it to tell new launches from evergreens."},"platforms":{"type":"array","items":{"type":"string"}},"creative":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary ad copy."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destination the ad links to."},"displayUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ctaText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Call-to-action button text."}},"required":["text","imageUrl","videoUrl","linkUrl","displayUrl","ctaText"],"additionalProperties":false},{"type":"null"}]}},"required":["id","advertiser","reach","estimatedSpendEur","isActive","relevanceScore","dateDelivered","platforms","creative"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Estimated total matches for the filters (not just this page)."}},"required":["ads","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/ads/{adId}":{"get":{"operationId":"ads-getAd","summary":"Get one ad by id","description":"MCP tool: `get_ad` · Credits: 2 credits · Response size: ≈ 940 tokens","tags":["ads"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"adId","schema":{"type":"string","description":"The ad id, e.g. from search_ads results."},"required":true,"description":"The ad id, e.g. from search_ads results."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","category"],"additionalProperties":false},"reach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"EU transparency reach (impressions) — the basis for spend estimates."},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated spend in EUR, derived from reach at a €30 CPM. An estimate, not billing data."},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"relevanceScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Internal 0-100 performance rank."},"dateDelivered":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the ad was first seen delivering — use it to tell new launches from evergreens."},"platforms":{"type":"array","items":{"type":"string"}},"creative":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary ad copy."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destination the ad links to."},"displayUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ctaText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Call-to-action button text."}},"required":["text","imageUrl","videoUrl","linkUrl","displayUrl","ctaText"],"additionalProperties":false},{"type":"null"}]},"facebookAdId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Meta Ad Library id."},"advertiserTotalAds":{"anyOf":[{"type":"number"},{"type":"null"}]},"savedByUser":{"type":"boolean","description":"Whether this ad is on one of your saved boards."},"transcript":{"anyOf":[{"type":"object","properties":{"text":{"type":"string","description":"Spoken text, max 20,000 characters."},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationMs":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"segments":{"type":"array","items":{"type":"object","properties":{"startMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"endMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"text":{"type":"string"}},"required":["startMs","endMs","text"],"additionalProperties":false},"description":"Timestamped segments, max 500."},"truncated":{"type":"boolean","description":"True when text or segments were cut to the limits above."}},"required":["text","language","durationMs","segments","truncated"],"additionalProperties":false},{"type":"null"}],"description":"Timestamped spoken transcript for the selected video creative when available."}},"required":["id","advertiser","reach","estimatedSpendEur","isActive","relevanceScore","dateDelivered","platforms","creative","facebookAdId","advertiserTotalAds","savedByUser","transcript"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/advertisers":{"get":{"operationId":"advertisers-searchAdvertisers","summary":"Search advertisers by name","description":"MCP tool: `search_advertisers` · Credits: 1 credit per returned result (min 1, max 50) · Response size: ≈ 11 tokens + ≈ 86 per result","tags":["advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"marketId","schema":{"type":"string","maxLength":100}},{"in":"query","name":"categoryId","schema":{"type":"string","maxLength":100}},{"in":"query","name":"niche","schema":{"type":"string","maxLength":100}},{"in":"query","name":"country","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"in":"query","name":"pageType","schema":{"type":"string","enum":["advertorial","offerpage","quiz","vsl","pdp","listicle","comparison","shop","other"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","inactive"]}},{"in":"query","name":"minAdSpend","schema":{"type":"number","minimum":0}},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["totalAds:desc","adSpend:desc","reach:desc","newAds:desc","newest:desc"]}},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"description":"Paging offset (max 1000).","type":"integer","minimum":0,"maximum":1000}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"advertisers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"profileImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"totalAds":{"anyOf":[{"type":"number"},{"type":"null"}]},"activeAds":{"description":"Currently running ads.","anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"description":"Sum of latest EU reach across all ads.","anyOf":[{"type":"number"},{"type":"null"}]},"estimatedTotalSpendEur":{"description":"Estimated total spend in EUR (€30 CPM heuristic).","anyOf":[{"type":"number"},{"type":"null"}]},"newAds30d":{"description":"New ads in the 30 days up to the last time the brand was checked.","anyOf":[{"type":"number"},{"type":"null"}]},"market":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","profileImageUrl","totalAds"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Estimated number of matching brands (not just this page)."}},"required":["advertisers","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/advertisers/{advertiserId}":{"get":{"operationId":"advertisers-getAdvertiser","summary":"Get one advertiser by id","description":"MCP tool: `get_advertiser` · Credits: 1 credit · Response size: ≈ 130 tokens","tags":["advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"advertiserId","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebookPageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"profileImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebookPageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebookLikes":{"anyOf":[{"type":"number"},{"type":"null"}]},"instagramUsername":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagramFollowers":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalAds":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of latest EU reach across all ads."},"estimatedTotalSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total spend in EUR (€30 CPM heuristic)."},"firstSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","facebookPageId","profileImageUrl","facebookPageUrl","facebookLikes","instagramUsername","instagramFollowers","totalAds","totalReach","estimatedTotalSpendEur","firstSeenAt"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/advertisers/{advertiserId}/overview":{"get":{"operationId":"advertisers-getBrandOverview","summary":"Brand overview: details, top ads and top landing pages","description":"MCP tool: `get_brand_overview` · Credits: 5 credits · Response size: ≈ 2,400 tokens","tags":["advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"advertiserId","schema":{"type":"string"},"required":true},{"in":"query","name":"adsLimit","schema":{"default":5,"description":"Top ads by EU reach to include (0-10, default 5).","type":"integer","minimum":0,"maximum":10}},{"in":"query","name":"landingPagesLimit","schema":{"default":5,"description":"Top landing pages by EU reach to include (0-10, default 5).","type":"integer","minimum":0,"maximum":10}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebookPageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"profileImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebookPageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebookLikes":{"anyOf":[{"type":"number"},{"type":"null"}]},"instagramUsername":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagramFollowers":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalAds":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of latest EU reach across all ads."},"estimatedTotalSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total spend in EUR (€30 CPM heuristic)."},"firstSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","facebookPageId","profileImageUrl","facebookPageUrl","facebookLikes","instagramUsername","instagramFollowers","totalAds","totalReach","estimatedTotalSpendEur","firstSeenAt"],"additionalProperties":false},"topAds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","category"],"additionalProperties":false},"reach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"EU transparency reach (impressions) — the basis for spend estimates."},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated spend in EUR, derived from reach at a €30 CPM. An estimate, not billing data."},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"relevanceScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Internal 0-100 performance rank."},"dateDelivered":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the ad was first seen delivering — use it to tell new launches from evergreens."},"platforms":{"type":"array","items":{"type":"string"}},"creative":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary ad copy."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destination the ad links to."},"displayUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ctaText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Call-to-action button text."}},"required":["text","imageUrl","videoUrl","linkUrl","displayUrl","ctaText"],"additionalProperties":false},{"type":"null"}]}},"required":["id","advertiser","reach","estimatedSpendEur","isActive","relevanceScore","dateDelivered","platforms","creative"],"additionalProperties":false},"description":"The brand’s ads with the highest EU reach."},"topLandingPages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"advertiser":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"],"additionalProperties":false},"pageType":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"adCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"activeAdCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"newAdsLast30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}]},"adSpendScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"0-100: share of the brand’s estimated spend flowing to this page."},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"firstSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","domain","advertiser","pageType","language","adCount","activeAdCount","newAdsLast30d","totalReach","estimatedSpendEur","adSpendScore","screenshotUrl","firstSeenAt","lastSeenAt"],"additionalProperties":false},"description":"The brand’s landing pages with the highest EU reach."}},"required":["advertiser","topAds","topLandingPages"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/advertisers/{advertiserId}/ads":{"get":{"operationId":"advertisers-getAdvertiserAds","summary":"List ads of one advertiser","description":"MCP tool: `get_advertiser_ads` · Credits: 1 credit per returned result (min 1, max 50) · Response size: ≈ 3 tokens + ≈ 290 per result","tags":["advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"advertiserId","schema":{"type":"string"},"required":true},{"in":"query","name":"creativeType","schema":{"type":"string","enum":["all","image","video","carousel"]}},{"in":"query","name":"platform","schema":{"type":"string","enum":["all","INSTAGRAM","FACEBOOK","AUDIENCE_NETWORK","MESSENGER","THREADS"]}},{"in":"query","name":"active","schema":{"type":"boolean"}},{"in":"query","name":"dateRange","schema":{"type":"string","enum":["last_7_days","last_14_days","last_30_days","last_90_days","last_6_months","this_year","last_year","last_2_years","all"]}},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["reach:desc","relevance:desc","date:asc","date:desc"]}},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","category"],"additionalProperties":false},"reach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"EU transparency reach (impressions) — the basis for spend estimates."},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated spend in EUR, derived from reach at a €30 CPM. An estimate, not billing data."},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"relevanceScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Internal 0-100 performance rank."},"dateDelivered":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the ad was first seen delivering — use it to tell new launches from evergreens."},"platforms":{"type":"array","items":{"type":"string"}},"creative":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary ad copy."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destination the ad links to."},"displayUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ctaText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Call-to-action button text."}},"required":["text","imageUrl","videoUrl","linkUrl","displayUrl","ctaText"],"additionalProperties":false},{"type":"null"}]}},"required":["id","advertiser","reach","estimatedSpendEur","isActive","relevanceScore","dateDelivered","platforms","creative"],"additionalProperties":false}}},"required":["ads"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/tracking/brands":{"get":{"operationId":"tracking-listTrackedBrands","summary":"List your tracked-brand lists","description":"MCP tool: `list_tracked_brands` · Credits: 1 credit · Response size: ≈ 9 tokens + ≈ 150 per result","tags":["tracking"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"lists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"profileImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"totalAds":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedTotalSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","name","profileImageUrl","totalAds","totalReach","estimatedTotalSpendEur"],"additionalProperties":false}}},"required":["id","name","brands"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Number of tracking lists (not just this page)."}},"required":["lists","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/boards":{"get":{"operationId":"boards-listSavedBoards","summary":"List your saved ad boards","description":"MCP tool: `list_saved_boards` · Credits: 1 credit · Response size: ≈ 9 tokens + ≈ 33 per result","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"boards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Id of the parent board for sub-folders; null for top-level boards."},"adCount":{"type":"number"}},"required":["id","name","parentId","adCount"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Number of saved boards (not just this page)."}},"required":["boards","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/boards/{boardId}/ads":{"get":{"operationId":"boards-getSavedBoardAds","summary":"List ads on one saved board","description":"MCP tool: `get_saved_board_ads` · Credits: 1 credit per returned result (min 1, max 50) · Response size: ≈ 12 tokens + ≈ 290 per result","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"boardId","schema":{"type":"string"},"required":true},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"boardId":{"type":"string"},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","category"],"additionalProperties":false},"reach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"EU transparency reach (impressions) — the basis for spend estimates."},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated spend in EUR, derived from reach at a €30 CPM. An estimate, not billing data."},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"relevanceScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Internal 0-100 performance rank."},"dateDelivered":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the ad was first seen delivering — use it to tell new launches from evergreens."},"platforms":{"type":"array","items":{"type":"string"}},"creative":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary ad copy."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destination the ad links to."},"displayUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ctaText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Call-to-action button text."}},"required":["text","imageUrl","videoUrl","linkUrl","displayUrl","ctaText"],"additionalProperties":false},{"type":"null"}]}},"required":["id","advertiser","reach","estimatedSpendEur","isActive","relevanceScore","dateDelivered","platforms","creative"],"additionalProperties":false}}},"required":["boardId","ads"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/saved/folders":{"get":{"operationId":"boards-listSavedFolders","summary":"List your saved folders of one kind","description":"MCP tool: `list_saved_folders` · Credits: 1 credit · Response size: ≈ 10 tokens + ≈ 37 per result","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["ads","landingPages","brands"],"description":"Folder tab: ad folders, landing page folders or brand folders."},"required":true,"description":"Folder tab: ad folders, landing page folders or brand folders."},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"folders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Id of the parent folder for sub-folders; null for top-level folders."},"itemCount":{"type":"number"},"isStarred":{"type":"boolean"}},"required":["id","name","parentId","itemCount","isStarred"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Number of folders of this kind (not just this page)."}},"required":["folders","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/saved/collections":{"get":{"operationId":"boards-listSavedCollections","summary":"List your saved collections","description":"MCP tool: `list_saved_collections` · Credits: 1 credit · Response size: ≈ 11 tokens + ≈ 35 per result","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"adCount":{"type":"number"},"landingPageCount":{"type":"number"},"brandCount":{"type":"number"}},"required":["id","name","adCount","landingPageCount","brandCount"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Number of collections (not just this page)."}},"required":["collections","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/saved/tags":{"get":{"operationId":"boards-listSavedTags","summary":"List your private tags","description":"MCP tool: `list_saved_tags` · Credits: 1 credit · Response size: ≈ 9 tokens + ≈ 35 per result","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"adCount":{"type":"number"},"landingPageCount":{"type":"number"},"brandCount":{"type":"number"}},"required":["id","name","adCount","landingPageCount","brandCount"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Number of tags (not just this page)."}},"required":["tags","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/saved/items":{"get":{"operationId":"boards-getSavedItems","summary":"List saved ads, landing pages or brands of a folder, collection or tag","description":"MCP tool: `get_saved_items` · Credits: 1 credit per returned result (min 1, max 50) · Response size: ≈ 13 tokens + ≈ 290 per result","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"itemType","schema":{"type":"string","enum":["ad","landingPage","brand"]},"required":true},{"in":"query","name":"folderId","schema":{"type":"string"}},{"in":"query","name":"subfolders","schema":{"default":"include","description":"With folderId: \"include\" adds the items of its sub-folders, \"only\" skips them.","type":"string","enum":["include","only"]}},{"in":"query","name":"collectionId","schema":{"type":"string"}},{"in":"query","name":"tagId","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"itemType":{"type":"string","enum":["ad","landingPage","brand"]},"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"advertiser":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","category"],"additionalProperties":false},"reach":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"EU transparency reach (impressions) — the basis for spend estimates."},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated spend in EUR, derived from reach at a €30 CPM. An estimate, not billing data."},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"relevanceScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Internal 0-100 performance rank."},"dateDelivered":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the ad was first seen delivering — use it to tell new launches from evergreens."},"platforms":{"type":"array","items":{"type":"string"}},"creative":{"anyOf":[{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary ad copy."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destination the ad links to."},"displayUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ctaText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Call-to-action button text."}},"required":["text","imageUrl","videoUrl","linkUrl","displayUrl","ctaText"],"additionalProperties":false},{"type":"null"}]}},"required":["id","advertiser","reach","estimatedSpendEur","isActive","relevanceScore","dateDelivered","platforms","creative"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"advertiser":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"],"additionalProperties":false},"pageType":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"adCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"activeAdCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"newAdsLast30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}]},"adSpendScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"0-100: share of the brand’s estimated spend flowing to this page."},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"firstSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","domain","advertiser","pageType","language","adCount","activeAdCount","newAdsLast30d","totalReach","estimatedSpendEur","adSpendScore","screenshotUrl","firstSeenAt","lastSeenAt"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"profileImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"totalAds":{"anyOf":[{"type":"number"},{"type":"null"}]},"activeAds":{"description":"Currently running ads.","anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"description":"Sum of latest EU reach across all ads.","anyOf":[{"type":"number"},{"type":"null"}]},"estimatedTotalSpendEur":{"description":"Estimated total spend in EUR (€30 CPM heuristic).","anyOf":[{"type":"number"},{"type":"null"}]},"newAds30d":{"description":"New ads in the 30 days up to the last time the brand was checked.","anyOf":[{"type":"number"},{"type":"null"}]},"market":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","profileImageUrl","totalAds"],"additionalProperties":false}]},"description":"Ad, landing page or brand summaries depending on itemType, most recently saved first."},"totalMatches":{"type":"number","description":"Number of saved items in this scope (not just this page)."}},"required":["itemType","items","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/boards/{boardId}/statistics":{"get":{"operationId":"boards-getBoardStatistics","summary":"Aggregated statistics for one saved board","description":"MCP tool: `get_board_statistics` · Credits: 1 credit · Response size: ≈ 49 tokens","tags":["boards"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"boardId","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"boardId":{"type":"string"},"adCount":{"type":"number"},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedTotalSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}]},"oldestAdDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"newestAdDate":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["boardId","adCount","totalReach","estimatedTotalSpendEur","oldestAdDate","newestAdDate"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/landing-pages":{"get":{"operationId":"landingPages-searchLandingPages","summary":"Search and browse landing pages","description":"MCP tool: `search_landing_pages` · Credits: 1 credit per returned result (min 1, max 50) · Response size: ≈ 11 tokens + ≈ 160 per result","tags":["landing-pages"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":200}},{"in":"query","name":"advertiserId","schema":{"type":"string"}},{"in":"query","name":"domain","schema":{"type":"string"}},{"in":"query","name":"pageType","schema":{"type":"string","enum":["advertorial","offerpage","quiz","vsl","pdp","listicle","comparison","shop","other"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","inactive","unavailable"]}},{"in":"query","name":"language","schema":{"type":"string","maxLength":8}},{"in":"query","name":"categoryId","schema":{"type":"string"}},{"in":"query","name":"marketId","schema":{"type":"string"}},{"in":"query","name":"niche","schema":{"type":"string"}},{"in":"query","name":"minReach","schema":{"type":"number"}},{"in":"query","name":"minAdSpend","schema":{"type":"number"}},{"in":"query","name":"maxAdSpend","schema":{"type":"number"}},{"in":"query","name":"firstSeenAfter","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"in":"query","name":"firstSeenBefore","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"in":"query","name":"lastSeenAfter","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"in":"query","name":"lastSeenBefore","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["reach:desc","adCount:desc","lastSeen:desc","adSpend:desc","adSpendScore:desc","activeAdCount:desc","firstSeen:asc","firstSeen:desc","newAds30d:desc"]}},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"landingPages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"advertiser":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"],"additionalProperties":false},"pageType":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"adCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"activeAdCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"newAdsLast30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}]},"adSpendScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"0-100: share of the brand’s estimated spend flowing to this page."},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"firstSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","domain","advertiser","pageType","language","adCount","activeAdCount","newAdsLast30d","totalReach","estimatedSpendEur","adSpendScore","screenshotUrl","firstSeenAt","lastSeenAt"],"additionalProperties":false}},"totalMatches":{"type":"number","description":"Estimated total matches for the query/filters (not just this page)."}},"required":["landingPages","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/landing-pages/{landingPageId}":{"get":{"operationId":"landingPages-getLandingPage","summary":"Get one landing page by id","description":"MCP tool: `get_landing_page` · Credits: 3 credits · Response size: ≈ 3,200 tokens","tags":["landing-pages"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"landingPageId","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"advertiser":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"],"additionalProperties":false},"pageType":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"adCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"activeAdCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"newAdsLast30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalReach":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedSpendEur":{"anyOf":[{"type":"number"},{"type":"null"}]},"adSpendScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"0-100: share of the brand’s estimated spend flowing to this page."},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"firstSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulltext":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Extracted page text, max 20,000 characters (null when not yet extracted — this API never triggers extraction)."},"fulltextTruncated":{"type":"boolean","description":"True when fulltext was cut to 20,000 characters."},"technologies":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["id","url","domain","advertiser","pageType","language","adCount","activeAdCount","newAdsLast30d","totalReach","estimatedSpendEur","adSpendScore","screenshotUrl","firstSeenAt","lastSeenAt","fulltext","fulltextTruncated","technologies"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/usage":{"get":{"operationId":"usage-getUsage","summary":"Your API credit balance and costs","description":"MCP tool: `get_usage` · Credits: free · Response size: ≈ 510 tokens","tags":["usage"],"security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"access":{"type":"boolean","description":"Whether this account can use the API (any paid adspends plan)."},"unlimited":{"type":"boolean","description":"Internal accounts that are never charged."},"billingMode":{"type":"string","enum":["off","shadow","enforce"],"description":"off = credits not active yet, shadow = counted but not enforced, enforce = active."},"plan":{"anyOf":[{"type":"object","properties":{"planClass":{"type":"string","description":"starter, growth or scaling."},"isTrial":{"type":"boolean"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["planClass","isTrial","trialEndsAt"],"additionalProperties":false},{"type":"null"}]},"credits":{"anyOf":[{"type":"object","properties":{"planRemaining":{"type":"number","description":"Plan credits left in this period."},"planAllowance":{"type":"number","description":"Plan credits per period (trial: total)."},"packRemaining":{"type":"number","description":"Never-expiring credit-pack credits, used after plan credits."},"totalRemaining":{"type":"number"},"periodResetsAt":{"description":"When plan credits refresh (no rollover).","type":"string"}},"required":["planRemaining","planAllowance","packRemaining","totalRemaining","periodResetsAt"],"additionalProperties":false},{"type":"null"}]},"daily":{"anyOf":[{"type":"object","properties":{"used":{"type":"number"},"cap":{"anyOf":[{"type":"number"},{"type":"null"}]},"remaining":{"anyOf":[{"type":"number"},{"type":"null"}]},"resetsAt":{"description":"Next 00:00 UTC.","type":"string"}},"required":["used","cap","remaining","resetsAt"],"additionalProperties":false},{"type":"null"}]},"costs":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string"},"cost":{"type":"string"}},"required":["tool","cost"],"additionalProperties":false},"description":"Credit cost per tool. Errors are never charged."},"links":{"type":"object","properties":{"upgrade":{"type":"string"},"creditPacks":{"type":"string"}},"required":["upgrade","creditPacks"],"additionalProperties":false},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Relay to the user when set."}},"required":["access","unlimited","billingMode","plan","credits","daily","costs","links","message"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/markets":{"get":{"operationId":"taxonomy-listMarkets","summary":"List markets (valid marketId values)","description":"MCP tool: `list_markets` · Credits: free · Response size: ≈ 940 tokens","tags":["taxonomy"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Use as marketId in search tools."},"name":{"type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]},"brandCount":{"type":"number","description":"Brands with ads in this market."}},"required":["id","name","slug","emoji","brandCount"],"additionalProperties":false}}},"required":["markets"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/categories":{"get":{"operationId":"taxonomy-listCategories","summary":"List advertiser categories (valid categoryId values)","description":"MCP tool: `list_categories` · Credits: free · Response size: ≈ 3,000 tokens","tags":["taxonomy"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":100}},{"in":"query","name":"limit","schema":{"default":100,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Use as categoryId in search tools."},"name":{"type":"string"},"nameGerman":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","nameGerman"],"additionalProperties":false}},"totalMatches":{"type":"number"}},"required":["categories","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/niches":{"get":{"operationId":"taxonomy-listNiches","summary":"List niches (valid niche values)","description":"MCP tool: `list_niches` · Credits: free · Response size: ≈ 1,900 tokens","tags":["taxonomy"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string","maxLength":100}},{"in":"query","name":"limit","schema":{"default":100,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"niches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Use as niche in search tools."},"name":{"type":"string"},"brandCount":{"type":"number","description":"Brands tagged with this niche."}},"required":["id","name","brandCount"],"additionalProperties":false}},"totalMatches":{"type":"number"}},"required":["niches","totalMatches"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}},"components":{"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Invalid input data"},"code":{"type":"string","description":"The error code","example":"BAD_REQUEST"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information","example":{"code":"BAD_REQUEST","message":"Invalid input data","issues":[]}},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Authorization not provided"},"code":{"type":"string","description":"The error code","example":"UNAUTHORIZED"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information","example":{"code":"UNAUTHORIZED","message":"Authorization not provided","issues":[]}},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Insufficient access"},"code":{"type":"string","description":"The error code","example":"FORBIDDEN"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information","example":{"code":"FORBIDDEN","message":"Insufficient access","issues":[]}},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Not found"},"code":{"type":"string","description":"The error code","example":"NOT_FOUND"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information","example":{"code":"NOT_FOUND","message":"Not found","issues":[]}},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message","example":"Internal server error"},"code":{"type":"string","description":"The error code","example":"INTERNAL_SERVER_ERROR"},"issues":{"description":"An array of issues that were responsible for the error","example":[],"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information","example":{"code":"INTERNAL_SERVER_ERROR","message":"Internal server error","issues":[]}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"adspends API key (adsp_live_…) or Clerk OAuth access token"}}}}