Skip to main content

OpenRTB Endpoint Overview

The OpenRTB endpoint is the primary bidding interface for the Affinity AI Bid API, implementing the industry-standard OpenRTB 2.6 protocol with optional Affinity AI extensions for enhanced capabilities.

What is OpenRTB?​

OpenRTB (Open Real-Time Bidding) is a protocol developed by the IAB Tech Lab that standardizes communication between:

  • Supply-Side Platforms (SSPs) / Publishers
  • Demand-Side Platforms (DSPs) / Advertisers
  • Ad Exchanges

Key Benefits​

  • Interoperability: Works with existing ad tech infrastructure
  • Standardization: Common language for bid requests and responses
  • Efficiency: Optimized for low-latency, high-volume transactions
  • Flexibility: Extensible through custom extensions

OpenRTB 2.6 in Affinity AI​

Affinity AI implements OpenRTB 2.6 as the base protocol layer, with optional Affinity AI extensions for enhanced functionality:

┌─────────────────────────────────────┐
│     Affinity AI Extensions (Optional)      │
│  - Context Enhancement              │
│  - AdCP (Ad Context Protocol)       │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│    OpenRTB 2.6 Standard (Required)  │
│  - Bid Request/Response             │
│  - Standard Objects                 │
│  - Core Fields                      │
└─────────────────────────────────────┘

Implementation Approach​

  1. Full Compliance: All required OpenRTB 2.6 fields are supported
  2. Recommended Fields: We encourage use of recommended fields for better targeting
  3. Extensions: Affinity AI-specific enhancements are added via the ext object
  4. Backward Compatibility: Standard OpenRTB clients work without modifications

Endpoint​

POST /openrtb2

Base URL: https://bid-aura.affinity.net

Full URL: https://bid-aura.affinity.net/openrtb2

Core Concepts​

Bid Request​

A bid request is sent from the publisher (SSP) to potential advertisers (DSPs) containing:

  • Impression details: What ad space is available
  • Site/App context: Where the ad will appear
  • User context: Anonymous targeting signals (no PII)
  • Device information: Technical capabilities

Bid Response​

A bid response is returned by advertisers containing:

  • Creative details: What ad content to display
  • Tracking URLs: For impressions, clicks, etc.

Auction​

The ad exchange conducts a real-time auction:

  1. Receives bid request from publisher
  2. Sends to multiple DSPs simultaneously
  3. Collects bid responses
  4. Determines winner (typically highest bid)
  5. Returns winning bid to publisher

Protocol​

The endpoint implements OpenRTB 2.6 (Real-Time Bidding Protocol) as specified by the IAB Tech Lab, with optional Affinity AI extensions for advanced features.

Request/Response Flow​

Key Features​

1. OpenRTB 2.6 Compliance​

Full support for the OpenRTB 2.6 specification:

  • Standard bid request/response format
  • Native impression type
  • IAB content taxonomy
  • Privacy compliance (GDPR, CCPA, GPP)
  • Deal IDs and private marketplace support

View OpenRTB 2.6 protocol details →

2. Optional Affinity AI Extensions​

Enhance capabilities with Affinity AI-specific extensions:

Context Enhancement​

Rich contextual signals for better targeting:

  • Intent analysis
  • Sentiment detection
  • Conversation metadata

Learn more: Context Enhancement

AdCP (Ad Context Protocol)​

Advanced creative assembly and delivery:

  • Format specifications
  • Creative manifests
  • Universal macros
  • Tracking framework

Learn more: AdCP Overview

3. High Performance​

Optimized for low-latency bidding:

  • p50 latency: < 50ms
  • p95 latency: < 100ms
  • p99 latency: < 200ms
  • Throughput: 10,000+ requests/second

View performance details →

Supported Impression Types​

Native​

Native ad units with structured assets:

{
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[...]}}"
      }
    }
  ]
}

View native format details →

Request Requirements​

Required Fields​

Minimum required fields for a valid bid request:

{
  "id": "unique-request-id",
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
      }
    }
  ]
}

View complete required fields →

Additional fields for better targeting and performance:

  • site.domain or app.bundle - Publisher identification
  • site.cat or app.cat - Content categories (IAB taxonomy)
  • device.ua - User agent string
  • device.geo - Geographic location
  • user.id - User identifier (if available)

View complete recommended fields →

Response Handling​

Successful Bid​

{
  "id": "unique-request-id",
  "seatbid": [
    {
      "bid": [
        {
          "id": "bid-001",
          "impid": "imp-1",
          "price": 2.5,
          "adm": "<a href='...'><img src='...'/></a>",
          "nurl": "https://track.example.com/win?price=${AUCTION_PRICE}"
        }
      ]
    }
  ]
}

View response format details →

No Bid​

When no suitable bid is available:

HTTP/1.1 204 No Content

Note: A 204 response is not an error - it simply means no bid was available for this request.

Error Response​

When request validation fails:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid OpenRTB request format",
    "details": {
      "field": "imp[0].native",
      "reason": "missing required field 'request'"
    },
    "request_id": "req-abc123"
  }
}

View error handling guide →

Rate Limits​

ScopeLimitWindow
Global10,000 req/sec1 second
Per Publisher1,000 req/sec1 second
Per IP100 req/sec1 second

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704067200

View rate limiting details →

Privacy & Compliance​

The endpoint supports multiple privacy frameworks:

  • GDPR: EU General Data Protection Regulation
  • CCPA: California Consumer Privacy Act
  • GPP: Global Privacy Platform

Privacy signals are passed through the regs and user objects:

{
  "regs": {
    "ext": {
      "gdpr": 1,
      "us_privacy": "1YNN"
    }
  },
  "user": {
    "ext": {
      "consent": "consent-string"
    }
  }
}

View privacy compliance guide →

Testing​

Test Mode​

Enable test mode to validate requests without affecting production:

{
  "id": "test-request",
  "test": 1,
  "imp": [...]
}

Test mode responses include validation details and do not trigger billing.

Performance Optimization​

Request Size​

Keep requests under 100KB for optimal performance:

  • Minimize unnecessary fields
  • Use compact JSON formatting
  • Avoid large custom extensions

Timeout Configuration​

Set appropriate client timeouts:

  • Connection timeout: 2 seconds
  • Read timeout: 600ms (slightly above service timeout)
  • Total timeout: 3 seconds

Caching​

Cache format definitions and static data:

  • AdCP format definitions (24 hours)
  • IAB category mappings (7 days)
  • Backend capabilities (1 hour)

View performance guide →

Integration Levels​

Publishers can integrate at different levels:

Level 1: Basic OpenRTB​

  • Standard OpenRTB 2.6 implementation
  • No Affinity AI extensions required
  • Works with any DSP

Level 2: With AdCP​

  • Add AdCP format support
  • Enable dynamic creative assembly
  • Better ad quality and relevance

Level 3: With Context Enhancement​

  • Include rich contextual signals
  • Improve targeting accuracy
  • Higher CPMs

Level 4: AI-Native​

  • Full Affinity AI extension support
  • Contextual weaving formats
  • Premium AI search monetization

View Use Cases →

Standards Compliance​

Affinity AI's OpenRTB implementation follows:

  • OpenRTB 2.6 Specification: Full compliance with IAB Tech Lab standard
  • IAB Content Taxonomy: Standard content categorization
  • Privacy Standards: GDPR, CCPA, TCF 2.0 support

Next Steps​

Support​

Need help with the OpenRTB endpoint?

  • 📖 Documentation: Browse our guides
  • 💬 Technical Support: Contact engineering team
  • 🐛 Issues: Report bugs or request features
  • 📧 Email: support@aura.tech