Go from zero to serving your first ad in under 5 minutes.

​
Prerequisites

Your API key starts with aiarco_ and is used to authenticate every request.

​
Step 1 — Fetch an Offer

Make a POST request to the offers endpoint with the user’s query: 
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 running shoes",
    "context": "shopping",
    "limit": 1
  }'

​
Response

{
  "offers": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "title": "Nike Air Zoom Pegasus 41",
      "content": "Responsive cushioning for everyday runs. Free shipping on orders over $100.",
      "cta": "Shop Now",
      "clickUrl": "https://ads-api.aiarco.com/api/v1/clicks/f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "source": "aiarco",
      "ad_type": "sponsored_result",
      "brand": {
        "name": "Nike",
        "iconUrl": "https://example.com/nike-icon.png"
      },
      "price": {
        "amount": 129.99,
        "currency": "USD"
      },
      "rating": {
        "value": 4,
        "scale": 5,
        "count": 2847
      }
    }
  ]
}
Do not cache offer responses. Caching will break impression tracking and attribution.

​
Step 2 — Display the Offer

Render the offer in your UI. Always use the clickUrl for the CTA link — it includes built-in click tracking and redirects to the advertiser’s landing page. 
// Example: render in a chat response
function renderAd(offer) {
  return `
    <div class="sponsored-result">
      <span class="badge">Sponsored</span>
      <h3>${offer.title}</h3>
      <p>${offer.content}</p>
      <a href="${offer.clickUrl}" target="_blank" rel="noopener sponsored">
        ${offer.cta}
      </a>
    </div>
  `;
}

​
Step 3 — Track the Impression

After confirming the offer was actually visible to the user, report the impression. 
curl -X POST https://ads-api.aiarco.com/api/v1/impressions/batch \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
Returns 204 No Content on success.

​
That’s it!

You’re now serving contextual ads and earning revenue from every click. Here’s what to explore next:

REST API Guide

Full parameter reference, typed signals, and advanced targeting.

Woven Offers

Inject ads into LLM system prompts for natural, AI-native integration.

Signal Collection

Send user intent signals to improve ad relevance and targeting.

JavaScript SDK

Drop-in script tag with automatic rendering and tracking.

​
Troubleshooting

IssueSolution
401 UnauthorizedCheck your API key. It should be sent in the X-AIARCO-API-Key header and start with aiarco_.
Empty offers arrayNo campaigns matched your query. Try a broader query or check that active campaigns exist for your channel’s categories.
reason: "frequency_cap"Too many requests for this user. Wait for the frequency cap window to reset or use a different user_id.