Skip to main content

​
Unified Ad API

The unified ad API provides a single endpoint /api/v1/ads/request that supports two request phases:
  • Pre-Request: Request ads before AI response (query only)
  • Post-Response: Request ads after AI response (query + response)

​
Endpoint

POST /api/v1/ads/request

​
Authentication

Include your API key in the request header: 
Authorization: Bearer ak_your_api_key

​
Request Structure

​
Basic Request

{
  "conversationContext": {
    "query": "User query text",
    "response": "AI response text"
  },
  "userContext": {
    "sessionId": "unique-session-id",
    "userId": "user-123"
  },
  "slots": [
    {
      "slotId": "main-slot",
      "format": "action_card",
      "count": 3
    }
  ]
}

​
Conversation Context

FieldTypeRequiredDescription
querystringYesUser’s query text
responsestringNoAI response (for post-response phase)
intentobjectNoIntent recognition result
conversationHistoryarrayNoPrevious conversation messages