API Reference · Discover

Offers for Contents API

Get relevant offers for web pages, inline text, images, and video with a live Content Assistant placement.

Base URL: https://api.aon.pro · Content API 1.2.0

Authentication

Send X-AON-Placement-Id with the public ID of a live Content Assistant placement from Developer Portal on every request. No API key is required. Anonymous requests and other placement types are not supported. Use https://api.aon.pro or https://plugin.aon.pro, not the documentation site.

Submit content and get offers

Send a web URL, inline text, or an image/video HTTPS URL to POST /v1/content/offers. Set source.type to web, inline, image or video. Set language explicitly; otherwise Accept-Language is used, then en.
HTTP 202 with data.status=pending: wait data.poll_after_ms, then repeat the same POST with unchanged content and language and current viewer context. No task ID, resource ID or Location is needed or returned.
HTTP 200 with data.status=ready: read data.matches. Each match contains an intent, its offers and a nullable video segment. Empty matches or offers are valid results.

Using offers

Video segments use start_ms and end_ms; repeated appearances have separate matches. For other content, or video without known segments, segment is null. Keep each returned offer_instance_id and the entire action together and unchanged.

For server-side calls, supply the viewer's context.user_profile.country and, when available, client.user_agent so matching uses the viewer's context rather than your server's.

Errors and retries

Errors return data:null. For CONTENT_ANALYSIS_FAILED, inspect extra.reason, extra.retryable and extra.retry_at before resubmitting. For HTTP 429, honor Retry-After or extra.retry_after_seconds and use backoff. These are separate from pending-response polling. Keep X-Request-Id for support.

Download OpenAPI JSON

POST/v1/content/offersPlacement ID

Get offers for content

OpenAPI security

Headers

Fields

5·2 required/3 optional

Showing the complete documented schema.

Required or conditional

X-AON-Placement-Idstring

required

Send the public ID of a live Content Assistant placement in X-AON-Placement-Id exactly once on every request. Use 1–64 ASCII letters, digits, underscores or hyphens. A placement_id in the body or query is not used. API keys, anonymous requests and other placement types are not supported.

example: plc_YOUR_PLACEMENT_ID

Content-Typestring

required

JSON request body.

example: application/json

Optional

Accept-Languagestring

optional

Preferred output language when language is omitted; defaults to en.

x-aon-user-pseudo-idstring

optional

Optional pseudonymous viewer ID; not echoed in the response.

Request Body

JSON body. Maximum 2097152 bytes. Omit: force_refresh, resource_id, task_id, pagination.

Fields

26·1 required/25 optional

Showing the complete documented schema.

Required or conditional

sourceobject

required

Exactly one of the source shapes below; never mix their fields.

Optional

languagestring

optional

Desired result language. Send it explicitly and keep it unchanged when repeating a pending request.

object

optional

Current viewer and session context for offer matching.

5 nested fields

object

optional

Application information.

3 nested fields

session_idstring

optional

Pseudonymous session identifier.

minLength: 1maxLength: 256

conversation_idstring | number

optional

Conversation identifier.

object

optional

Recent session context.

2 nested fields

object

optional

Current viewer targeting information.

3 nested fields

object

optional

Current viewer client information. Omit properties: ip.

1 nested field

user_agentstring

optional

Viewer user agent. If omitted, the request's User-Agent header is used. No client IP field is supported. Maximum UTF-8 bytes: 2048.

minLength: 1

object

optional

Optional filters for the returned offers.

4 nested fields

category_idsstring[]

optional

Include these category IDs.

items: string

excluded_category_idsstring[]

optional

Exclude these category IDs.

items: string

offer_typesstring[]

optional

Allowed offer types.

items: string

listing_source_namesstring[]

optional

Allowed listing sources.

items: string

force_offerboolean

optional

Request a fallback recommendation when normal matching finds none.

object

optional

Options for the returned offers.

1 nested field

thinking_modeboolean

optional

Whether offers include match reasons. If omitted, the service default applies.

Source: web

Fields for source.type = web. Omit: contents, media_type.

Fields

3·3 required

Showing the complete documented schema.

object

required

