Ad Serving API (Legacy)

⚠️ DEPRECATED: This API is deprecated in favor of the new SSP Bidding API. While still functional, new integrations should use the SSP API for better performance and industry-standard compatibility. See the Migration Guide for upgrade instructions.

The Ad Serving API provides endpoints for requesting contextual ads and tracking user interactions.

Request Ad

Request a contextual ad based on conversation context.

POST /api/v1/ad-serving/request

Authentication

This endpoint requires API key authentication. Use one of these methods:

Bearer Token (Recommended)

Authorization: Bearer your-api-key

Custom Header

x-api-key: your-api-key

Query Parameter

POST /api/v1/ad-serving/request?api_key=your-api-key

Request Body

{
  "context": {
    "conversation": "I'm looking for ways to improve my team's productivity. We're using Slack but need better project management.",
    "userQuery": "What are some good project management tools for small teams?",
    "metadata": {
      "userAgent": "Mozilla/5.0...",
      "sessionId": "session-123",
      "userId": "user-456"
    }
  },
  "placement": {
    "type": "inline",
    "position": "after_response",
    "dimensions": {
      "width": 300,
      "height": 250
    }
  },
  "preferences": {
    "adFormat": "text",
    "maxAds": 1,
    "categories": ["productivity", "business-tools"],
    "excludeCategories": ["gambling", "adult"]
  }
}

Response

{
  "ads": [
    {
      "id": "ad-789",
      "campaignId": "campaign-123",
      "type": "text",
      "content": {
        "headline": "Transform Your Team's Workflow",
        "description": "Boost productivity by 300% with our AI-powered project management tool. Perfect for small teams!",
        "callToAction": "Start Free Trial",
        "landingUrl": "https://example.com/signup?ref=cue"
      },
      "tracking": {
        "impressionUrl": "https://app.oncue.ad/api/v1/ad-serving/impression/ad-789",
        "clickUrl": "https://app.oncue.ad/api/v1/ad-serving/click/ad-789"
      },
      "metadata": {
        "relevanceScore": 0.92,
        "bidAmount": 2.45,
        "category": "productivity"
      }
    }
  ],
  "requestId": "req-abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

Example

curl -X POST https://app.oncue.ad/api/v1/ad-serving/request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "context": {
      "conversation": "I'\''m looking for ways to improve my team'\''s productivity.",
      "userQuery": "What are some good project management tools for small teams?"
    },
    "placement": {
      "type": "inline",
      "position": "after_response"
    },
    "preferences": {
      "adFormat": "text",
      "maxAds": 1
    }
  }'

const response = await fetch('https://app.oncue.ad/api/v1/ad-serving/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-api-key'
  },
  body: JSON.stringify({
    context: {
      conversation: "I'm looking for ways to improve my team's productivity.",
      userQuery: "What are some good project management tools for small teams?"
    },
    placement: {
      type: 'inline',
      position: 'after_response'
    },
    preferences: {
      adFormat: 'text',
      maxAds: 1
    }
  })
});

const adResponse = await response.json();

Track Ad Click

Track when a user clicks on an ad.

GET /api/v1/ad-serving/click/:adId

Parameters

Parameter	Type	Description
adId	string	The ad ID from the ad response

Query Parameters

Parameter	Type	Description
userId	string	Optional user identifier
sessionId	string	Optional session identifier
timestamp	string	Optional click timestamp (ISO 8601)

Response

{
  "success": true,
  "adId": "ad-789",
  "clickId": "click-xyz456",
  "redirectUrl": "https://example.com/signup?ref=cue&click_id=click-xyz456",
  "timestamp": "2024-01-15T10:35:00Z"
}

Example

curl -X GET "https://app.oncue.ad/api/v1/ad-serving/click/ad-789?userId=user-456&sessionId=session-123"

const response = await fetch('https://app.oncue.ad/api/v1/ad-serving/click/ad-789?userId=user-456&sessionId=session-123');
const clickResponse = await response.json();

// Redirect user to the landing page
window.location.href = clickResponse.redirectUrl;

Track Ad Impression

Track when an ad is shown to a user.

GET /api/v1/ad-serving/impression/:adId

Parameters

Parameter	Type	Description
adId	string	The ad ID from the ad response

Query Parameters

Parameter	Type	Description
userId	string	Optional user identifier
sessionId	string	Optional session identifier
timestamp	string	Optional impression timestamp (ISO 8601)

Response

{
  "success": true,
  "adId": "ad-789",
  "impressionId": "imp-def789",
  "timestamp": "2024-01-15T10:30:00Z"
}

Example

curl -X GET "https://app.oncue.ad/api/v1/ad-serving/impression/ad-789?userId=user-456&sessionId=session-123"

// Track impression when ad is displayed
fetch('https://app.oncue.ad/api/v1/ad-serving/impression/ad-789?userId=user-456&sessionId=session-123');

Request Parameters

Context Object

Field	Type	Description
conversation	string	The full conversation context
userQuery	string	The user's current query or message
metadata	object	Additional metadata about the request

Placement Object

Field	Type	Description
type	string	Ad placement type (inline, sidebar, overlay)
position	string	Position within the placement (before_response, after_response, middle)
dimensions	object	Ad dimensions (width, height)

Preferences Object

Field	Type	Description
adFormat	string	Preferred ad format (text, image, video)
maxAds	number	Maximum number of ads to return (1-5)
categories	array	Preferred ad categories
excludeCategories	array	Categories to exclude

Ad Formats

Text Ads

{
  "type": "text",
  "content": {
    "headline": "Ad Headline",
    "description": "Ad description text",
    "callToAction": "Click Here",
    "landingUrl": "https://example.com"
  }
}

Image Ads

{
  "type": "image",
  "content": {
    "headline": "Ad Headline",
    "description": "Ad description text",
    "imageUrl": "https://example.com/ad-image.jpg",
    "callToAction": "Learn More",
    "landingUrl": "https://example.com"
  }
}

Video Ads

{
  "type": "video",
  "content": {
    "headline": "Ad Headline",
    "description": "Ad description text",
    "videoUrl": "https://example.com/ad-video.mp4",
    "thumbnailUrl": "https://example.com/thumbnail.jpg",
    "callToAction": "Watch Now",
    "landingUrl": "https://example.com"
  }
}

Error Responses

Common error responses for ad serving endpoints:

400 Bad Request

{
  "error": "Invalid request",
  "message": "Context conversation is required",
  "statusCode": 400
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "statusCode": 401
}

404 Not Found

{
  "error": "Not found",
  "message": "Ad not found",
  "statusCode": 404
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later",
  "statusCode": 429
}

503 Service Unavailable

{
  "error": "No ads available",
  "message": "No matching ads found for the given context",
  "statusCode": 503
}

Integration Best Practices

1. Always track impressions when displaying ads to users
2. Use the click tracking endpoint instead of direct links
3. Provide rich context for better ad matching
4. Implement proper error handling for when no ads are available
5. Respect user preferences and privacy settings
6. Cache API keys securely and never expose them in client-side code
7. Monitor API usage to avoid rate limiting

SDK Integration

For easier integration, consider using our official SDKs:

// JavaScript SDK example
import { CueAds } from '@cue/sdk';

const cue = new CueAds({ apiKey: 'your-api-key' });

const ad = await cue.requestAd({
  context: {
    conversation: "User conversation context",
    userQuery: "User's current question"
  },
  placement: { type: 'inline', position: 'after_response' }
});

See the SDK Documentation for more details.