AI API

POST /v1/ai/process matches a contextual ad to one assistant message. The AI SDK integrations call this endpoint, and you can call it directly.

POST /v1/ai/process

POST https://api.adzen.ai/v1/ai/process

Headers

See Authentication for how to get a key.

Body

Adzen checks the API key first, then parses the body, then checks the field rules above.

Example request

curl -X POST https://api.adzen.ai/v1/ai/process \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0f8b6d2e-5c1a-4e7b-9d3f-2a6c8e1b4f70' \
  -d '{
    "message_id": "msg_abc123",
    "content": "For a leaking pipe, shut off the main water valve first, then call a plumber.",
    "conversation_id": "conv_7f3a9b2e",
    "location": "US-WA"
  }'

Response

A match returns 200 with one ad:

{
  "message_id": "msg_abc123",
  "ads": [
    {
      "ad_id": 1071,
      "title": "24/7 Emergency Plumbing",
      "cta": "Book a licensed plumber",
      "click_through_url": "https://api.adzen.ai/dea/ai/redirect/k3x9q2m",
      "advertiser_name": "Example Plumbing Co.",
      "sponsor_logo_url": "https://cdn.example.com/logos/example-plumbing.png",
      "creative_url": "https://cdn.example.com/creatives/plumber-van.jpg",
      "description": "Same-day repairs for leaks, clogs and burst pipes.",
      "pricing_model": "CPC",
      "relevancy_score": 0.9473,
      "placement": "after_message",
      "pixel_trackers": [],
      "render_impression_url": "https://api.adzen.ai/dea/ai/impressions/render?ad_id=1071&message_id=msg_abc123&slug=k3x9q2m&conversation_id=conv_7f3a9b2e&ad_unit_position=after_message&timestamp=2026-10-30T14%3A02%3A11.483920517%2B00%3A00",
      "view_impression_url": "https://api.adzen.ai/dea/ai/impressions/view?ad_id=1071&message_id=msg_abc123&slug=k3x9q2m&conversation_id=conv_7f3a9b2e&ad_unit_position=after_message&timestamp=2026-10-30T14%3A02%3A11.483920517%2B00%3A00&viewability_ms=1000"
    }
  ]
}

No match also returns 200, with an empty ads array:

{
  "message_id": "msg_abc123",
  "ads": []
}

Each object in ads has these fields. Fields typed string or null are sent as null when they have no value; no field is left out.

Errors

Errors from this endpoint have this body:

{
  "error": "content must not be empty"
}

Malformed JSON (400), a wrong Content-Type (415) and a body that does not fit the schema (422) return a plain-text body instead.

No fill is not an error. It returns 200 with "ads": []. See Rate limits for limits across products.

Click URL

Link the ad to click_through_url exactly as returned. The URL has the form https://api.adzen.ai/dea/ai/redirect/<slug> and answers 302 with the advertiser’s landing page. Adzen counts a click only when the viewer goes through this URL.

Impression beacons

Each ad carries two beacon URLs. Fire each one once, from the viewer’s browser, exactly as returned.

The view URL already carries viewability_ms=1000. Do not change it.

• Beacons are GET requests. A beacon returns 204 No Content.
• A beacon with ad_id or message_id removed, or a view beacon without an integer viewability_ms, returns 400 with {"error": "..."}.
• Adzen counts one beacon of each type per message_id and ad_id pair for the same IP address and user agent. A repeat within 5 minutes still returns 204 and counts as invalid.
• Beacon and click URLs return 403 to requests from IP addresses outside the US.

Fire beacons from the viewer’s browser. Adzen validates each beacon against the viewer’s IP address and user agent.

Idempotency and retries

Send the same Idempotency-Key on every retry of a request. Publisher insights counts requests that share an Idempotency-Key once in ad_requests. Each request sent without the header counts as a separate request.

Each retry returns a fresh match. It can return a different ad, or none.

Retry 429 after the Retry-After delay and 5xx with backoff. Do not retry 400, 401, 403, 415 or 422 without changing the request.

Timing

Matching has a deadline of 2.5 seconds. A request that takes longer returns 200 with empty ads.