Authentication

Every Kettio API request needs a bearer token:

Authorization: Bearer agk_live_YOUR_KEY

The base URL is https://kettio.com for all endpoints.

Self-serve ranking API access requires Professional or another API-enabled plan. Free and Starter accounts can rank ads in the web app, but cannot create self-serve API keys.

Create a key

Open API Keys

Go to Dashboard → API Keys.

Generate a key

Keys are prefixed agk_live_.

Store it immediately

Kettio displays the raw key once. Put it straight into your secret manager.

This is a server-to-server API. Never embed a key in browser or mobile code, commit it to a repository, or paste it into a public issue thread. If you lose a key, create a replacement from the dashboard.

Verify it works

curl -X POST https://kettio.com/api/v1/rank \
  -H "Authorization: Bearer agk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [{ "url": "https://cdn.example.com/ad-a.png", "id": "ad-a" }],
    "audience": { "name": "Millennial pet owners" }
  }'

A 401 means the key is missing or invalid. A 403 means the account does not have ranking API access. See error codes for the other statuses.

Error codes

Status	Meaning
`401`	Missing or invalid API key
`402`	Not enough ad rankings remaining for this batch
`403`	Ranking API access requires an API-enabled plan
`404`	`audience_id` not found, or not owned by your account
`422`	Validation error in the request body
`429`	Rate limited — check the `Retry-After` header

Rate limits count scoring evaluations. The monthly ranking allowance counts successfully ranked ads. See Limits and billing.

Using a key with MCP

The MCP server reads the same key from an environment variable:

KETTIO_API_URL=https://kettio.com
KETTIO_API_KEY=agk_live_YOUR_KEY

Full setup for each client is in MCP installation.

Get started

Guides

Concepts

MCP server

Changelog

Authentication

Create a key

Verify it works

Error codes

Using a key with MCP

​Create a key

​Verify it works

​Error codes

​Using a key with MCP

Create a key

Verify it works

Error codes

Using a key with MCP