KnobaseKnobase Ads API reference
A UI-neutral, policy-aware sponsored-offer decision and tracked-link service.
Knobase Ads is a server-side decision API. It returns either a labeled, tracked offer or a successful no-fill. It does not generate, rewrite, or append to the publisher’s organic AI answer.
Product invariants
- Knobase is UI-neutral. It never requires a compact card, post-answer card, panel, sidebar, empty slot, or a new chat UI.
- Publishers may use an eligible offer only in an existing, separate, clickable native surface.
- Every rendered offer must visibly show sponsorship disclosure, advertiser identity, and the Knobase tracked link.
- If no compliant existing surface exists, the correct outcome is no-render. Do not append a raw URL or commercial copy to the organic answer.
- KNOBASE_API_KEY is server-side only, long-lived until revoked or rotated, and scoped to one app and environment.
- The only V1 offer decision endpoint is POST /v1/offers/decide.
- Raw full chat history is not accepted. The current message is transient only and is not persisted.
- No-fill is a valid successful result. The organic answer must remain available on no-fill, timeout, or error.
Implemented V1 endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /v1/offers/decide | Bearer serving key | Decide whether to return a labeled offer |
| GET | /r/{token} | None (browser) | Redirect a tracked click |
| POST | /v1/events/rendered | Bearer serving key | Record offer_rendered |
| POST | /v1/events/qualified-impression | Bearer serving key | Record qualified_impression |
| POST | /v1/events/impression | Bearer serving key | Alias until first-party clients migrate |
| POST | /v1/events/conversion | Bearer serving key | Record a signed conversion |
GET /v1/decisions/{id} can read decision metadata with the same serving key. It is listed in OpenAPI and is not a required integration step.
OpenAPI and LLM contract
Download the machine-readable contract as OpenAPI JSON, or copy the Markdown developer contract for coding agents. Copy for LLM uses the same text as /docs/llms.txt.