Skip to main content

​
Platform Request Schema

​
Overview

AI platform request sent to an AIP operator to initiate an ad auction. This payload uses the UCP (User Context Protocol) structure with nested objects for producer, context, identity, and extensions. Operators transform it into a context_request before distributing to brand agents.

​
UCP Structure

The PlatformRequest follows the UCP specification with the following top-level structure:
FieldTypeDescription
spec_versionstringUCP specification version (e.g., “1.0.0”)
message_idstringUnique identifier for this auction request
timestampstringISO 8601 timestamp when the platform generated the request
producerobjectProducer information (platform/agent that created the request)
contextobjectContext information (language, publisher, placement, device, geography)
identityobjectIdentity information (namespace, value_hash, confidence)
extensionsobjectExtensions containing AIP-specific and other vendor data

​
Producer Object

FieldTypeDescription
agent_idstringIdentifier of the AI platform sending this request
agent_rolestringRole of the agent, typically “publisher”
softwarestringSoftware name (e.g., “chatgpt”)
software_versionstringSoftware version or model identifier (e.g., “4.3-mini”)

​
Context Object

FieldTypeDescription
languagestringUser locale in BCP 47 format (e.g., “en-US”)
publisherstringPublisher identifier (same as producer.agent_id)
placementobjectPlacement information
placement.ad_unitstringPlatform surface type: “conversation”, “chat”, “voice”, etc.
deviceobjectDevice information
device.platformstringDevice platform: “web”, “mobile”, etc.
device.form_factorstringDevice form factor: “mobile”, “desktop”, “tablet”
device.ua_hashstringOptional user agent hash
geographyobjectGeographic information
geography.countrystringUser country code (ISO 3166-1 alpha-2, e.g., “US”)

​
Identity Object

FieldTypeDescription
namespacestringIdentity namespace (e.g., “platform_user”)
value_hashstringAnonymous hashed user ID
confidencenumberConfidence level for identity (0.0 to 1.0)

​
Extensions Object

The extensions object contains vendor-namespaced data. The aip namespace contains AIP-specific fields:

​
AIP Extensions (extensions.aip)

FieldTypeDescription
session_idstringConversation or interaction session ID
turn_indexintegerTurn index in the conversation
query_textstringUser’s raw query text
messagesarrayOptional short conversation history (last N turns)
latency_budget_msintegerOptional latency budget from platform (milliseconds)
cpx_floornumberMinimum CPX (USD) required by the platform

​
Example

{
  "spec_version": "1.0.0",
  "message_id": "req_92fA1",
  "timestamp": "2025-11-14T18:22:00Z",
  "producer": {
    "agent_id": "openai_chat",
    "agent_role": "publisher",
    "software": "chatgpt",
    "software_version": "4.3-mini"
  },
  "context": {
    "language": "en-US",
    "publisher": "openai_chat",
    "placement": {
      "ad_unit": "conversation"
    },
    "device": {
      "platform": "web",
      "form_factor": "desktop",
      "ua_hash": "ua_hash_xyz"
    },
    "geography": {
      "country": "US"
    }
  },
  "identity": {
    "namespace": "platform_user",
    "value_hash": "user_hash_abc123",
    "confidence": 1.0
  },
  "extensions": {
    "aip": {
      "session_id": "sess_001",
      "turn_index": 3,
      "query_text": "best CRM for small teams",
      "messages": [
        { "role": "user", "content": "best CRM tools?" },
        { "role": "assistant", "content": "HubSpot, Zoho, Salesforce…" }
      ],
      "latency_budget_ms": 500,
      "cpx_floor": 0.05
    }
  }
}

​
Validation Rules

  • spec_version must be “1.0.0” for UCP v1.0
  • message_id must be a unique string identifier
  • context.language must match pattern ^[a-z]{2}-[A-Z]{2}$ (BCP 47)
  • context.geography.country must match pattern ^[A-Z]{2}$ (ISO 3166-1 alpha-2)
  • timestamp must be RFC 3339 / ISO 8601 compliant
  • extensions keys must be vendor namespaces (e.g., aip, openai, vectorgrid)
  • identity.confidence must be between 0.0 and 1.0