AIARCO
Get API Key
Integration

REST API

Complete guide to the AIARCO Offers REST API. Authentication, request parameters, response schema, and server-side examples.

Fetch contextually matched ads from any server-side environment using HTTP requests.

Authentication

Every request must include your channel API key in the X-AIARCO-API-Key header:

X-AIARCO-API-Key: aiarco_YOUR_CHANNEL_KEY

Get your API key from publishers.ads.aiarco.com → Channels → copy the key.

Base URL

https://ads-api.aiarco.com

Endpoints

POST /api/v1/offers

The primary endpoint. Accepts a JSON body with the user's query, context, and optional typed signals for improved targeting.

Request Body

FieldTypeDefaultDescription
querystring""User's search query or intent text. Primary matching field.
contextstring""Page context or category (e.g. "shopping", "technology").
placementstring"sponsored_result"Ad placement type.
user_idstring""Stable user identifier (hash, not PII). Used for frequency capping.
session_idstring""Session identifier for continuity across requests.
localestring"en"User locale (e.g. "en", "fr", "de").
devicestring"desktop"Device type: "desktop", "mobile", or "tablet".
geostring""ISO 3166-1 alpha-2 country code (e.g. "US", "AU").
limitinteger1Number of ads to return (1–8).
signalsSignal[]?nullTyped intent/context signals. See Signal Collection.

Example Request

curl -X POST https://ads-api.aiarco.com/api/v1/offers \
  -H "Content-Type: application/json" \
  -H "X-AIARCO-API-Key: aiarco_YOUR_KEY" \
  -d '{
    "query": "best noise cancelling headphones 2025",
    "context": "electronics",
    "device": "mobile",
    "geo": "US",
    "limit": 3,
    "user_id": "usr_abc123",
    "session_id": "sess_xyz789"
  }'

Response

{
  "offers": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Sony WH-1000XM5 Wireless Headphones",
      "content": "Industry-leading noise cancelling with 30-hour battery life.",
      "cta": "Shop Now",
      "clickUrl": "https://ads-api.aiarco.com/api/v1/clicks/a1b2c3d4-...",
      "source": "aiarco",
      "ad_type": "sponsored_result",
      "brand": {
        "name": "Sony",
        "url": "https://sony.com",
        "iconUrl": "https://example.com/sony-icon.png"
      },
      "product": {
        "title": "WH-1000XM5",
        "category": "Electronics > Headphones"
      },
      "price": {
        "amount": 348.0,
        "currency": "USD",
        "originalPrice": 399.99,
        "discount": 13
      },
      "rating": {
        "value": 5,
        "scale": 5,
        "count": 12483
      }
    }
  ]
}

Do not cache offer responses. Each response creates unique impression records. Caching breaks tracking and revenue attribution.

GET /api/v1/offers

Same as POST but accepts parameters as query strings. Useful for simple integrations or testing.

GET /api/v1/offers?query=running+shoes&context=shopping&limit=2&geo=US
X-AIARCO-API-Key: aiarco_YOUR_KEY

Inline Signals

You can send typed intent signals directly in the offers request for improved targeting. This is equivalent to calling POST /api/v1/signals separately but saves an extra round-trip.

{
  "query": "noise cancelling headphones under $300",
  "context": "electronics",
  "user_id": "usr_abc123",
  "signals": [
    {
      "category": "purchase_intent",
      "confidence": 0.9,
      "subject": "noise cancelling headphones",
      "attributes": { "budget": "under $300" }
    },
    {
      "category": "price_sensitivity",
      "confidence": 0.8,
      "subject": "headphones",
      "iab": {
        "type": "content",
        "version": "2.2",
        "ids": ["607"]
      }
    }
  ]
}

Server-Side Examples

Python

import requests
 
response = requests.post(
    "https://ads-api.aiarco.com/api/v1/offers",
    headers={
        "Content-Type": "application/json",
        "X-AIARCO-API-Key": "aiarco_YOUR_KEY",
    },
    json={
        "query": user_query,
        "context": page_context,
        "limit": 2,
        "user_id": hashed_user_id,
    },
)
 
offers = response.json().get("offers", [])
for offer in offers:
    print(f"{offer['title']} — {offer['clickUrl']}")

Node.js

const response = await fetch("https://ads-api.aiarco.com/api/v1/offers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-AIARCO-API-Key": "aiarco_YOUR_KEY",
  },
  body: JSON.stringify({
    query: userQuery,
    context: pageContext,
    limit: 2,
    user_id: hashedUserId,
  }),
});
 
const { offers } = await response.json();
offers.forEach((offer) => {
  console.log(`${offer.title} — ${offer.clickUrl}`);
});

Response Headers

All offer responses include Cache-Control: no-store. Respect this header — do not cache offer responses at any layer (CDN, browser, or application).

Need to integrate with an LLM?

Use Woven Offers to inject ads directly into LLM system prompts for AI-native monetization.

← OffersJavaScript SDK →