{"openapi":"3.1.0","info":{"title":"MarsDSP API","version":"1.0.0","description":"Statistics and campaign actions for your MarsDSP account. Money values are integers in cents.","contact":{"email":"support@mars.media"}},"servers":[{"url":"https://marsdsp.com/api/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"account"},{"name":"stats"},{"name":"campaigns"},{"name":"actions"},{"name":"creatives"},{"name":"audiences"},{"name":"library"},{"name":"wallet"},{"name":"webhooks"}],"paths":{"/me":{"get":{"operationId":"getMe","tags":["account"],"summary":"The token and the account it works in","description":"Use it to check a token: it returns the account, the token's scopes and when it expires.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"account":{"id":"01JB…","name":"Acme","type":"advertiser","currency":"USD"},"token":{"id":"01JD…","name":"BI export","prefix":"dsp_a1b2c3d4","scopes":["stats.read"],"expiresAt":"2027-01-16T08:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/stats":{"get":{"operationId":"getStats","tags":["stats"],"summary":"Statistics for the account","description":"The same report as the Reports page: totals, the change against the comparison period, a time series and one row per group. An agency account's report covers its clients too. Money values are in cents.","security":[{"bearer":["stats.read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"The period.","schema":{"type":"string","enum":["today","yesterday","last_7","last_14","last_30","last_90","mtd","last_month","qtd","ytd","custom"],"default":"last_30"}},{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD, UTC) when preset is custom.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD, UTC, inclusive) when preset is custom.","schema":{"type":"string"}},{"name":"groupBy","in":"query","required":false,"description":"What each row is.","schema":{"type":"string","enum":["campaign","channel","platform","pricing_model","goal","status","day","week","month","geo","device","os","placement","app_or_site","creative","audience","split","hour"],"default":"campaign"}},{"name":"granularity","in":"query","required":false,"description":"Time step of the series.","schema":{"type":"string","enum":["auto","day","week","month"],"default":"auto"}},{"name":"compare","in":"query","required":false,"description":"Period the deltas compare with.","schema":{"type":"string","enum":["previous","last_year","none"],"default":"previous"}},{"name":"campaign","in":"query","required":false,"description":"Only these campaigns (comma-separated ids).","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"description":"Only these channels (comma-separated).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only campaigns in these statuses (comma-separated).","schema":{"type":"string","enum":["draft","learning","live","paused","paused_no_funds","ended"]}},{"name":"sort","in":"query","required":false,"description":"Metric the rows are sorted by.","schema":{"type":"string","enum":["spend","impressions","reach","clicks","ctr","views","completedViews","vtr","conversions","cvr","conversionValue","ecpm","cpc","cpv","cpcv","cpa","roas","profit","epc","billed","agencyMarkup"],"default":"spend"}},{"name":"dir","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (up to 500).","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"period":{"from":"2026-09-18","to":"2026-10-17"},"currency":"USD","totals":{"spend":125000,"impressions":980000,"clicks":6400,"ctr":0.0065,"conversions":212,"cpa":590,"roas":3.1},"rows":[{"key":"01JC0Q…","label":"Spring sale","metrics":{"spend":80000,"impressions":610000,"clicks":4100,"conversions":150}}],"rowsTotal":1}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/stats.csv":{"get":{"operationId":"getStatsCsv","tags":["stats"],"summary":"Statistics for the account, as CSV","description":"The rows of /stats as a CSV file, with the same parameters.","security":[{"bearer":["stats.read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"The period.","schema":{"type":"string","enum":["today","yesterday","last_7","last_14","last_30","last_90","mtd","last_month","qtd","ytd","custom"],"default":"last_30"}},{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD, UTC) when preset is custom.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD, UTC, inclusive) when preset is custom.","schema":{"type":"string"}},{"name":"groupBy","in":"query","required":false,"description":"What each row is.","schema":{"type":"string","enum":["campaign","channel","platform","pricing_model","goal","status","day","week","month","geo","device","os","placement","app_or_site","creative","audience","split","hour"],"default":"campaign"}},{"name":"granularity","in":"query","required":false,"description":"Time step of the series.","schema":{"type":"string","enum":["auto","day","week","month"],"default":"auto"}},{"name":"compare","in":"query","required":false,"description":"Period the deltas compare with.","schema":{"type":"string","enum":["previous","last_year","none"],"default":"previous"}},{"name":"campaign","in":"query","required":false,"description":"Only these campaigns (comma-separated ids).","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"description":"Only these channels (comma-separated).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only campaigns in these statuses (comma-separated).","schema":{"type":"string","enum":["draft","learning","live","paused","paused_no_funds","ended"]}},{"name":"sort","in":"query","required":false,"description":"Metric the rows are sorted by.","schema":{"type":"string","enum":["spend","impressions","reach","clicks","ctr","views","completedViews","vtr","conversions","cvr","conversionValue","ecpm","cpc","cpv","cpcv","cpa","roas","profit","epc","billed","agencyMarkup"],"default":"spend"}},{"name":"dir","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (up to 500).","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/stats/data.csv":{"get":{"operationId":"getStatsDataCsv","tags":["stats"],"summary":"Every metric per day, campaign and channel, as CSV","description":"The same data file the scheduled stats emails attach: one line per UTC day, campaign and channel with every metric, for the period and filters of /stats. Use preset=today for today so far.","security":[{"bearer":["stats.read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"The period.","schema":{"type":"string","enum":["today","yesterday","last_7","last_14","last_30","last_90","mtd","last_month","qtd","ytd","custom"],"default":"last_30"}},{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD, UTC) when preset is custom.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Last day (YYYY-MM-DD, UTC, inclusive) when preset is custom.","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Only these campaigns (comma-separated ids).","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"description":"Only these channels (comma-separated).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only campaigns in these statuses (comma-separated).","schema":{"type":"string","enum":["draft","learning","live","paused","paused_no_funds","ended"]}}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/stats":{"get":{"operationId":"getCampaignStats","tags":["stats"],"summary":"Statistics for one campaign","description":"Totals and a daily series for the last `days` days.","security":[{"bearer":["stats.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"How many days back from today (1 to 365).","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/stats.csv":{"get":{"operationId":"getCampaignStatsCsv","tags":["stats"],"summary":"Daily statistics for one campaign, as CSV","security":[{"bearer":["stats.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"How many days back from today (1 to 365).","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/breakdown":{"get":{"operationId":"getCampaignBreakdown","tags":["stats"],"summary":"One campaign split by hour, creative, country, device and more","description":"Use dimension=hour for hourly figures.","security":[{"bearer":["stats.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"dimension","in":"query","required":true,"description":"How to split the figures.","schema":{"type":"string","enum":["creative","geo","device","os","placement","hour","audience"]}},{"name":"days","in":"query","required":false,"description":"How many days back from today (1 to 365).","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":[{"key":"14","label":"14:00","impressions":41000,"clicks":270,"conversions":9,"spend":5200,"ctr":0.0066,"costPerKpi":578}]}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/agency/summary":{"get":{"operationId":"getAgencySummary","tags":["stats"],"summary":"Agency accounts: the last 30 days per client","description":"Spend, what each client is billed, your markup and fee share, per client and in total. Agency accounts only.","security":[{"bearer":["stats.read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns":{"get":{"operationId":"listCampaigns","tags":["campaigns"],"summary":"List campaigns","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Only these statuses (comma-separated).","schema":{"type":"string","enum":["draft","learning","live","paused","paused_no_funds","ended"]}},{"name":"q","in":"query","required":false,"description":"Name contains.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","required":false,"description":"Rows per page (up to 100).","schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"01JC0Q6Z8M2R7K4S9T1V3W5X7Y","name":"Spring sale","goal":"sales","status":"live","pricingModel":"cpm","dailyBudget":5000,"totalBudget":null,"startAt":"2026-10-01T00:00:00.000Z","endAt":null,"channels":[{"channel":"display","sharePct":60},{"channel":"ctv","sharePct":40}]}],"total":1,"page":1,"pageSize":25}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createCampaign","tags":["actions"],"summary":"Create a draft campaign","description":"Creates a draft with the goal's recommended channel mix. Set its budget, dates, audiences and creatives with PATCH, then launch it.","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"goal":"sales","name":"Spring sale"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"01JC0Q6Z8M2R7K4S9T1V3W5X7Y","name":"Spring sale","goal":"sales","status":"draft","pricingModel":"cpm","dailyBudget":5000,"totalBudget":null,"startAt":"2026-10-01T00:00:00.000Z","endAt":null,"channels":[{"channel":"display","sharePct":60},{"channel":"ctv","sharePct":40}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}":{"get":{"operationId":"getCampaign","tags":["campaigns"],"summary":"One campaign","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"01JC0Q6Z8M2R7K4S9T1V3W5X7Y","name":"Spring sale","goal":"sales","status":"live","pricingModel":"cpm","dailyBudget":5000,"totalBudget":null,"startAt":"2026-10-01T00:00:00.000Z","endAt":null,"channels":[{"channel":"display","sharePct":60},{"channel":"ctv","sharePct":40}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateCampaign","tags":["actions"],"summary":"Edit a campaign: budget, dates, name, target, channels, audiences, creatives","description":"Send only the fields you change. Budgets are in cents (daily budget at least 500).","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"},"example":{"dailyBudget":7500}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"01JC0Q6Z8M2R7K4S9T1V3W5X7Y","name":"Spring sale","goal":"sales","status":"live","pricingModel":"cpm","dailyBudget":7500,"totalBudget":null,"startAt":"2026-10-01T00:00:00.000Z","endAt":null,"channels":[{"channel":"display","sharePct":60},{"channel":"ctv","sharePct":40}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/launch-check":{"get":{"operationId":"getLaunchCheck","tags":["campaigns"],"summary":"What a draft still needs before it can launch","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/changes":{"get":{"operationId":"listCampaignChanges","tags":["campaigns"],"summary":"Changes the optimizer made to a campaign, each with its reason","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/from-text":{"post":{"operationId":"createCampaignFromText","tags":["actions"],"summary":"Create a draft campaign from one sentence","description":"\"$50 a day for my app in Israel\" becomes a draft with the goal, daily budget, countries and interests it names; the rest comes from the account's brand kit (name, target, channel mix, AI-picked audiences). Nothing is launched. `defaulted` lists what the sentence didn't give.","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"text":"$50 a day for my app in Israel"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"campaign":{"id":"01JC…","name":"Acme – App installs","status":"draft","goal":"installs","dailyBudget":5000,"currency":"USD","geo":["IL"],"interests":[]},"defaulted":[],"summary":"Created the draft \"Acme – App installs\": App installs, $50/day, Israel.\nReview it, add creatives and launch it from the wizard. Nothing runs until it is launched.","reviewPath":"/wizard/01JC…/audience"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/launch":{"post":{"operationId":"launchCampaign","tags":["actions"],"summary":"Launch a draft","description":"Runs the same checks as the app (wallet, creatives, review). A refused launch answers 422 with the checklist in details.","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/pause":{"post":{"operationId":"pauseCampaign","tags":["actions"],"summary":"Pause a campaign","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/resume":{"post":{"operationId":"resumeCampaign","tags":["actions"],"summary":"Resume a paused campaign","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/end":{"post":{"operationId":"endCampaign","tags":["actions"],"summary":"End a campaign for good","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/duplicate":{"post":{"operationId":"duplicateCampaign","tags":["actions"],"summary":"Copy a campaign into a new draft","security":[{"bearer":["campaigns.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/creatives":{"get":{"operationId":"listCreatives","tags":["creatives"],"summary":"List creatives","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"campaignId","in":"query","required":false,"description":"Only the creatives of this campaign.","schema":{"type":"string"}},{"name":"formatId","in":"query","required":false,"description":"Only this format.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/creatives/{id}":{"get":{"operationId":"getCreative","tags":["creatives"],"summary":"One creative","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The creative id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/audiences":{"get":{"operationId":"listAudiences","tags":["audiences"],"summary":"Search the audience catalogue and your own audiences","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Search words.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/audiences/{id}":{"get":{"operationId":"getAudience","tags":["audiences"],"summary":"One audience","security":[{"bearer":["campaigns.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The audience id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/library/sites":{"get":{"operationId":"lookupLibrarySite","tags":["library"],"summary":"What the library knows about a website or app","description":"Pass a domain, a URL or an app id. Answers the library's placement for it (score, warnings, measured viewability and invalid traffic, ads.txt and store readings), or item null when the library has none, and the account's packages with whether each already holds it. The browser extension calls this on every site.","security":[{"bearer":["library.read"]}],"parameters":[{"name":"domain","in":"query","required":true,"description":"A domain, URL or app id, for example news.example.com.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"domain":"news.example.com","item":{"id":"01JE…","name":"News Example","kind":"web","score":82,"lowViewability":false,"highIvt":false},"packages":[{"id":"01JF…","name":"News sites","hasItem":false}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/library/packages":{"post":{"operationId":"createLibraryPackage","tags":["library"],"summary":"Create a package of placements","description":"A new package in the account's library. Start a campaign from it with /wizard?package=<id>.","security":[{"bearer":["library.write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"news.example.com","itemIds":["01JE…"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"package":{"id":"01JF…","name":"news.example.com"}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/library/packages/{id}/items":{"post":{"operationId":"addLibraryPackageItems","tags":["library"],"summary":"Add placements to a package","description":"Adds the placements a package does not hold yet; the ones it holds stay as they are, so a repeat is harmless.","security":[{"bearer":["library.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The package id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"itemIds":["01JE…"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/wallet":{"get":{"operationId":"getWallet","tags":["wallet"],"summary":"Wallet balance and today's spend","security":[{"bearer":["wallet.read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"balanceCents":245000,"currency":"USD"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/wallet/ledger":{"get":{"operationId":"listLedger","tags":["wallet"],"summary":"Wallet transactions","security":[{"bearer":["wallet.read"]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","required":false,"description":"Rows per page (up to 200).","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/wallet/ledger.csv":{"get":{"operationId":"getLedgerCsv","tags":["wallet"],"summary":"Every wallet transaction, as CSV","security":[{"bearer":["wallet.read"]}],"parameters":[],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","tags":["webhooks"],"summary":"The account's webhooks and the events they can subscribe to","security":[{"bearer":["webhooks.manage"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createWebhook","tags":["webhooks"],"summary":"Subscribe a URL to events","description":"Each event is a signed POST (Standard Webhooks headers webhook-id, webhook-timestamp and webhook-signature, HMAC-SHA256 with the secret this call returns once). Failed deliveries retry for about a day and a half. This is the REST hook Zapier, Make and n8n subscribe with.","security":[{"bearer":["webhooks.manage"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"url":"https://hooks.zapier.com/hooks/standard/123/abc/","events":["campaign.launched","wallet.low"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"item":{"id":"01JF…","url":"https://hooks.zapier.com/hooks/standard/123/abc/","events":["campaign.launched","wallet.low"],"active":true},"secret":"whsec_…"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","tags":["webhooks"],"summary":"Unsubscribe a webhook","security":[{"bearer":["webhooks.manage"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The webhook id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8 to 128 characters. A retry with the same key returns the first answer instead of acting twice.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/sample":{"get":{"operationId":"getWebhookSample","tags":["webhooks"],"summary":"An example of an event's body","security":[{"bearer":["webhooks.manage"]}],"parameters":[{"name":"event","in":"query","required":true,"description":"The event, such as campaign.launched.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"evt_01JF…","type":"campaign.launched","createdAt":"2026-10-26T08:00:00.000Z","account":{"id":"01JB…"},"data":{"campaign":{"id":"01JC…","name":"Spring sale"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A token from Settings > API. Scopes: stats.read (Read statistics); campaigns.read (Read campaigns, creatives and audiences); campaigns.write (Create, edit, launch, pause, resume and end campaigns); wallet.read (Read the wallet balance and transactions); library.read (Look up placements in the inventory library); library.write (Create library packages and add placements to them); webhooks.manage (Subscribe to events with webhooks (Zapier, Make, n8n))."}},"responses":{"Error":{"description":"400 bad_request: A parameter or the body is not valid; details say which. 401 invalid_token: No token, an unknown one, or one that was revoked or expired. 403 insufficient_scope: The token lacks the scope this endpoint needs. 403 forbidden: The person who created the token can't do this any more (their role changed). 404 not_found: No such endpoint, or no such record in this account. 409 idempotency_in_progress: A request with the same Idempotency-Key is still running. 422 idempotency_key_reused: The Idempotency-Key was used for a different request. 429 rate_limited: Too many requests; wait Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["error","message"]}}}}}}}