AI advertising API and SDK integration docs

Connect an AI application

Ad cards appear separately from the AI response and are labeled “Ad”.

Add your app

Open Apps in the app owner account. Enter a name and HTTPS URL. The app will be sent for review.

Save the server key

The key is shown only once. Store it in your server’s secrets. Do not put it in a prompt, browser code or Git. Rotate a lost key in your account.

CONTEXTA_URL=https://inai.ad
CONTEXTA_PUBLISHER_KEY=ctx_pub_YOUR_SERVER_KEY

Connect the SDK

Download the SDK files into one server folder and create a client. The ad request runs alongside your app; the main AI response is generated separately.

SDK files

Keep server files together. Add AdCard.tsx for React. Plain websites can use contexta-sdk.js.

server.ts types.ts classify.ts need.ts catalog.ts partner.ts AdCard.tsx

import { createContexta } from "./inai/server.ts";

const ads = createContexta({
  baseUrl: process.env.CONTEXTA_URL!,
  apiKey: process.env.CONTEXTA_PUBLISHER_KEY!,
  classifier: classifyWithYourExistingModel,
});

Send matching data

Use trusted data for age, ad permission and location. Keep sessionId stable across requests and requestId stable when retrying one operation. In need, supply the specific product, budget stated by the user and required features.

const result = await ads.decideConversation({
  context: {
    requestId: stableOpportunityUuid,
    sessionId: stableRandomAdSessionId,
    country: trustedCountry, city: trustedCity,
    language: "ru", placement: "chat_card",
    age: trustedAge, adsAllowed: trustedConsent,
    sensitive: safetyResult.isSensitive,
  },
  messages: recentConversation,
  userTurn: fullSessionUserTurnCount,
});
// Only structured need/context leaves your backend.
// Raw conversation stays with your application.

Display the card

Return ad alongside the response or as a separate stream event. Show one card labeled “Ad”. If the user opts out, stop subsequent ad requests.

Check an impression and a click

After the app is approved and delivery enabled, check: a card visible for at least one second produces one impression; a user click produces one click. Retrying the same event must not create another charge.

What we read from a website

Names, descriptions, images, prices and currencies, product features and location, when the page provides them. Check the suggested category and offer type. Clarify price ranges, unclear subscription periods and data available only through JavaScript manually. Google Ads is supported through CSV; direct account connection is not available yet.

Before launch

The key is on your server. The campaign and app are approved.
The product, country, language, price and features fit the request.
The app settings permit delivery: timing and frequency limits are met.
On errors, timeouts, unknown age, opt-out or sensitive topics, the app responds without an ad.
The card is visible, the link opens, and an impression and click appear in the report.

Why an ad did not appear

This is not always an error. Delivery may be off, request data incomplete, no offer suitable or a limit reached. Check the API response reason and the integration status in your account. Do not retry solely to force an impression.

For your developer or AI coding assistant

Integrate inai.ad into the existing backend. Read:
https://inai.ad/sdk/partner-integration.md
https://inai.ad/sdk/integrator-agent.md
https://inai.ad/sdk/context-prompt.md

Keep the current AI provider, auth and independent answer.
Use server-only credentials and structured need.
Verify real visibility, native click navigation and reports.
Never fabricate production integration evidence.

Download technical instructions

How to launch ads with inai.ad