Agent loop

There are two ways to reach the same scoring pipeline, and the right one depends on where your agent runs.

MCP — rank_assets

Takes local file paths and uploads them for you. Best for repo-local and interactive work.

REST — POST /api/v1/rank

Takes fetchable URLs. Best for volume, scheduled jobs, and services with no client attached.

Both paths hit the same model. The difference is transport and where the files live — MCP handles the upload step, REST expects you to have already published the assets.

The cycle

Collect the creatives

Gather the files you want scored. The agent works from its own filesystem — Kettio’s tools take local paths directly. See the tool reference.

Rank them

Via MCP, call rank_assets with local paths. Via REST, publish to durable https:// URLs — or inline a data:image/ payload for small images — then call POST /api/v1/rank. Up to 20 assets either way.

Decide from the response

Use the ordering, copy_lift to see whether the words are earning their place, panel_outcome to see where refinement changed the order, and summary.scoring_evaluations to track spend.

Decision rules worth encoding

These are the checks worth writing into the agent rather than leaving to a model’s judgment:

Never act on a batch with silent failures

summary.assets_failed > 0 means the ordering you are reading is incomplete. Either re-run the failed assets or mark the result provisional.

if (summary.assets_failed > 0) throw new Error("incomplete batch");

Treat near-ties as ties

A small gap between rank 1 and rank 2 is not a decision. Either escalate to /api/v1/pairwise or report both. See Reading confidence.

Track ad allowance and evaluation rate limits

One successfully ranked asset uses one monthly ad ranking. An asset with copy_context can require two evaluations toward the per-minute rate limit. Track ad_rankings_remaining for monthly usage and honor Retry-After on 429. See Limits and billing.

Keep the audience fixed across a comparison

Scores are relative within a batch and conditioned on the audience. Changing the audience between runs and comparing the numbers is not a valid comparison.

Rate limit backoff

The Rank API allows 60 scoring evaluations per minute per key and returns Retry-After on 429. Honour it rather than retrying on a fixed interval:

async function rankWithBackoff(body, attempt = 0) {
  const response = await fetch("https://kettio.com/api/v1/rank", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KETTIO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (response.status === 429 && attempt < 4) {
    const retryAfterSeconds = Number(response.headers.get("Retry-After") ?? 5);
    await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
    return rankWithBackoff(body, attempt + 1);
  }

  return response.json();
}

MCP installation

Connect Claude Desktop, Codex, or any stdio MCP client.

Rank API

Goals, asset types, copy context, and refinement behavior.

Get started

Guides

Concepts

MCP server

Changelog

MCP — rank_assets

REST — POST /api/v1/rank

The cycle

Decision rules worth encoding

Rate limit backoff

MCP installation

Rank API

MCP — rank_assets

REST — POST /api/v1/rank

​The cycle

​Decision rules worth encoding

​Rate limit backoff

​Related

MCP installation

Rank API

The cycle

Decision rules worth encoding

Rate limit backoff

Related