A publicly accessible HTTP or HTTPS web page. Omit properties: contents, media_type.

2 nested fields

typestring

required

Content type: web, inline, image or video.

Allowed valuesweb

uristring

required

HTTP or HTTPS URL of the page, including any required query parameters. Maximum UTF-8 bytes: 8192.

Source: inline

Fields for source.type = inline. Omit: media_type.

Fields

6·6 required

Showing the complete documented schema.

object

required

Plain text supplied directly. The application URI identifies the text and is not fetched. Omit properties: media_type.

4 nested fields

typestring

required

Content type: web, inline, image or video.

Allowed valuesinline

uristring

required

Application URI, such as myapp://articles/123. This address is not fetched. Maximum UTF-8 bytes: 4096.

contentsobject[]

required

Original text entries in order. At least one nonblank entry is required. Keep the text and entry boundaries unchanged when repeating a pending request. Minimum items: 1. Maximum items: 32. Maximum decoded UTF-8 bytes: 262144.

items: object

object

optional

Nested object container for the fields below.

2 nested fields

Source: image

Fields for source.type = image. Omit: contents, media_type.

Fields

3·3 required

Showing the complete documented schema.

object

required

An image or video at an HTTPS URL. Set source.type to image or video; do not send media_type. Omit properties: contents, media_type.

2 nested fields

typestring

required

Content type: web, inline, image or video.

Allowed valuesimage

uristring

required

HTTPS URL of the image or video. Do not include credentials, control characters or surrounding whitespace.

maxLength: 2000

Source: video

Fields for source.type = video. Omit: contents, media_type.

Fields

3·3 required

Showing the complete documented schema.

object

required

An image or video at an HTTPS URL. Set source.type to image or video; do not send media_type. Omit properties: contents, media_type.

2 nested fields

typestring

required

Content type: web, inline, image or video.

Allowed valuesvideo

uristring

required

HTTPS URL of the image or video. Do not include credentials, control characters or surrounding whitespace.

maxLength: 2000

Request Examples

web

curl

curl -X POST 'https://api.aon.pro/v1/content/offers' \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "type": "web",
    "uri": "https://publisher.example/article"
  },
  "language": "en",
  "context": {
    "user_profile": {
      "country": "US"
    }
  },
  "client": {
    "user_agent": "PublisherApp/1.0"
  }
}'

inline

curl

curl -X POST 'https://api.aon.pro/v1/content/offers' \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "type": "inline",
    "uri": "myapp://articles/123",
    "contents": [
      {
        "type": "text",
        "text": "Original article text."
      }
    ]
  },
  "language": "en"
}'

image

curl

curl -X POST 'https://api.aon.pro/v1/content/offers' \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "type": "image",
    "uri": "https://cdn.example.com/a.jpg"
  },
  "language": "en"
}'

video

curl

curl -X POST 'https://api.aon.pro/v1/content/offers' \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "type": "video",
    "uri": "https://cdn.example.com/a.mp4"
  },
  "language": "en"
}'

HTTP 200: ready matches. HTTP 202: pending; wait poll_after_ms and repeat POST with the same content and language. Error responses have data:null.

Fields

33·26 required/2 conditional/5 optional

Showing the complete documented schema.

codestring

required

Response code. SUCCESS does not mean offers are ready; inspect data.status. Machine-readable error code.

Allowed valuesSUCCESSINVALID_JSONUNSUPPORTED_MEDIA_TYPEVALIDATION_ERRORPAYLOAD_TOO_LARGEPLACEMENT_REJECTEDRESULT_REVOKEDNOT_FOUNDAPI_NOT_FOUNDMETHOD_NOT_ALLOWEDRESULT_EXPIREDRATE_LIMITEDSERVICE_UNAVAILABLEINTERNAL_ERRORCONTENT_ANALYSIS_FAILEDOFFER_QUERY_TIMEOUTRESULT_TOO_LARGE

messagestring

required

Human-readable explanation. Use code and data.status for application logic.

object | null

required

Ready matches or a pending status.

5 nested fieldsnullable: true

statusstring

required

ready when matching is complete. pending while the content is being prepared.

Allowed valuesreadypending

source_typestring

required when status = ready

