Getting Started

Quickstart

Fetch your first ad from the AIARCO API in under 5 minutes. Get your API key, make a request, and start monetizing.

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

Prerequisites

A publisher account on publishers.ads.aiarco.com
A channel API key (created in your publisher dashboard under Channels)

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

Issue	Solution
`401 Unauthorized`	Check your API key. It should be sent in the `X-AIARCO-API-Key` header and start with `aiarco_`.
Empty `offers` array	No 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`.

← Developer Documentation Channels →