Docs

Click Oracle docs

Quickstart, reading your results, the REST API, MCP setup and the calibration file format.

QuickstartReading resultsAPIMCPCalibrationLimits and errors

Quickstart

  1. Create an account. The Free plan includes 5 rankings a month of up to 20 options.
  2. Choose New ranking and the format: article headline, YouTube title, email subject line, ad headline or hook.
  3. Paste your options, one per line. Or open Write with Claude, describe the content and the audience, and pick how many options you want.
  4. If one option is what you use today, tick First line is my current version to see each option's odds of beating it.
  5. Choose Rank. Small sets usually come back in seconds; large sets take longer because there are more head-to-heads.

Reading your results

REST API

API access is on paid plans. Create a key in Account, API keys. Keys start with co_live_ and are shown once. Send them as a bearer token. All bodies are JSON.

Rank options

curl -s https://clickoracle.trylumegrid.com/v1/rank \
  -H "Authorization: Bearer $CLICK_ORACLE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"youtube","variants":["Option one","Option two","Option three"],"control":0}'

Fields: variants (2 to your plan's limit, strings up to 300 characters), format (headline, youtube, email, ad, hook; default headline), optional control (0-based index of your current version), profileId (use a brand profile's format and calibration) and title.

Response (shortened):

{
  "id": "rk_...",
  "verdict": { "kind": "lean", "pLeaderBeatsRunnerUp": 0.58, "topTier": [4],
               "summary": "Lean: #1 edges #2 (58%), but not by enough to skip a live test. Test #1 against #2." },
  "variants": [ { "rank": 1, "text": "...", "winOdds": 0.64, "pBeatsNext": 0.58, "pVsLeader": null,
                  "pVsControl": 0.61, "tier": "top", "comparisons": 5, "flags": [] } ],
  "design": "round_robin", "pairsJudged": 15, "orderAgreement": 0.8, "measured": false
}

Write options with Claude

Writes distinct options from a content brief. Counts against your plan's monthly Claude-written options. If Claude cannot write them, the request returns 502 generator_failed and nothing is counted against your plan.

curl -s https://clickoracle.trylumegrid.com/v1/generate -H "Authorization: Bearer $CLICK_ORACLE_API_KEY" -H "content-type: application/json" \
  -d '{"format":"email","brief":"This issue: how one bakery raised its average order 18% with a register display.","count":30,"audience":"Small bakery owners"}'

Optional: tone, mustInclude, avoid, examples (options you already have, so Claude does not repeat them), profileId. Returns {"id","variants":[...],"model"}. Generation does not rank; send the variants to /v1/rank.

Other endpoints

MCP (Claude and other MCP clients)

The MCP endpoint is https://clickoracle.trylumegrid.com/mcp (Streamable HTTP). It authenticates with the same API key as a bearer token. Tools: rank_variants, generate_variants, generate_and_rank, get_ranking, list_rankings, get_usage.

Claude Code

claude mcp add --transport http click-oracle https://clickoracle.trylumegrid.com/mcp \
  --header "Authorization: Bearer $CLICK_ORACLE_API_KEY"

Claude Desktop and other clients that launch local servers

Use the small bridge in the Click Oracle package (mcp/stdio.mjs, Node 18 or newer, no dependencies):

{
  "mcpServers": {
    "click-oracle": {
      "command": "node",
      "args": ["/path/to/click-oracle/mcp/stdio.mjs"],
      "env": { "CLICK_ORACLE_API_KEY": "co_live_...", "CLICK_ORACLE_URL": "https://clickoracle.trylumegrid.com" }
    }
  }
}

Web apps that only accept connectors with an OAuth sign-in (such as claude.ai custom connectors and ChatGPT connectors) are not supported yet.

Calibration with your own past tests

On paid plans, open Profiles, pick a profile and upload a CSV of past A/B tests. Two shapes are accepted (header names are not case sensitive):

test_id,variant,impressions,clicks
t1,"Why your podcast sounds bad",5120,212
t1,"The $40 fix for podcast audio",5088,251
t2,...
test_id,variant_a,variant_b,winner
t1,"Option A text","Option B text",b

You can use opens, conversions or successes instead of clicks, and sends, views, delivered or recipients instead of impressions. Up to 12 versions per test are used. Click Oracle ranks each past test, then shows how often it would have picked your real winner by band (counting tests with a clear result). With 10 or more tests it fits a calibration for that profile and blends it with the global one, giving your data more weight as you add tests. Each upload counts toward your plan's monthly limit of past tests calibrated, and one upload can hold up to 200 past tests on Creator, 1,000 on Pro and 2,000 on Agency.

Limits and errors

Limits per plan are on the pricing table. Usage resets on the first of each month at midnight Mountain Time. Upgrading raises your limit right away; it does not reset counters. Errors return JSON { "error": { "code", "message" } }:

Design notes

Up to 24 options, every pair is judged in both orders. Above 24, each option first meets 8 random opponents (the first round is a ring, so every option is connected), then the top 16 play a full round robin. On three Claude-written sets of 120 options, we compared this with judging every pair: the tournament's #1 was the full round robin's #1 in 2 of 3 sets and in its top 3 in 3 of 3, the two top 10s shared 9 of 10 options on average, and rank correlation was at least 0.987, using about 1/11 of the comparisons.