Skip to main content

​
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

FieldTypeRequiredDescription
spec_versionstringYesSpec version. MUST be "1.0"
recommendation_idstringYesUnique identifier for this recommendation
timestampstringYesRFC 3339 timestamp when the response was produced
statusstringYesRecommendation generation status: generated, no_match, or error
ttl_msintegerYesResponse time-to-live in milliseconds
recommendationobjectConditionallyRecommendation payload. Required when status="generated"
delegationobjectNoDelegation availability surfaced to the platform
trackingobjectNoDownstream event tracking hooks
errorobjectConditionallyError payload. Required when status="error"
extobjectNoVendor extensions

​
recommendation

Platform recommendation payload containing format, disclosure, and creative content.
FieldTypeRequiredDescription
formatstringYesRender format: weave, tail, product_card, or bridge
disclosurestringYesDisclosure label such as [Ad] or Sponsored
creativeobjectYesStructured creative payload
offerIdstringNoUnique identifier for the offer being presented

​
creative

Combined creative object containing brand information, ad assets, destination, and click tracking.
FieldTypeRequiredDescription
brand_namestringYesAdvertiser or brand name
domainstringNoOptional advertiser domain
headlinestringYesPrimary ad headline
descriptionstringYesAd description text
cta_textstringYesCall-to-action text
follow_up_suggestionstringNoOptional follow-up suggestion the platform can surface after the initial recommendation
logo_urlstringNoOptional logo asset
image_urlsarrayNoOptional creative image assets
landing_page_urlstringYesAdvertiser-controlled destination URL

​
delegation

Optional delegation availability surfaced to the platform for the winning bid.
FieldTypeRequiredDescription
availablebooleanNoWhether delegated execution is available
modestringNoDelegation behavior: optional, recommended, or required
triggerstringNoActivation mode: user_action, explicit_consent, or operator_initiated
cta_textstringNoDelegation-specific CTA text

​
tracking

Optional downstream tracking hooks.
FieldTypeRequiredDescription
exposure_urlstringNoImpression tracking endpoint
followup_exposure_urlstringNoFollow-up impression tracking endpoint
click_urlstringNoClick tracking endpoint
conversion_urlstringNoConversion tracking endpoint
followup_engagement_urlstringNoFollow-up engagement tracking endpoint

​
error

Present when status = "error".
FieldTypeRequiredDescription
codestringYesOperator-defined error code
messagestringYesHuman-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