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
Body
application/json
- Option 1
- Option 2