AI API

Match a contextual ad to a turn in an assistant conversation. This is the API behind the AI SDK integrations, and can be called directly.

Endpoint	Auth	Purpose
`POST /v1/ai/process`	`X-API-Key`	Match an ad to a conversation turn
`GET /v1/ai/health`	none	Liveness check

`POST /v1/ai/process`


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

Body


{
  message_id: string        // Your unique id for this assistant message
  content: string           // The text to match against
  conversation_id?: string  // Groups turns in one conversation. Recommended —
                            // it is carried onto impression beacons.
  location?: string         // ISO country/subdivision, e.g. "US-CA"
  prompt?: string           // The user prompt that produced `content`, when
                            // you want matching to consider both sides
}

Example


curl -X POST https://api.adzen.ai/v1/ai/process \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "message_id": "msg_abc123",
    "content": "For a leaking pipe, shut off the main valve first.",
    "conversation_id": "conv_7f3a9b2e",
    "location": "US-WA"
  }'

Response

Each matched ad carries its own impression beacon URLs, already built with the right ids — use them verbatim rather than constructing them:


{
  "ads": [
    {
      "ad_id": 1071,
      "placement": "after_message",
      "render_impression_url": "https://api.adzen.ai/dea/ai/impressions/render?ad_id=1071&message_id=msg_abc123&conversation_id=conv_7f3a9b2e",
      "view_impression_url": "https://api.adzen.ai/dea/ai/impressions/view?ad_id=1071&message_id=msg_abc123&conversation_id=conv_7f3a9b2e"
    }
  ]
}

Impression beacons are served from /dea/ai/impressions/*, not from /v1/ai/impressions/*. Take the URLs from the response as given — a beacon built by hand against the /v1/ai prefix returns 404.

Fire render_impression_url when the ad is rendered, and view_impression_url when it meets your viewability threshold.

Error responses

Status	Meaning
`401`	Missing or invalid API key, or a key issued for a different product
`422`	Body failed validation — a missing required field