Bid Schema

Overview

A Bid is the payload a Brand Agent returns for a ContextRequest. It declares:

bid identity and versioning
where the bid applies (targeting)
how the agent wants to be paid (pricing)
how much it is willing to spend (budget)
what the platform may render (recommendation)
how relevant it believes the bid is (declared_relevance)
whether it can handle delegated execution (delegation)

Top-Level Fields

Field	Type	Required	Description
`spec_version`	string	Yes	Spec version. MUST be `"1.0"`
`bid_id`	string	Yes	Unique identifier for this bid
`brand_agent_id`	string	Yes	Identifier of the Brand Agent placing the bid
`context_id`	string	Yes	ID of the ContextRequest being bid on
`wallet_id`	string	Yes	Wallet to debit if the bid wins
`targeting`	object	Yes	Brand-declared applicability constraints
`pricing`	object	Yes	Billing model and per-event prices in micros
`budget`	object	Yes	Spend caps and pacing controls
`recommendation`	object	Yes	Creative input to render if the bid wins
`declared_relevance`	number	Yes	Brand-declared relevance score (`0.0`-`1.0`)
`supported_opportunities`	array	Yes	Opportunity types this bid supports
`preferred_format`	string	Yes	Preferred creative format
`valid_until`	string	Yes	RFC 3339 expiry timestamp for the bid
`timestamp`	string	Yes	RFC 3339 creation timestamp for the bid
`delegation`	object	No	Delegation capability declaration
`processing_latency_ms`	integer	No	End-to-end bid response latency in milliseconds
`metadata`	object	No	Optional vendor-namespaced metadata

`targeting`

Defines when the bid should be considered applicable.

Field	Type	Required	Description
`intent_types`	array	Yes	Supported intent types such as `commercial` or `transactional`
`decision_phases`	array	Yes	Supported phases from the canonical taxonomy such as `awareness`, `consideration`, `decision`, or `action`
`verticals`	array	No	Normalized topical verticals such as `crm`
`countries`	array	No	ISO 3166-1 alpha-2 country codes
`locales`	array	No	BCP 47 locales such as `en-US`

Valid intent_types: commercial, transactional, informational, navigational, support, unsafe, unknown Valid decision_phases: awareness, research, consideration, decision, action, post_purchase, support

`pricing`

All pricing values use micros of the declared currency. 1 USD = 1,000,000 micros

Field	Type	Required	Description
`currency`	string	Yes	ISO 4217 currency code
`cpx_micros`	integer	No	Price per exposure in micros
`cpc_micros`	integer	No	Price per click in micros
`cpe_micros`	integer	No	Price per delegated-session engagement in micros
`cpa_micros`	integer	No	Price per acquisition / verified outcome in micros
`preferred_pricing_model`	string	No	Preferred billing model: `CPX`, `CPC`, `CPE`, or `CPA`

At least one of cpx_micros, cpc_micros, cpe_micros, or cpa_micros MUST be present.

`budget`

Budget controls declared by the Brand Agent.

Field	Type	Required	Description
`max_bid_per_event_micros`	integer	Yes	Maximum spend allowed for a single billable event
`daily_cap_micros`	integer	Yes	Maximum spend allowed for the current day
`remaining_budget_micros`	integer	Yes	Remaining available budget when the bid is created
`pacing_mode`	string	Yes	Budget pacing strategy: `even`, `accelerated`, or `manual`

`recommendation`

Platform render instructions for the winning recommendation.

Field	Type	Required	Description
`format`	string	Yes	Creative format: `weave`, `tail`, `product_card`, or `bridge`
`disclosure`	string	Yes	Disclosure label such as `[Ad]` or `Sponsored`
`creative`	object	Yes	Structured creative payload
`offerId`	string	No	Unique identifier for the offer being presented

`recommendation.creative`

Combined creative object containing brand information, ad assets, and destination.

Field	Type	Required	Description
`brand_name`	string	Yes	Advertiser or brand name
`domain`	string	No	Optional advertiser domain
`headline`	string	Yes	Primary ad headline
`description`	string	Yes	Ad description text
`cta_text`	string	Yes	Call-to-action text
`follow_up_suggestion`	string	No	Optional follow-up suggestion the platform can surface after the initial recommendation
`logo_url`	string	No	Optional logo asset
`image_urls`	array	No	Optional creative image assets for creative
`landing_page_url`	string	Yes	Advertiser-controlled destination URL

`supported_opportunities`

Array of opportunity types this bid is intended to serve. Allowed values:

soft_recommendation
comparison_slot
decision_moment
transaction_trigger

`delegation`

Optional block for Brand Agents that can take over task execution after explicit user consent.

Field	Type	Required	Description
`supported`	boolean	Yes	Whether delegation is supported
`consent_required`	boolean	Yes, when supported	Whether explicit user consent is required
`supported_for_intents`	object	Yes, when supported	Intent types and decision phases where delegation is allowed
`required_scopes`	array	Yes, when supported	Context scopes required for the operator-mediated session-init payload before session start
`protocol`	object	Yes, when supported	Delegation protocol descriptor
`mcp`	object	Yes, when supported	MCP session bootstrap details
`session_constraints`	object	Yes, when supported	Session timeout and turn limits

`delegation.required_scopes`

