Skip to main content

​
Bid Schema

​
Overview

Brand Agent bid submitted in response to a ContextRequest. Includes pricing for CPX/CPC/CPA in micros format (with cents and dollars for display), structured recommendation metadata, and relevance scoring.

​
Required Fields

FieldTypeDescription
bid_idstringUnique identifier for this bid
brand_agent_idstringIdentifier of the Brand Agent placing the bid
context_idstringID of the ContextRequest being bid on
wallet_idstringWallet to debit if the bid wins
pricingobjectPricing vector with micros (authoritative), cents (display), and dollars (UI)
recommendationobjectRecommendation metadata + creative input
timestampstringISO 8601 timestamp for the bid
relevancenumberRelevance score for this bid (0.0-1.0). Required field used by operator for bid ranking

​
Pricing Object

Pricing uses USD micros as the authoritative format (1 USD = 1,000,000 micros), with cents and dollars provided for brand-friendly display.
FieldTypeRequiredDescription
currencystringYesISO 4217 currency code (default USD)
display_currencystringYesDisplay currency code (default USD)
cpx_microsintegerNoPrice per exposure in USD micros (authoritative)
cpx_centsintegerNoPrice per exposure in cents (for display, derived from micros)
cpx_dollarsnumberNoPrice per exposure in dollars (for UI, derived from micros)
cpc_microsintegerNoPrice per click in USD micros (authoritative)
cpc_centsintegerNoPrice per click in cents (for display, derived from micros)
cpc_dollarsnumberNoPrice per click in dollars (for UI, derived from micros)
cpa_microsintegerNoPrice per conversion in USD micros (authoritative)
cpa_centsintegerNoPrice per conversion in cents (for display, derived from micros)
cpa_dollarsnumberNoPrice per conversion in dollars (for UI, derived from micros)
preferred_pricing_modelstringNoPreferred pricing model: “CPX”, “CPC”, or “CPA”
Note: At least one of cpx_micros, cpc_micros, or cpa_micros must be provided. The operator uses micros values for all calculations. Cents and dollars are provided for brand-friendly display and UI rendering.

​
Recommendation Object

Contains creative_input, the unified creative input structure shared with the operator.
FieldTypeRequiredDescription
creative_inputobjectYesUnified creative input structure
The creative_input object contains:
  • brand_name: Brand or advertiser name
  • product_name: Product or offer name
  • short_description: 1-2 sentence summary (max 200 chars)
  • long_description: 2-4 sentence expanded description (max 500 chars)
  • value_props: Short value propositions or bullet points
  • context_snippet: 60-100 character contextual hint for weave format
  • cta_label: Call-to-action label
  • cta_url: Call-to-action URL
  • assets: Creative assets (logo, images, resource URLs)

​
Optional Fields

FieldTypeDescription
preferred_formatstringPreferred creative format: “weave”, “tail”, “product_card”, or “bridge”
processing_latency_msintegerRound-trip latency from auction request receipt to bid submission (milliseconds)

​
Example

{
  "bid_id": "bid_7823",
  "brand_agent_id": "brand_agent_123",
  "context_id": "ctx_92f",
  "wallet_id": "wallet_890",
  "pricing": {
    "currency": "USD",
    "display_currency": "USD",
    "cpx_micros": 50000,
    "cpx_cents": 5,
    "cpx_dollars": 0.05,
    "cpc_micros": 450000,
    "cpc_cents": 45,
    "cpc_dollars": 0.45,
    "cpa_micros": 10000000,
    "cpa_cents": 1000,
    "cpa_dollars": 10.0,
    "preferred_pricing_model": "CPA"
  },
  "recommendation": {
    "creative_input": {
      "brand_name": "Nimbus",
      "product_name": "Nimbus CRM Pro",
      "short_description": "CRM built for growing teams, with AI-assisted workflows.",
      "long_description": "Nimbus CRM Pro is designed for teams of 5-50 people who need intelligent pipeline management.",
      "value_props": [
        "Automated pipeline insights",
        "Collaborative forecasting"
      ],
      "context_snippet": "For startups needing higher limits and automated expense workflows.",
      "cta_label": "Start Free Trial",
      "cta_url": "https://nimbus.example.com/signup",
      "assets": {
        "logo_url": "https://cdn.example.com/nimbus/logo.png",
        "image_urls": ["https://cdn.example.com/nimbus/crm.png"],
        "resource_urls": ["https://nimbus.example.com/signup"]
      }
    }
  },
  "timestamp": "2025-11-11T18:00:01Z",
  "relevance": 0.87,
  "preferred_format": "weave",
  "processing_latency_ms": 42
}

​
Validation Rules

  • At least one of cpx_micros, cpc_micros, or cpa_micros must be provided
  • relevance must be between 0.0 and 1.0
  • currency and display_currency must be valid ISO 4217 codes
  • Arrays in creative_input must contain at least one entry where required
  • resource_urls and image_urls must be valid URIs
  • timestamp must be ISO 8601 / RFC 3339 formatted
  • Micros values are authoritative; cents and dollars are derived for display

​
Pricing Format Migration

Old format (deprecated):
  • Used string-based pricing: "cpx": "0.05", "cpc": "0.45", "cpa": "10.00"
New format (current):
  • Uses integer micros (authoritative): cpx_micros: 50000, cpc_micros: 450000, cpa_micros: 10000000
  • Includes cents and dollars for display: cpx_cents: 5, cpx_dollars: 0.05
  • Conversion: 1 USD = 1,000,000 micros = 100 cents