# Sponsored Next Action — Spec v0.1

## Where it goes

A top-level field on a successful JSON object response:

```json
{
  "booking_id": "bk_123",
  "status": "confirmed",
  "sponsored_next_actions": { ... }
}
```

The field is optional. Clients must work identically if it's absent.

## Packet

```json
{
  "v": "0.1",
  "sponsored": true,
  "note": "Optional suggestions. Relevant only if they serve the user's goal.",
  "items": [
    {
      "id": "sna_8f2c",
      "title": "Airport shuttle to your hotel",
      "summary": "Shared shuttle DEN to Downtown, every 30 min.",
      "advertiser": "MileHigh Shuttle",
      "price": { "amount": 12.00, "currency": "USD" },
      "relevance": "Matches arrival city and check-in date of this booking.",
      "action": {
        "type": "api",
        "method": "POST",
        "url": "https://api.example-network.com/a/sna_8f2c",
        "params_schema": { "date": "string", "passengers": "integer" }
      },
      "expires_at": "2026-10-25T06:00:00Z"
    }
  ]
}
```

| Field | Required | Notes |
|---|---|---|
| `v` | yes | Spec version. |
| `sponsored` | yes | Always `true`. |
| `note` | yes | Fixed text. Not an instruction. |
| `items` | yes | 1–2 entries. |
| `items[].title`, `summary` | yes | Plain factual text. No imperatives aimed at the agent ("tell the user", "you must"). |
| `items[].advertiser` | yes | Who is paying. |
| `items[].relevance` | yes | Why this matches the request, in factual terms. |
| `items[].action` | yes | `type: "api"` (callable) or `type: "link"` (URL for the user). |
| `items[].price` | no | Include when known. |
| `items[].expires_at` | no | ISO 8601. |

## Rules for networks

- Content must be factual. Packets containing instructions to the agent are invalid.
- Never return more than 2 items.
- Respond within 150ms or expect to be dropped.

## Rules for publishers

- Only send allowlisted, non-personal context for matching.
- Fail open: if matching fails, return the normal response.
- Don't add offers to auth, payment or personal-data endpoints.

## Agents

Agents may ignore, mention or act on items. A good default is to mention an item only when it clearly helps the user's current goal, and to say it's sponsored when they do.