API docs

REST API reference. The API is not live yet - it is in private pilot and this page describes the coming interface accurately, not a running service. Email adagentzteam@gmail.com to join the pilot.

Basics

Base URL: https://api.adagentz.com (reserved, not yet serving). Auth: X-Api-Key header with your key. Rate limit: 60 requests per minute per key. Sandbox keys serve labelled test ads only; nothing bills in sandbox.

For hosts (agents and sites)

POST /v1/impressions - request an ad for the current context. Send the topic of the person's current question, never the conversation. Returns one labelled sponsored suggestion, or no ad when nothing relevant or appropriate exists. Sensitive contexts never return ads.

POST /v1/feedback - report what happened: shown, clicked, dismissed, or a complaint. Feedback drives relevance and frequency caps.

GET /v1/earnings - your aggregate earnings and payout status. 70% of ad revenue to the host at launch.

For advertisers

POST /v1/campaigns - create a campaign from site, goal and budget cap. Always created paused.

POST /v1/campaigns/{id}/approve - approve the exact draft. Approval is blocked if any claim is not backed by your own website.

POST /v1/campaigns/{id}/pause - stop delivery immediately. Nothing spends while paused.

GET /v1/reports - aggregate outcomes only: views, clicks, spend. Never anyone's conversations.

Rules that apply to every caller

One ad per answer at most, frequency caps per person, no ad profiles, no sensitive-context ads, and advertisers never see conversations. The Content policy lists what we do not run.