Your first API call

Send a live Offer Query without registration using the first example below. It needs no API key or Placement ID and earns no attribution or payouts. The Public Test Sandbox is a separate, fixed, non-billable contract check. For attributable traffic, replace plc_YOUR_PLACEMENT_ID in the second example with your own placement id. Both examples send AON-Protocol-Version: 1.0 and read the v1.0 response fields (protocol_version, offers, and any bounded engagement guidance).

Identify attributable requests with the placement id of a placement in a serviceable Application, sent in the X-AON-Placement-Id header. The query identity is a placement, not an API key: a non-empty invalid placement returns INVALID_PLACEMENT, empty or whitespace-only counts as not provided, and with no placement the call is served in anonymous mode through the AON default placement (the response carries extra.identity.mode="anonymous", with no attribution or earnings). Anonymous requests are not idempotently replayed. If you do not have a placement yet, use the anonymous example above, then get your Placement ID.

curl -s -X POST https://api.aon.pro/v1/offers/query \
  -H "Content-Type: application/json" \
  -H "AON-Protocol-Version: 1.0" \
  -d '{
    "intent": {
      "content": [
        { "type": "input_text", "text": "Find travel deals for a weekend trip to Tokyo" }
      ],
      "provenance": "user_expressed"
    },
    "context": {
      "platform": { "name": "api-client", "channel": "api" }
    }
  }' | python3 -m json.tool

curl -s -X POST https://api.aon.pro/v1/offers/query \
  -H "Content-Type: application/json" \
  -H "AON-Protocol-Version: 1.0" \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -d '{
    "intent": {
      "content": [
        { "type": "input_text", "text": "Find travel deals for a weekend trip to Tokyo" }
      ],
      "provenance": "user_expressed"
    },
    "context": {
      "platform": { "name": "api-client", "channel": "api" }
    }
  }' | python3 -m json.tool

What success looks like

The live REST path is complete when an Offer Query with your placement id (or anonymously) returns HTTP 2xx, code=SUCCESS, and data.protocol_version="1.0". An empty offers result or data.empty_reason is still a valid successful response. Sandbox, local mock verification, identity failure, and protocol failure are not live completion.

What to validate

• Request content and context conform to the v1.0 Query contract.
• Response handling consumes canonical v1.0 Offer fields and preserves the tracking destination supplied by the integration contract.
• The placement id is not a secret, so you can call from a server, browser, or app. For identity mechanics, see Authentication.

Get your Placement ID

Review the Offer Query field contract

Local SDK verification

To check client construction without a live endpoint, use SDK setup mock mode. It verifies API shape and error handling only. It does not provide a runtime or production eligibility.

Compatibility — existing integration

Existing integrations may continue to use an explicitly supported compatibility path while they plan migration work. New integrations read the canonical v1.0 response; compatibility behavior is not the current contract.

Resources for AI coding agents

Open /agent.md (raw Markdown) for the current Protocol, Schema, and Examples source links behind the request shape.