← Back to docs

API Reference

A practical reference for the exchange’s HTTP endpoints. For exact payloads, see the server route handlers.

Edit this page →

Authentication

text
Authenticated requests use NextAuth sessions (role-based access: admin | publisher | demand). For
some endpoints, the exchange also supports a lightweight email lock via query/body where noted in code.

Publishers API

Create publisher
POST /api/publishers
Auth required: admin
json
{
  "name": "Example Publisher",
  "domain": "publisher.example",
  "contact_email": "publisher@example.com",
  "sizes": ["300x250"],
  "ad_type": "display",
  "environment": "web",
  "floor_price": 0.5
}
json
{
  "id": "UUID",
  "status": "pending",
  "name": "Example Publisher",
  "domain": "publisher.example"
}
Get publisher
GET /api/publishers/:id
Auth required: admin/publisher
Update publisher status
PATCH /api/publishers/:id
Auth required: admin
json
{
  "status": "active"
}
json
{ "id": "UUID", "status": "active" }
Delete publisher
DELETE /api/publishers/:id
Auth required: admin

Campaigns API

Create campaign
POST /api/campaigns
Auth required: demand (or admin)
json
{
  "advertiser_name": "Example Advertiser",
  "advertiser_email": "buyer@example.com",
  "campaign_name": "Spring Promo",
  "bid_price": 5.0,
  "daily_budget": 50,
  "target_sizes": ["300x250"],
  "target_environments": ["web"],
  "target_devices": ["desktop"],
  "target_geos": ["all"]
}
json
{
  "id": "UUID",
  "status": "pending",
  "campaign_name": "Spring Promo"
}
List campaigns by email
GET /api/campaigns?email={email}
Auth required: public (email lock)
json
[{ "id": "UUID", "campaign_name": "Spring Promo" }]
Update campaign
PATCH /api/campaigns/:id
Auth required: admin/demand
Bulk import campaigns (CSV)
POST /api/campaigns/bulk
Auth required: public (email lock)
Bulk status update
PATCH /api/campaigns/bulk-status
Auth required: demand/admin
Export campaigns as CSV
GET /api/campaigns/export?email={email}
Auth required: public (email lock)
Duplicate campaign
POST /api/campaigns/:id/duplicate
Auth required: demand/admin
Auto-optimize bid
POST /api/campaigns/:id/auto-optimize
Auth required: demand/admin

Creatives API

Create creative
POST /api/creatives
Auth required: public (email lock) / demand/admin
json
{
  "campaign_id": "UUID",
  "advertiser_email": "buyer@example.com",
  "name": "Creative name",
  "type": "banner",
  "size": "300x250",
  "click_url": "https://landing.example",
  "file": "<multipart form upload>"
}
json
{
  "id": "UUID",
  "campaign_id": "UUID",
  "size": "300x250",
  "status": "active"
}
List creatives by campaign/email
GET /api/creatives?campaign_id={id}&email={email}
Auth required: public (email lock)
Update creative
PATCH /api/creatives/:id
Auth required: admin/demand
Delete creative
DELETE /api/creatives/:id
Auth required: admin/demand
Scan creative (rescan)
POST /api/creatives/:id/scan
Auth required: publisher/admin

Reports API

Admin dashboard reports
GET /api/reports/dashboard
Auth required: admin
json
{ "auctionsToday": 123, "activeCampaigns": 12 }
Demand performance
GET /api/demand-performance
Auth required: admin
json
{ "rows": [ ... ] }
Auction log query
GET /api/auction-log?limit=10&preset=today
Auth required: admin
Impression pixel
GET /api/track/impression?id={auction_log_uuid}
Auth required: public (pixel)
json
(Returns a 1x1 transparent GIF)