The submitted source.type.

Allowed valueswebinlineimagevideo

matchesobject[]

required when status = ready

Each entry pairs an intent and its offers with an optional video segment. Empty when no intents are found.

items: object

object

optional

Nested object container for the fields below.

4 nested fields

poll_after_msinteger | null

required

Milliseconds to wait before repeating POST with the same content and language and current viewer context. Use each response's value.

nullable: trueminimum: 1

object

required

Additional response information.

4 nested fields

retry_after_secondsinteger

optional

Seconds to wait before retrying a rate-limited request.

Allowed values60

reasonstring

optional

Reason the content could not be processed.

retryableboolean

optional

Whether submitting again later may succeed.

retry_atstring | null

optional

Earliest time to submit again, if provided. Not a pending-response polling interval.

format: date-timenullable: true

Response Examples

HTTP 200: ready

JSON

{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "status": "ready",
    "source_type": "video",
    "matches": [
      {
        "segment": {
          "start_ms": 12000,
          "end_ms": 18500
        },
        "intent": "Wireless noise-cancelling headphones",
        "offers": [
          {
            "offer_id": "019ad760-1234-7000-8000-000000000101",
            "offer_instance_id": "019ad760-1234-7000-8000-000000000102",
            "version": "3.0",
            "content_language": "en",
            "offer_info": {
              "title": "Wireless noise-cancelling headphones",
              "description": "Comfortable over-ear headphones for travel and everyday listening.",
              "category": {
                "id": "others"
              },
              "commercial": {
                "price": {
                  "amount": "79.99",
                  "currency": "USD"
                }
              }
            },
            "entity": {
              "id": "example-merchant",
              "name": "Example Audio Store"
            },
            "action": {
              "type": "link",
              "payload": {
                "url": "https://track.example/offers/headphones?offer_instance_id=019ad760-1234-7000-8000-000000000102"
              }
            }
          }
        ]
      }
    ],
    "poll_after_ms": null
  },
  "extra": {}
}

HTTP 202: pending

JSON

{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "status": "pending",
    "poll_after_ms": 2000
  },
  "extra": {}
}

Errors and failure modes

Error Responses

Contract note: 429 / 500 are HTTP status values returned by the response status, not fields in the JSON response body. The response body remains the envelope { code, message, data, extra }.

HTTP 429: RATE_LIMITED

body.code = RATE_LIMITED

Response body

JSON

{
  "code": "RATE_LIMITED",
  "message": "Content request capacity is exhausted",
  "data": null,
  "extra": {
    "retry_after_seconds": 60
  }
}

HTTP 500: SERVICE_UNAVAILABLE

body.code = SERVICE_UNAVAILABLE

Response body

JSON

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Offer service is temporarily unavailable",
  "data": null,
  "extra": {}
}

{
  "code": "RATE_LIMITED",
  "message": "Content request capacity is exhausted",
  "data": null,
  "extra": {
    "retry_after_seconds": 60
  }
}

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Offer service is temporarily unavailable",
  "data": null,
  "extra": {}
}

Behavior, compatibility, and source notes

Submit content and current viewer context. HTTP 202 means pending: wait poll_after_ms and repeat this POST with the same source and language. HTTP 200 means ready, including empty matches or offers. Available matches may be returned even when some matching attempts fail; results do not promise exhaustive inventory or stable ranking. Keep each offer_instance_id and action unchanged. The response is limited to 2 MiB; oversized results return RESULT_TOO_LARGE, not truncated offers.

HTTP 202: data.status is pending. Wait data.poll_after_ms, then repeat POST with the same content and language and current viewer context. No Location or task ID is returned.

Implementation checklist · 3 items

Create a live Content Assistant placement in Developer Portal and send its X-AON-Placement-Id on every request; other placement types and anonymous requests are not supported.
For HTTP 202, wait data.poll_after_ms, then repeat POST with the same content and language and current viewer context.
Keep each returned offer_instance_id and action unchanged for attribution.

Content Assistant

Set up a Content Assistant placement before using the Offers for Contents API.

Offers for Contents API

Authentication

Submit content and get offers

Using offers

Errors and retries

Operations

Related links