Meridian Exchange · DocsDemo chatDashboard

Contextual ads for AI apps

Match ads to the conversation, not to cookies. Keep the model's answer untouched; show one clearly labelled suggestion next to it, only when it helps.

1. Request an ad (server-side)

Call this in parallel with your LLM request. Never make the answer wait for the ad. Keep the key on your server.

POST /api/v1/ad
Authorization: Bearer pk_live_…        (pk_test_… = test traffic, never billed)
Content-Type: application/json

{
  "messages": [{"role":"user","content":"How do I deploy Postgres for Next.js?"},
               {"role":"assistant","content":"…"}],         // last 2 used
  "user": { "userId": "u_123", "country": "US" },           // userId is hashed per publisher
  "placements": [{ "placement": "below_response", "placement_id": "main" }],  // ≤ 10
  "relevancy": 0.3,                    // optional floor 0–1 (publisher default otherwise)
  "excludedTopics": ["politics"],      // optional, added to the default safety list
  "alwaysReturn": false                // test keys only: skip the relevancy floor
}

200 one distinct ad per placement:

{ "requestId": "req_…", "elapsed_ms": 31,
  "ads": [{ "adId": "ad_…", "placement": "below_response", "placement_id": "main",
    "unit": "text_card", "label": "Sponsored", "brand": "Neonbase", "title": "Neonbase",
    "body": "Serverless Postgres that…", "cta": "Start free",
    "clickUrl": "https://…/c/ad_…", "impUrl": "https://…/i/ad_…",
    "relevance": 0.81, "signals": { "keyword": 0.82, "semantic": 0.74, "intent": 1, "matched": ["postgres","next.js"] } }] }

204 no ad. The X-MX-Reason header says why: safety:mental_health, below_relevancy_floor, ineligible:budget,frequency_cap, no_campaigns. 401 bad key, 400 bad body.

Placements: below_response, above_response, inline_response, left_response, right_response, search_result, top_page, bottom_page. New placement_ids are registered on first use and reported per slot.

Server helper (never throws, 1.5 s timeout): meridian-server.mjs

import { getAds } from './meridian-server.mjs';
const adPromise = getAds({ messages, userId, placements: [{ placement: 'below_response', placement_id: 'main' }] });
const answer = await streamLLM(messages);   // user sees the answer first
const { ads } = await adPromise;

2. Show the ad (browser)

<script src="/sdk.js"></script>
MeridianAds.render(document.getElementById('slot'), ads[0]);

The SDK draws a labelled card with a “Why this ad” note, opens clickUrl on click and loads impUrl once the card is ≥50% visible for 1 s. Theme with --mx-accent, --mx-bg, --mx-border, --mx-radius. Drawing your own UI: show a clear “Sponsored” label, load impUrl once when visible, link to clickUrl (not the landing page).

3. Brand safety

Every request is classified before the auction. These categories never receive ads: self_harm, mental_health, medical, grief, nsfw, hate, violence, minors, profanity, financial_distress, legal_trouble. Publishers may add politics, gambling and others via excludedTopics; advertisers may block topics per campaign. Creative or chit-chat prompts (poems, jokes, translations) carry low commercial intent and rarely clear the relevancy floor. See GET /api/v1/topics.

4. How the auction works

StepWhat happens
EligibilityActive, in flight, geo match, under daily and total budget, even pacing through the day, per-user frequency cap (default 3/day).
Relevancemax(keyword match, semantic match via Workers AI bge-small embeddings) × commercial-intent factor. Must clear the floor.
RankingeCPM × relevance. CPC bids become eCPM through a smoothed predicted CTR.
PriceGeneralised second price: the lowest bid that would still win, floor $2 CPM, never above the bid.
BillingCPM on viewable impression, CPC on click. Bots and test keys are logged but not billed. Publisher earns the revenue share (default 70%).

5. Conversions (advertisers)

Clicks land on your page with ?mx_click=ad_…. Either add the pixel:

<script src="https://YOUR-EXCHANGE/px.js"></script>
<script>mx('track', 'purchase', { value: 49, eventId: 'order_881' })</script>

…or send it from your server (30-day click attribution, deduplicated by event_id):

POST /api/v1/conversions
{ "click_id": "ad_…", "event": "purchase", "value": 49, "event_id": "order_881" }

The pixel sends nothing when the browser signals Global Privacy Control.

6. Admin API

All require Authorization: Bearer ADMIN_TOKEN.

EndpointPurpose
GET /api/v1/stats?days=7Fill rate, impressions, clicks, CTR, conversions, spend, payouts, latency p50/p95, no-fill reasons, per-campaign ROAS, recent decisions
GET|POST /api/v1/campaignsList / create campaigns
PATCH /api/v1/campaigns/:idPause, resume, change bid, budget, copy
POST /api/v1/creativeDraft ad copy, keywords and context from a product description (Workers AI)
GET|POST /api/v1/publishersList publishers with placements / onboard a publisher and issue live + test keys