REST API

Performance demand by default. Uncertified API integrations serve CPC (filtered) and CPA demand only. If you render ads in a real client and implement the impression pixel correctly, you can certify for Direct and Programmatic CPM demand. The rules are below and in Choosing your integration path.

The REST API is for architectures where an SDK cannot run: server-rendered stacks, proprietary clients, enterprise deployments. You call the serve endpoint, receive an ad payload, and render it yourself. That last part is where integrations succeed or fail, so read the tracking obligations before writing any code.

Authentication

Send your publisher key in either header. They are interchangeable, and the value is the same:

x-mcp-api-key: YOUR_PUBLISHER_KEY

Authorization: Bearer YOUR_PUBLISHER_KEY

If you send both, x-mcp-api-key is the one that is read. A request with neither is rejected with 401 Authentification failed: no_api_key.

Serve an ad

POST https://api.adgentek.ai/ad-server/v1/get-ad

https://api.adgentek.ai/functions/v1/mcp-ad-server/get-ad is an alias for this endpoint. Both accept the same request and return the same response, so existing integrations do not need to change. Use /ad-server/v1/ for new ones — it matches the click_url and impression_url values the API returns.

curl -X POST https://api.adgentek.ai/ad-server/v1/get-ad \
  -H "x-mcp-api-key: YOUR_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slot_id": "your-slot-id",
    "context": {
      "messages": [
        { "role": "user", "content": "best mattress for back pain under 1500" },
        { "role": "assistant", "content": "For back pain, medium-firm hybrid mattresses..." }
      ],
      "session_id": "conv_8f2a"
    },
    "surface_type": "conversational",
    "format_preferences": ["inline", "native"]
  }'

Field	Type	Required	Description
`slot_id`	string	Yes	The slot being filled
`context.messages`	object[]	Yes	Conversation turns, each `{ role, content }`. `role` is `user`, `assistant` or `system`
`context.session_id`	string	No	Stable per-conversation ID for frequency capping. Send it — capping depends on it
`surface_type`	string	No	`conversational`, `search`, `voice`, `image`, `video`, `coding`, `web` or `agent`
`format_preferences`	string[]	No	Restrict eligible formats. Only `inline` and `native` are accepted
`geo`	object	No	`{ country, region, city, zip }`, all optional
`custom`	object	No	String-to-string map stored for reporting. Does not affect targeting. See Custom parameters

Unknown request fields are ignored, not rejected. A misspelled or invented parameter does not produce an error — the request succeeds and your parameter simply has no effect. Check names against the table above rather than relying on a validation error to catch a typo.

Response

{
  "ads": [
    {
      "id": "10d78976-5949-465b-9814-1b2051dd8081",
      "creative_id": "015e3058-289b-46c2-8948-ef91d4a31156",
      "format": "native",
      "title": "Packed with a Purpose",
      "content": "Struggling with gift ideas? ...",
      "cta": "Connect with an Expert",
      "image_url": "https://...",
      "click_url": "https://api.adgentek.ai/ad-server/v1/click-redirect?...",
      "impression_url": "https://api.adgentek.ai/ad-server/v1/track-impression?...",
      "placement": { "position": "inline", "paragraph_index": 1 },
      "targeting_score": 0.5,
      "bid_price": 4.66,
      "cleared_price_usd": 4.66,
      "advertiser_domain": "packedwithpurpose.eco",
      "adomain": ["packedwithpurpose.eco"]
    }
  ]
}

A no-fill returns { "ads": [] }. Render nothing — no-fill is a normal outcome on conversational inventory.

Price fields

Both prices are CPM in USD — the price per thousand impressions, not per impression. Per-impression revenue is cleared_price_usd / 1000.

Field	Type	Description
`bid_price`	number	The price for this placement, as a CPM. Use this to include Adgentek in a client-side auction against other partners.
`cleared_price_usd`	number	The same value, named for revenue reconciliation.

Both are always present on a filled ad.

These two fields currently carry the same number. Both are the winning ad’s clearing price. bid_price is the name to read if you are running an auction; cleared_price_usd is the name to read if you are reconciling revenue. Do not treat them as a bid and a separate settlement price that might differ — today they will not.It is a cleared price, not a raw demand-side bid. The value is what the winning bid cleared at after the auction ran, which is the price you will actually be credited for. That is normally what an auction integration wants, but it does mean it is not the gross bid a demand partner submitted.

Rounding: reconcile against cp, not against cleared_price_usd. Both JSON fields are rounded to 2 decimal places, while the cp query parameter on the impression and click URLs carries the same price at higher precision. In a real response, cleared_price_usd read 4.66 while the URLs carried cp=4.6629.For display, use cleared_price_usd. For settlement figures that must tie out, use cp — at CPM scale the rounding is a real difference.

Rendering and tracking obligations

These three rules determine whether your impressions are billable. They are not optional. 1. Fire the impression pixel client-side, as an image request.

// Correct: fires from the user's browser when the ad enters the viewport
const ad = response.ads[0];
new Image().src = ad.impression_url;

2. Never fire it via fetch.

// Wrong: CORS blocks this silently in many contexts. The event never arrives.
fetch(ad.impression_url);

3. Never fire it from your backend.

// Wrong: any server-side request to the impression URL originates from
// datacenter IP space and is classified as GIVT by verification vendors.
// The impression is discarded and unbilled.

Clicks must use click_url from the payload. It routes through the Adgentek redirect layer where click-quality filtering runs. Linking users directly to advertiser destinations breaks CPC billing and fails integration review.

Certification for impression-priced demand

Once your client-side impression implementation is live:

Confirm in your own DevTools that the pixel fires from the browser on render.
Email hello@adgentek.ai with your placement IDs to request an integration review.
On approval, Direct and Programmatic demand become eligible for your placements. Certification is per placement and revocable if server-side impression traffic appears.

Get Started

Concepts

Integrations

Dashboard

Policies

Authentication

Serve an ad

Response

Price fields

Rendering and tracking obligations

Certification for impression-priced demand

Full endpoint reference

​Authentication

​Serve an ad

​Response

​Price fields

​Rendering and tracking obligations

​Certification for impression-priced demand

​Full endpoint reference

Authentication

Serve an ad

Response

Price fields

Rendering and tracking obligations

Certification for impression-priced demand

Full endpoint reference