Run a battle end to end

This tutorial builds the core Arena loop against the API. You’ll need an access token in DUALMIND_TOKEN (how to get one).

Your access token acts as you: anyone holding it can start battles, vote and read your private threads until it expires. Keep it in an environment variable and never paste it into shared code, issues or chats.

dualmind-battle

.env

battle.mjs

battle.py

Put DUALMIND_TOKEN=... in .env (and .env in .gitignore), then follow along in JavaScript (Node 18+) or Python 3.9+.

Create a thread (optional)

Threads keep battles together and make them shareable. Skip this step if you don’t need history.

THREAD_ID=$(curl -s https://api.dualmindlab.tech/api/threads \
  -H "Authorization: Bearer $DUALMIND_TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Haiku battles", "mode": "battle"}' | jq -r .threadId)

const api = (path, body) =>
  fetch(`https://api.dualmindlab.tech${path}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.DUALMIND_TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  }).then(async (r) => {
    if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
    return r.json();
  });

const { threadId } = await api("/api/threads", { title: "Haiku battles", mode: "battle" });

import os, requests

S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['DUALMIND_TOKEN']}"
BASE = "https://api.dualmindlab.tech"

thread_id = S.post(f"{BASE}/api/threads", json={"title": "Haiku battles", "mode": "battle"}).json()["threadId"]

Start a blind battle

Leave model1 and model2 out so the Arena picks two random models.

curl -s https://api.dualmindlab.tech/api/arena/dualchat --max-time 150 \
  -H "Authorization: Bearer $DUALMIND_TOKEN" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Write a haiku about distributed systems\", \"threadId\": \"$THREAD_ID\"}" > battle.json
jq -r '.comparisonId, .agent1.message, "---", .agent2.message' battle.json

const battle = await api("/api/arena/dualchat", {
  prompt: "Write a haiku about distributed systems",
  threadId,
});
console.log("A:", battle.agent1.message);
console.log("B:", battle.agent2.message);

battle = S.post(
    f"{BASE}/api/arena/dualchat",
    json={"prompt": "Write a haiku about distributed systems", "threadId": thread_id},
    timeout=150,
).json()
print("A:", battle["agent1"]["message"])
print("B:", battle["agent2"]["message"])

Keep the names hidden

The response includes each side’s model and an arena.models summary so you can reveal them later. For a fair vote, don’t show these until the user has voted:

const blind = { comparisonId: battle.comparisonId, a: battle.agent1.message, b: battle.agent2.message };
const reveal = { a: battle.agent1.model.displayName, b: battle.agent2.model.displayName };

If a model is unreachable or takes longer than 60 seconds, a basic fallback model answers instead and the reply starts with a [System Note]. You’d be judging the fallback, so consider skipping the vote on that battle.

Vote

left means agent1 won and right means agent2 won. You can also send tie or both-bad. One vote per user per comparison.

curl -s https://api.dualmindlab.tech/api/arena/model-vote \
  -H "Authorization: Bearer $DUALMIND_TOKEN" -H "Content-Type: application/json" \
  -d "{\"comparisonId\": \"$(jq -r .comparisonId battle.json)\", \"voteChoice\": \"left\", \"voteDurationMs\": 9000}"

const started = Date.now();
// ...user reads both answers and picks one...
await api("/api/arena/model-vote", {
  comparisonId: blind.comparisonId,
  voteChoice: "left", // "left" | "right" | "tie" | "both-bad"
  voteDurationMs: Date.now() - started,
});

S.post(
    f"{BASE}/api/arena/model-vote",
    json={"comparisonId": battle["comparisonId"], "voteChoice": "left", "voteDurationMs": 9000},
).raise_for_status()

Reveal

Now show the names:

jq -r '"A was \(.agent1.model.displayName) (\(.agent1.model.provider))", "B was \(.agent2.model.displayName) (\(.agent2.model.provider))"' battle.json

console.log(`A was ${reveal.a}, B was ${reveal.b}`);

a, b = battle["agent1"]["model"], battle["agent2"]["model"]
print(f"A was {a['displayName']} ({a['provider']}), B was {b['displayName']} ({b['provider']})")

You’ve built the full Arena loop: battle, blind vote, reveal. Your vote counts on the leaderboard like any other.

Variations

Side by Side: choose both models

Pass both model1 and model2 (a modelName or modelId from List models):

{ "prompt": "Explain CRDTs in 3 sentences", "model1": "llama-3.3-70b-versatile", "model2": "gemini-2.5-flash" }

Topper: challenge the leader

{ "prompt": "Prove that there are infinitely many primes", "selectionMode": "topper" }

Same settings for both sides

system, maxTokens and temperature apply to both models:

{ "prompt": "Write a product tagline", "system": "Answer in under 12 words.", "maxTokens": 256, "temperature": 0.9 }

Start a battle

Full request and response reference.

Submit a vote

Vote options and errors.

Overview

Tutorials

Arena

Voting & leaderboard

Models

Threads

Utilities

Variations

Start a battle

Submit a vote

​Variations

Start a battle

Submit a vote

Variations