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": 0,
"credits_remaining": null,
"ad_rankings_used": 1,
"ad_rankings_remaining": 499
}
}{
"error": "<string>",
"field": "<string>"
}{
"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>"
}Endpoints
Rank assets
Score and rank a batch of ad creative assets against one audience.
POST
/
api
/
v1
/
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": 0,
"credits_remaining": null,
"ad_rankings_used": 1,
"ad_rankings_remaining": 499
}
}{
"error": "<string>",
"field": "<string>"
}{
"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
Kettio API key, for example Authorization: Bearer agk_live_xxx.
Body
application/json
- Option 1
- Option 2
Required array length:
1 - 20 elementsShow child attributes
Show child attributes
Show child attributes
Show child attributes
Saved audience ID from the authenticated Kettio account.
Default asset type for assets that do not provide their own asset_type.
Optional platform context, for example meta, instagram, facebook, tiktok, linkedin, or google.
Optional campaign placement/context alias used when platform is omitted.
When true, Kettio can run a pairwise panel on near-tied successful assets and adjust rank ordering when the panel disagrees.