PlatformResponse Schema

Overview

PlatformResponse is the operator-generated response returned to the AI platform after auction evaluation. It communicates:

the outcome status of the auction
the winning bid and reserved billing state, if any
the render payload for platform presentation
optional delegation availability for the winning bid
optional tracking hooks for downstream events

All monetary values in PlatformResponse MUST use micros as the only canonical unit. If status is "generated", recommendation MUST be present. If status is "no_match", recommendation MUST be omitted. If status is "error", an error object MUST be present. Creative payloads MUST separate:

advertiser identity
ad assets
advertiser destination URL

Top-Level Fields

Field	Type	Required	Description
`spec_version`	string	Yes	Spec version. MUST be `"1.0"`
`recommendation_id`	string	Yes	Unique identifier for this recommendation
`timestamp`	string	Yes	RFC 3339 timestamp when the response was produced
`status`	string	Yes	Recommendation generation status: `generated`, `no_match`, or `error`
`ttl_ms`	integer	Yes	Response time-to-live in milliseconds
`recommendation`	object	Conditionally	Recommendation payload. Required when `status="generated"`
`delegation`	object	No	Delegation availability surfaced to the platform
`tracking`	object	No	Downstream event tracking hooks
`error`	object	Conditionally	Error payload. Required when `status="error"`
`ext`	object	No	Vendor extensions

`recommendation`

Platform recommendation payload containing format, disclosure, and creative content.

Field	Type	Required	Description
`format`	string	Yes	Render 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

`creative`

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

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
`landing_page_url`	string	Yes	Advertiser-controlled destination URL

`delegation`

Optional delegation availability surfaced to the platform for the winning bid.

Field	Type	Required	Description
`available`	boolean	No	Whether delegated execution is available
`mode`	string	No	Delegation behavior: `optional`, `recommended`, or `required`
`trigger`	string	No	Activation mode: `user_action`, `explicit_consent`, or `operator_initiated`
`cta_text`	string	No	Delegation-specific CTA text

`tracking`

Optional downstream tracking hooks.

Field	Type	Required	Description
`exposure_url`	string	No	Impression tracking endpoint
`followup_exposure_url`	string	No	Follow-up impression tracking endpoint
`click_url`	string	No	Click tracking endpoint
`conversion_url`	string	No	Conversion tracking endpoint
`followup_engagement_url`	string	No	Follow-up engagement tracking endpoint

`error`

Present when status = "error".

Field	Type	Required	Description
`code`	string	Yes	Operator-defined error code
`message`	string	Yes	Human-readable error message

Example

{
  "spec_version": "1.0",
  "recommendation_id": "rec_981",
  "timestamp": "2026-03-26T18:00:02Z",
  "status": "generated",
  "recommendation": {
    "format": "weave",
    "disclosure": "[Ad]",
    "creative": {
      "brand_name": "Nimbus",
      "domain": "nimbus.example.com",
      "headline": "Scale your CRM",
      "description": "Built for founders.",
      "cta_text": "Try for free",
      "follow_up_suggestion": "Ask Nimbus to draft a migration plan for 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"
  },
  "delegation": {
    "available": true,
    "mode": "optional",
    "trigger": "user_action",
    "cta_text": "Continue with Nimbus"
  },
  "tracking": {
    "exposure_url": "https://track.example.com/impression/stk_abcxyz123",
    "followup_exposure_url": "https://track.example.com/follow-up-impression/stk_abcxyz123",
    "click_url": "https://track.example.com/click/stk_abcxyz123",
    "conversion_url": "https://track.example.com/conversion/stk_abcxyz123",
    "followup_engagement_url": "https://track.example.com/follow-up-engagement/stk_abcxyz123"
  },
  "ttl_ms": 60000
}

Validation Rules

All monetary values MUST use micros
ttl_ms MUST be between 1000 and 300000
If status = "generated", recommendation MUST be present
If status = "no_match", recommendation MUST be omitted
If status = "error", error MUST be present
recommendation.creative MUST separate advertiser identity, ad assets, and destination URL

Welcome

Get Started

AI Platforms

Publisher Access Governance (PAG)

Common

Platform Response

PlatformResponse Schema

Overview

Top-Level Fields

`recommendation`

`creative`

`delegation`

`tracking`

`error`

Example

Validation Rules

​PlatformResponse Schema

​Overview

​Top-Level Fields

​recommendation

​creative

​delegation

​tracking

​error

​Example

​Validation Rules

PlatformResponse Schema

Overview

Top-Level Fields

`recommendation`

`creative`

`delegation`

`tracking`

`error`

Example

Validation Rules