Ranking API for Agents

┌───────────────────────┐
│  Agent / CLI / Script │
└──────────┬────────────┘
           │  POST /api/v1/rank
           │  { assets[], audience, goal }
           ▼
┌───────────────────────┐
│    Kettio API         │
│  Auth + Rate Limit    │
│  Credit Check         │
└──────────┬────────────┘
           │  Parallel evaluation (4 concurrent)
           ▼
┌───────────────────────┐
│   SSR Pipeline        │
│  Gemini → Rationale   │
│  Embed → Score (1-5)  │
└──────────┬────────────┘
           │  Sorted results
           ▼
┌───────────────────────┐
│   JSON Response       │
│  ranked[], errors[],  │
│  credits summary      │
└───────────────────────┘

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://example.com/ad-a.png", "id": "ad-a" },
      { "url": "https://example.com/ad-b.png", "id": "ad-b" },
      { "url": "https://example.com/ad-c.png", "id": "ad-c" }
    ],
    "audience": {
      "name": "Budget-conscious parents",
      "description": "Parents aged 30-44 who compare prices",
      "demographics": { "ageRange": "35-44", "priceSensitivity": "high" }
    },
    "goal": "purchase-intent"
  }'

For Computer-Use Agents

The API returns structured JSON — no browser interaction needed. Agents can parse the ranked[] array directly, read rationale strings for reasoning, and use score values to make decisions.

{
  "request_id": "a1b2c3d4-...",
  "ranked": [
    {
      "rank": 1,
      "asset_url": "https://example.com/ad-a.png",
      "asset_id": "ad-a",
      "score": 4.23,
      "rationale": "This ad immediately communicates value...",
      "product_read": "A promotional banner showing a family...",
      "confidence": "high",
      "confidence_details": {
        "entropy": 0.42,
        "top_margin": 0.31,
        "sample_std_dev": 0.08
      }
    },
    {
      "rank": 2,
      "asset_url": "https://example.com/ad-b.png",
      "asset_id": "ad-b",
      "score": 3.15,
      "rationale": "The creative lacks a clear value proposition...",
      "confidence": "medium"
    }
  ],
  "errors": [],
  "summary": {
    "goal": "purchase-intent",
    "asset_type": "Social Media Post",
    "audience": "Budget-conscious parents",
    "assets_ranked": 2,
    "assets_failed": 0,
    "credits_used": 2,
    "credits_remaining": 48
  }
}