Adsourcer Developer

API reference

REST endpoints for ad recommendations, campaign management, analytics, and event tracking.

Publisher — POST /v1/ads/recommend

Core endpoint for publishers. Returns sponsored recommendations with mandatory disclosure fields. Requires a publisher-scoped API key.

Request
json
{  "query": "wireless keyboard under €150",  "context": {    "currency": "EUR",    "location": "NO",    "session_id": "anon-session-uuid"  },  "placement": "recommendation",  "max_results": 3}
Response
json
{  "request_id": "550e8400-e29b-41d4-a716-446655440000",  "decision": "SHOW",  "ads": [{    "ad_id": "660e8400-e29b-41d4-a716-446655440001",    "title": "Keychron K2 Wireless",    "price": 129.0,    "currency": "EUR",    "sponsored": true,    "disclosure": "Sponsored",    "click_url": "http://localhost:8000/v1/click/eyJ..."  }]}

When intent is not commercial, decision is NO_AD and ads is empty.

Public — GET /v1/click/{token}

Signed redirect endpoint. Validates the token, records the click, and returns a 302 to the advertiser URL. No API key required — this is the href you expose to end users.

See the click tracking guide for details.

Events

  • POST /v1/events/impression
  • POST /v1/events/click
  • POST /v1/events/conversion

Prefer click_url redirects over manual click events. Impressions can be recorded when ads render; conversions attach to prior clicks.

Advertiser

  • POST /v1/campaigns
  • GET /v1/campaigns
  • POST /v1/products
  • GET /v1/products
  • GET /v1/analytics/advertiser
  • GET /v1/balance
  • POST /v1/balance/topup

Manage campaigns from the dashboard or API. See the advertiser guide.

Publisher analytics

  • GET /v1/analytics/publisher

OpenAPI

Interactive Swagger docs at http://localhost:8000/docs when the API is running locally.