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
| Step | What happens |
|---|---|
| Eligibility | Active, in flight, geo match, under daily and total budget, even pacing through the day, per-user frequency cap (default 3/day). |
| Relevance | max(keyword match, semantic match via Workers AI bge-small embeddings) × commercial-intent factor. Must clear the floor. |
| Ranking | eCPM × relevance. CPC bids become eCPM through a smoothed predicted CTR. |
| Price | Generalised second price: the lowest bid that would still win, floor $2 CPM, never above the bid. |
| Billing | CPM 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.
| Endpoint | Purpose |
|---|---|
GET /api/v1/stats?days=7 | Fill rate, impressions, clicks, CTR, conversions, spend, payouts, latency p50/p95, no-fill reasons, per-campaign ROAS, recent decisions |
GET|POST /api/v1/campaigns | List / create campaigns |
PATCH /api/v1/campaigns/:id | Pause, resume, change bid, budget, copy |
POST /api/v1/creative | Draft ad copy, keywords and context from a product description (Workers AI) |
GET|POST /api/v1/publishers | List publishers with placements / onboard a publisher and issue live + test keys |