> ## Documentation Index
> Fetch the complete documentation index at: https://agenticintentprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Response

> Operator-generated response returned to the AI platform after auction evaluation

# 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

```json theme={null}
{
  "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

***