Rank assets

curl --request POST \
  --url https://kettio.com/api/v1/rank \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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_url": "https://cdn.example.com/ad-a.png",
      "asset_id": "ad-a",
      "score": 4.24,
      "score_before_refine": 4.23,
      "score_layer": "full-ad-package",
      "asset_type": "Advertisement",
      "copy_context_included": true,
      "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,
      "confidence_details": {
        "entropy": 0.38,
        "top_margin": 0.35,
        "sample_std_dev": 0.06,
        "repetition_count": 3,
        "generator_sample_count": 6
      },
      "details": {
        "probabilities": [
          0.02,
          0.06,
          0.18,
          0.46,
          0.28
        ],
        "similarities": [
          0.12,
          0.21,
          0.35,
          0.47,
          0.41
        ],
        "repetitionCount": 3,
        "generatorSampleCount": 6,
        "repetitionScores": [
          4.18,
          4.24,
          4.3
        ],
        "repetitionScoreRange": 0.12
      }
    }
  ],
  "errors": [],
  "summary": {
    "goal": "purchase-intent",
    "asset_type": "Social Media Post",
    "platform": "meta",
    "audience": "Millennial pet owners",
    "assets_ranked": 1,
    "assets_failed": 0,
    "scoring_evaluations": 2,
    "repetitions_per_evaluation": 3,
    "generator_samples_per_evaluation": 6,
    "close_pair_refinement": {
      "enabled": true,
      "pairs_evaluated": 0,
      "results": []
    },
    "credits_used": 2,
    "credits_remaining": 48
  }
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>",
  "retryAfter": 123,
  "resetAt": 123
}

{
  "error": "<string>",
  "field": "<string>"
}

POST

api

rank

curl --request POST \
  --url https://kettio.com/api/v1/rank \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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_url": "https://cdn.example.com/ad-a.png",
      "asset_id": "ad-a",
      "score": 4.24,
      "score_before_refine": 4.23,
      "score_layer": "full-ad-package",
      "asset_type": "Advertisement",
      "copy_context_included": true,
      "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,
      "confidence_details": {
        "entropy": 0.38,
        "top_margin": 0.35,
        "sample_std_dev": 0.06,
        "repetition_count": 3,
        "generator_sample_count": 6
      },
      "details": {
        "probabilities": [
          0.02,
          0.06,
          0.18,
          0.46,
          0.28
        ],
        "similarities": [
          0.12,
          0.21,
          0.35,
          0.47,
          0.41
        ],
        "repetitionCount": 3,
        "generatorSampleCount": 6,
        "repetitionScores": [
          4.18,
          4.24,
          4.3
        ],
        "repetitionScoreRange": 0.12
      }
    }
  ],
  "errors": [],
  "summary": {
    "goal": "purchase-intent",
    "asset_type": "Social Media Post",
    "platform": "meta",
    "audience": "Millennial pet owners",
    "assets_ranked": 1,
    "assets_failed": 0,
    "scoring_evaluations": 2,
    "repetitions_per_evaluation": 3,
    "generator_samples_per_evaluation": 6,
    "close_pair_refinement": {
      "enabled": true,
      "pairs_evaluated": 0,
      "results": []
    },
    "credits_used": 2,
    "credits_remaining": 48
  }
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>"
}

{
  "error": "<string>",
  "field": "<string>",
  "retryAfter": 123,
  "resetAt": 123
}

{
  "error": "<string>",
  "field": "<string>"
}

Authorizations

Authorization

string

header

required

Kettio API key, for example Authorization: Bearer agk_live_xxx.

Body

application/json

Option 1
Option 2

assets

object[]

required

Required array length: 1 - 20 elements

Show child attributes

audience

object

required

Show child attributes

audience_id

string

Saved audience ID from the authenticated Kettio account.

goal

string

default:purchase-intent

asset_type

string

default:Social Media Post

Default asset type for assets that do not provide their own asset_type.

platform

string

Optional platform context, for example meta, instagram, facebook, tiktok, linkedin, or google.

campaign_type

string

Optional campaign placement/context alias used when platform is omitted.

refine_close_pairs

boolean

default:true

When true, Kettio can run a pairwise panel on near-tied successful assets and adjust rank ordering when the panel disagrees.

Response

Ranked assets and any per-asset errors.

request_id

string<uuid>

required

ranked

object[]

required

Show child attributes

errors

object[]

required

Show child attributes

summary

object

required

Show child attributes

⌘I

Overview

Endpoints

Authorizations

Body

Response