API Reference

REST endpoints for advertisers and publishers, with JSON over HTTPS.

The Koah API is organized around resources with predictable URLs, JSON-encoded responses, and standard HTTP verbs and status codes. It covers two roles:

• Advertisers send conversion events from their own servers with the Conversion API — the server-side counterpart to the Koah pixel. For a step-by-step setup guide, see API Installation.
• Publishers manage the publishers under their team and pull daily performance metrics with the Publishers and Reporting endpoints. For what the metrics mean, see Reporting.

Base URL

Every endpoint lives on https://app.koah.ai. Conversion endpoints are versioned under /api/v1; publisher endpoints live under /api.

Authentication

Every request is authenticated with a bearer token in the Authorization header. Where you generate it depends on your role:

• Advertisers create an API key from the API keys tab of the advertiser dashboard settings.
• Publishers create an API token from the Koah dashboard under Settings › API Tokens. Publisher endpoints are only available to publisher team accounts.

Keep keys and tokens on the server. Never embed them in client-side code or ship them in a mobile app.

Responses

Successful requests return 200 OK (or 201 Created) with a JSON body. Publisher endpoints report problems through the HTTP status — 401, 403, 404, 422, 429 — with an error message in the body. The Conversion API reports per-event validation problems in a messages array rather than through the status, so a 200 does not mean every event was accepted; see the Send events response for details.

Rate limits

The Conversion API allows 100 requests per second per IP address, each carrying up to 100 events. Publisher endpoints allow 10 requests per minute; exceeding it returns 429.