Ranking API for Agents

┌───────────────────────┐
│  Agent / CLI / Script │
└──────────┬────────────┘
           │  POST /api/v1/rank
           │  { assets[], audience, goal, platform }
           ▼
┌───────────────────────┐
│    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[],  │
│  copy lift + credits  │
└───────────────────────┘

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",
        "copy_context": {
          "pageName": "Pawbox",
          "adBody": "First box free for new subscribers.",
          "adHeadline": "Healthy treats your dog will actually want"
        }
      },
      { "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",
    "platform": "meta",
    "refine_close_pairs": true
  }'

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.

{
  "url": "https://cdn.example.com/ad-a.png",
  "id": "ad-a",
  "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",
    "adDescription": "Subscription dog treats delivered monthly"
  }
}

{
  "request_id": "a1b2c3d4-...",
  "ranked": [
    {
      "rank": 1,
      "asset_url": "https://example.com/ad-a.png",
      "asset_id": "ad-a",
      "score": 4.23,
      "score_before_refine": 4.23,
      "score_layer": "full-ad-package",
      "asset_type": "Social Media Post",
      "copy_context_included": true,
      "image_only_score": 3.81,
      "copy_lift": 0.42,
      "rationale": "This ad immediately communicates value...",
      "product_read": "A promotional banner showing a family...",
      "panel_outcome": null,
      "confidence": "high",
      "confidence_details": {
        "entropy": 0.42,
        "top_margin": 0.31,
        "sample_std_dev": 0.08
      },
      "details": {
        "probabilities": [0.02, 0.06, 0.18, 0.46, 0.28],
        "similarities": [0.12, 0.21, 0.35, 0.47, 0.41]
      }
    },
    {
      "rank": 2,
      "asset_url": "https://example.com/ad-b.png",
      "asset_id": "ad-b",
      "score": 3.15,
      "score_before_refine": 3.15,
      "score_layer": "image-only",
      "asset_type": "Social Media Post",
      "copy_context_included": false,
      "image_only_score": 3.15,
      "copy_lift": 0,
      "rationale": "The creative lacks a clear value proposition...",
      "confidence": "medium",
      "panel_outcome": null
    }
  ],
  "errors": [],
  "summary": {
    "goal": "purchase-intent",
    "asset_type": "Social Media Post",
    "audience": "Budget-conscious parents",
    "assets_ranked": 2,
    "assets_failed": 0,
    "scoring_evaluations": 3,
    "close_pair_refinement": {
      "enabled": true,
      "pairs_evaluated": 0,
      "results": []
    },
    "credits_used": 3,
    "credits_remaining": 48
  }
}