Kettio Rank API · Updated September 2026

Ad creative scoring API

The Kettio Rank API scores and ranks 1 to 20 ad images for a buyer and a campaign goal in one request. Send image URLs, an audience, and a goal to POST /api/v1/rank. Each ad comes back with a rank, a score, a written rationale, and a confidence level.

The ranking is directional: it tells you which ads to put into a live test first. Live media stays the final proof. Full reference lives at docs.kettio.com.

Endpoints

POST /api/v1/rank to score and rank a batch. POST /api/v1/pairwise for head-to-head checks.

Auth

Bearer token with a Kettio API key (agk_live_…). Create keys in the dashboard under API keys.

Batch size

1 to 20 image assets per rank request. 1 to 10 pairs per pairwise request.

Rate limit

60 scoring evaluations per minute per API key. An image-only asset is 1 evaluation; an asset with copy_context is 2.

Access

Professional or another API-enabled plan. Free and Starter accounts get a 403 until they upgrade.

Billing

Each successfully ranked asset uses one ad ranking from the monthly allowance shared with the app. Generation credits are not charged. A batch that exceeds the remaining allowance gets a 402.

POST /api/v1/rank

Rank a batch

Only assets is required. Each asset needs an HTTPS image URL or a data:image URI; the optional id comes back as asset_id so you can match results to your own records.

curl -X POST https://kettio.com/api/v1/rank \
  -H "Authorization: Bearer $KETTIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "url": "https://cdn.example.com/ad-a.png", "id": "ad-a" },
      { "url": "https://cdn.example.com/ad-b.png", "id": "ad-b" }
    ],
    "audience": {
      "name": "Budget-conscious parents",
      "description": "Parents aged 30-44 who compare prices before buying",
      "demographics": {
        "ageRange": "35-44",
        "priceSensitivity": "high",
        "shoppingIntent": "comparing"
      }
    },
    "goal": "purchase-intent",
    "platform": "meta"
  }'

{
  "request_id": "1f4d884c-f9ef-4f36-a8e9-f7b6a5b63291",
  "ranked": [
    {
      "rank": 1,
      "asset_id": "ad-a",
      "score": 4.24,
      "score_layer": "full-ad-package",
      "image_only_score": 3.81,
      "copy_lift": 0.42,
      "rationale": "The creative quickly communicates the offer and the copy removes purchase friction.",
      "product_read": "A product-focused social ad with subscription-box imagery and a clear first-box-free offer.",
      "confidence": "high",
      "panel_outcome": null
    }
  ],
  "errors": [],
  "summary": {
    "goal": "purchase-intent",
    "assets_ranked": 1,
    "assets_failed": 0,
    "scoring_evaluations": 2,
    "ad_rankings_used": 1,
    "ad_rankings_remaining": 499
  }
}

Request options

Options that change the result

{
  "url": "https://cdn.example.com/ad-a.png",
  "id": "ad-a",
  "asset_type": "Advertisement",
  "copy_context": {
    "pageName": "Pawbox",
    "adBody": "First box free for new subscribers. Fresh treats picked for picky dogs.",
    "adHeadline": "Healthy treats your dog will actually want",
    "adCaption": "Cancel anytime"
  }
}

Response

Reading the result

rank

Position in the batch, 1 is the strongest for this buyer and goal.

score

The ranking score on the goal’s five-point scale. Compare it within the batch, not across batches.

image_only_score, copy_lift

Present when copy_context was sent. Shows whether the image or the copy is carrying the ad.

rationale

Why the ad landed where it did, written from the buyer’s point of view.

product_read

What the model understood the ad to be selling. If this is wrong, fix the creative before trusting the score.

confidence

high, medium, or low, with the underlying spread in confidence_details.

errors

Per-asset failures. One bad image URL does not fail the batch.

The summary block reports ad_rankings_used and ad_rankings_remaining for the month, plus scoring_evaluations for rate limiting.

POST /api/v1/pairwise

Head-to-head checks

When you need a direct answer on specific matchups, send 1 to 10 pairs. Each pair gets five blinded Claude Haiku votes, balanced so each ad is shown first in some votes and second in others. Every vote and model response is returned, so you can audit why a pair went the way it did.

{
  "pairs": [
    {
      "pair_id": "creative-a-vs-b",
      "a": { "id": "creative-a", "image_url": "https://cdn.example.com/ad-a.png" },
      "b": { "id": "creative-b", "image_url": "https://cdn.example.com/ad-b.png" }
    }
  ],
  "audience": {
    "name": "GLP-1 shoppers",
    "description": "Women considering GLP-1 support who need credible purchase proof"
  },
  "goal": "purchase-intent",
  "platform": "facebook"
}

Workflow

How a ranking fits into testing

1. 01

   Send a comparable batch

   Same audience, offer, and objective across the batch. The ranking answers which of these ads to test first, so mixed products or goals make it meaningless.

2. 02

   Score the set

   Kettio scores each ad for the buyer and goal, then runs a head-to-head check on near-ties.

3. 03

   Read the drivers

   image_only_score and copy_lift show which part of each ad is carrying the result.

4. 04

   Build the next variant

   Borrow the strongest driver from lower-ranked ads, then put the top candidates into a live test.

Evidence

What the score is validated against

The two numbers are not combined into one accuracy figure, and neither is a CPA, ROAS, or purchase guarantee. Definitions and limits are on the methodology page.

Reference

Where to go next

• First API request

  Send your first batch with curl.

• API reference

  Every request and response field.

• Integration guide

  Calling the API from a TypeScript server.

• MCP server

  Let an AI assistant rank, list, and edit assets with Kettio tools.

• OpenAPI spec

  The machine-readable contract for both endpoints.

• API keys

  Create and revoke keys on a Professional plan.

FAQ

Common questions