Skip to main content

API Overview

Cue's RESTful API enables you to integrate contextual advertising into your conversational applications. The API provides endpoints for managing campaigns, serving ads, and tracking performance.

API Versions​

Cue offers two API approaches:

Modern two-phase bidding system designed for Supply-Side Platforms and real-time advertising auctions. Features fast bidding (<1000ms>) and flexible ad serving.

Legacy API (Deprecated)​

Traditional single-phase ad serving. Still functional but will be deprecated in favor of SSP API.

Base URL​

All API requests should be made to:

https://app.oncue.ad/api/v1

For development and testing, you can use:

http://localhost:3001/api/v1

Authentication​

Cue uses two authentication methods depending on the endpoint:

1. User Authentication (Dashboard API)​

For dashboard operations (managing campaigns, API keys), use the temporary user ID header:

x-user-id: your-user-id

2. API Key Authentication (Ad Serving)​

For ad serving endpoints, use one of these methods:

Authorization: Bearer your-api-key

Custom Header​

x-api-key: your-api-key

Query Parameter​

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

Content Type​

All requests that send data must include the JSON content type header:

Content-Type: application/json

Rate Limiting​

API requests are rate-limited to ensure fair usage:

  • Dashboard API: 100 requests per minute per user
  • Ad Serving API (Legacy): 1,000 requests per minute per API key
  • SSP API: 15 requests per second per API key

Error Handling​

The API returns standard HTTP status codes and JSON error responses:

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or expired",
  "statusCode": 401
}

Common status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Internal Server Error

API Endpoints​

Authentication​

Campaigns​

Ad Serving​

  • SSP Bidding - Real-time bidding for conversational ads (Recommended)
  • Ad Serving - Legacy ad serving endpoint (Deprecated)

SDK Support​

Official SDKs are available for:

  • JavaScript/TypeScript
  • Python
  • Go
  • Java

See the SDK Documentation for installation and usage instructions.

Support​

For API support, please:

  • Check the documentation for common issues
  • Review the error messages and status codes
  • Contact support at support@oncue.ad