These scopes apply to the operator-mediated handoff payload used to start the delegated session. They do not grant unlimited access to upstream conversation history or automatically extend to new information the user provides later during the delegated session. Allowed values:

intent
constraints
selection_context
conversation_summary

In v1.0, new information collected from the user during the live delegated session is session-bound by default unless separately consented.

`delegation.protocol`

In v1.0, the standardized protocol type is mcp.

`delegation.mcp`

Field	Type	Required	Description
`server_url`	string	Yes	MCP server URL
`tool_name`	string	Yes	MCP tool used to start the delegated session
`session_init_schema_ref`	string	Yes	URI of the session initialization schema

`delegation.session_constraints`

Field	Type	Required	Description
`multi_turn`	boolean	Yes	Whether the session supports multiple turns
`session_timeout_seconds`	integer	Yes	Inactivity timeout in seconds after `delegation_started`; the Operator expires the delegated session if no verified session activity arrives before this window elapses
`max_turns`	integer	Yes	Maximum turn count allowed

In v1.0, delegated session liveness is tracked from verified delegation_activity events sent by the Platform or Brand Agent. Each verified activity event resets the inactivity timer. If the timer elapses with no activity, the Operator marks the delegated session expired and records delegation_expired.

Example

{
  "spec_version": "1.0",
  "bid_id": "bid_7823",
  "brand_agent_id": "brand_agent_123",
  "context_id": "ctx_92f",
  "wallet_id": "wallet_890",
  "targeting": {
    "intent_types": ["commercial", "transactional"],
    "decision_phases": ["consideration", "decision"],
    "verticals": ["crm", "sales_software"],
    "countries": ["US"],
    "locales": ["en-US"]
  },
  "pricing": {
    "currency": "USD",
    "cpx_micros": 50000,
    "cpc_micros": 450000,
    "cpe_micros": 700000,
    "cpa_micros": 10000000,
    "preferred_pricing_model": "CPA"
  },
  "budget": {
    "max_bid_per_event_micros": 10000000,
    "daily_cap_micros": 50000000,
    "remaining_budget_micros": 32000000,
    "pacing_mode": "even"
  },
  "recommendation": {
    "format": "weave",
    "disclosure": "[Ad]",
    "creative": {
      "brand_name": "Nimbus",
      "domain": "nimbus.example.com",
      "headline": "Scale your CRM with AI",
      "description": "Nimbus CRM Pro helps growing teams automate their sales pipeline with AI-powered insights and collaborative forecasting.",
      "cta_text": "Start Free Trial",
      "follow_up_suggestion": "Get a migration checklist tailored to your current CRM.",
      "logo_url": "https://cdn.example.com/nimbus/logo.png",
      "image_urls": ["https://cdn.example.com/nimbus/crm.png"],
      "landing_page_url": "https://nimbus.example.com/signup"
    },
    "offerId": "offer_12345"
  },
  "declared_relevance": 0.87,
  "supported_opportunities": ["comparison_slot", "decision_moment", "transaction_trigger"],
  "preferred_format": "weave",
  "delegation": {
    "supported": true,
    "consent_required": true,
    "supported_for_intents": {
      "intent_types": ["transactional", "commercial"],
      "decision_phases": ["decision", "post_purchase"]
    },
    "required_scopes": ["intent", "constraints"],
    "protocol": {
      "type": "mcp",
      "version": "1.0"
    },
    "mcp": {
      "server_url": "https://agent.nimbus.example.com/mcp",
      "tool_name": "start_crm_signup_session",
      "session_init_schema_ref": "https://agent.nimbus.example.com/schemas/session-init.json"
    },
    "session_constraints": {
      "multi_turn": true,
      "session_timeout_seconds": 900,
      "max_turns": 25
    }
  },
  "processing_latency_ms": 42,
  "valid_until": "2026-03-26T18:00:10Z",
  "timestamp": "2026-03-26T18:00:01Z"
}

Validation Rules

spec_version MUST equal "1.0"
At least one of cpx_micros, cpc_micros, or cpa_micros MUST be present
declared_relevance MUST be between 0.0 and 1.0
currency MUST be a valid ISO 4217 code
countries MUST use ISO 3166-1 alpha-2 codes
valid_until and timestamp MUST be RFC 3339 timestamps
If delegation.supported is true, the rest of the delegation fields become required

Welcome

Get Started

AI Platforms

Publisher Access Governance (PAG)

Common

Bid

Bid Schema

Overview

Top-Level Fields

`targeting`

`pricing`

`budget`

`recommendation`

`recommendation.creative`

`supported_opportunities`

`delegation`

`delegation.required_scopes`

`delegation.protocol`

`delegation.mcp`

`delegation.session_constraints`

Example

Validation Rules

Welcome

Get Started

AI Platforms

Publisher Access Governance (PAG)

Common

​Bid Schema

​Overview

​Top-Level Fields

​targeting

​pricing

​budget

​recommendation

​recommendation.creative

​supported_opportunities

​delegation

​delegation.required_scopes

​delegation.protocol

​delegation.mcp

​delegation.session_constraints

​Example

​Validation Rules

Bid Schema

Overview

Top-Level Fields

`targeting`

`pricing`

`budget`

`recommendation`

`recommendation.creative`

`supported_opportunities`

`delegation`

`delegation.required_scopes`

`delegation.protocol`

`delegation.mcp`

`delegation.session_constraints`

Example

Validation Rules