Core Concepts
Use this page to understand how a Developer request moves through AON. Exact field definitions and enum values remain in the API, SDK, and canonical Protocol sources.
Protocol v1.0
Current integrations use the v1.0 contract with
AON-Protocol-Version: 1.0. Existing SDK integrations should use the
explicit TypeScript or
Python migration guide.
The Developer flow
- Intent captures what the user is asking for and where that request came from.
- Query sends the current intent and only the context declared by Protocol v1.0 to AON.
- Offer returns a structured result that your product can evaluate and present.
- Event optionally preserves outcome and attribution signals after presentation.
The Query API specification and Offer Schema remain authoritative for the current wire contract.
Choose one integration surface
| Surface | Use it when | Continue |
|---|---|---|
| REST API | You want direct HTTP control. | Offer Query |
| SDK | You want typed TypeScript or Python helpers. | SDK Reference |
| MCP | Your account has hosted access for an AI client. | MCP |
Separate Query constraints from supporting references
Category and location references have different responsibilities. They do not create an automatic second request after every Offer Query.
- Category Taxonomy lists ids accepted by current Query category constraints.
- Location Search performs registry lookup and normalization; its ancestry chain is not a Query v1.0 viewer field.
- Location Targeting explains Partner Offer-side geo configuration and the Query boundary.
Go to the source for details
- API Reference for endpoint and field behavior.
- SDK Reference for language-specific types and methods.
- MCP for hosted runtime and tool access.
- Protocol for canonical specifications, schemas, and examples.
- Best Practices for implementation and recovery principles.