AON Quick Start

Run one bounded Offer Query, then choose the HTTP, SDK, or provisioned Hosted MCP path that fits your product. The current public contract remains the source of truth for every path.

Protocol v1.0 · Updated September 2, 2026

Run the Public Test Sandbox

No application identity is required. The Sandbox returns a fixed, non-billable Query response.

Before live traffic

Four terms you will see next

Learn these after the Sandbox, when you are ready to configure your own integration.

Application: Your live integration in Developer Portal. A serviceable Application owns the placements your integration uses.
Placement: Where offers appear in your product. Each placement has a placement id that identifies your live traffic.
Placement ID: The plc_… id you send in the X-AON-Placement-Id header on every live Offer Query and MCP call. It is not a secret.
Offer: The structured result returned by an AON Query for your product to evaluate and display.

Developer implementation path

REST and SDK are the standard implementation paths after the Sandbox. Choose Hosted MCP when your product connects through an MCP client.

For an MCP client, open Hosted MCP Connection Setup and configure your placement id as the X-AON-Placement-Id header (attribution and earnings), or try /v1/mcp anonymously with no placement (no key, no earnings). The aon_submit_feedback and aon_manage_watch write tools require that placement header; no Hosted MCP tool needs an API key.

Developer integration

Choose one implementation route

Start with HTTP or an SDK, or connect an MCP client. Every route is identified by your placement id; without one, Offer Query and MCP search run in anonymous mode (no earnings), and none of them needs an API key.

HTTP

Build with HTTP

Use the HTTP API when your service needs direct control over requests and responses.

Read the first API call

SDK

Build with an SDK

Use the TypeScript client library when it fits your application.

Set up an SDK

Hosted MCP

MCP connection setup

Connect an MCP client to /v1/mcp with your placement id in the X-AON-Placement-Id header to earn attribution, or try it without a placement in anonymous mode (no earnings); no tool needs an API key or provisioned access, and the write tools require the placement header. It is not part of the default Developer flow.

Open Connection Setup

Each guide covers the setup, placement identity, and next step for a developer implementation path.

Local checks are not live access

The public contract and local SDK mock verification validate integration shape. They do not by themselves provision account access or production availability.

Sandbox completion is not production completion

The Sandbox completes one bounded Query and contract check only. Continue with REST, an SDK, or MCP for your own integration, identified by your placement id; without one, queries are served anonymously and earn no attribution.

Implementation requirements

Use Node.js 20+ for the documented SDK baselines. Use the API Reference and SDK Reference for implementation details; access requirements live with the service and account setup for each path.

Resources for AI coding agents

Open /agent.md (raw Markdown) when an AI coding agent needs the current Protocol, Schema, and Examples source links behind these guides.