This week...
", "stats": { "matches_played": 1520, "top_bot": "SwarmBot", "top_bot_rating": 1847 } }`, }, ], }, { title: 'R2 Endpoints (Warm Cache)', description: 'Recent replays and real-time data served from Cloudflare R2. Free tier capped at 10GB. Try R2 first, fall back to B2 for older data.', endpoints: [ { method: 'GET', path: '/evolution/live.json', description: 'Real-time evolution observatory data. Updated every evolution cycle (~5 min) with Cache-Control: max-age=10.', cache: '10 seconds', responseExample: `{ "updated_at": "2026-03-29T12:05:00Z", "total_programs": 1247, "promoted_count": 12, "islands": { "alpha": {"count": 312, "best_fitness": 0.85, "avg_fitness": 0.62} }, "generation_log": [...], "lineage": [...], "meta_snapshots": [...] }`, }, { method: 'GET', path: '/replays/{match_id}.json.gz', description: 'Compressed replay file for recent matches. Contains full turn-by-turn game state.', cache: 'immutable (content-addressed)', schemaLink: '#replay-schema', }, { method: 'GET', path: '/matches/{match_id}.json', description: 'Per-match metadata including win probability curve and critical moments.', cache: 'immutable (content-addressed)', responseExample: `{ "match_id": "match_xyz789", "completed_at": "2026-03-29T11:45:00Z", "map_id": "map_2p_001", "config": {"rows": 60, "cols": 60}, "participants": [...], "result": {"winner": 0, "reason": "dominance", "turns": 247}, "win_prob": [[0.5, 0.5], [0.52, 0.48], ...], "critical_moments": [ {"turn": 87, "delta": 0.22, "description": "Decisive engagement"} ] }`, }, { method: 'GET', path: '/cards/{bot_id}.png', description: 'Canvas-rendered bot profile card image (1200x630) for Open Graph social sharing.', cache: 'max-age=86400 (1 day)', }, { method: 'GET', path: '/thumbnails/{match_id}.png', description: 'Auto-generated match thumbnail for embed previews.', cache: 'max-age=86400 (1 day)', }, ], }, { title: 'B2 Endpoints (Cold Archive)', description: 'Permanent archive for ALL replays and match data. Free egress via Cloudflare Bandwidth Alliance. Use as fallback when R2 returns 404.', endpoints: [ { method: 'GET', path: '/replays/{match_id}.json.gz', description: 'Compressed replay file. All replays are archived permanently on B2.', cache: 'immutable (content-addressed)', schemaLink: '#replay-schema', }, { method: 'GET', path: '/matches/{match_id}.json', description: 'Per-match metadata. Same structure as R2 endpoint.', cache: 'immutable (content-addressed)', }, { method: 'GET', path: '/cards/{bot_id}.png', description: 'Bot profile card images. All cards archived permanently.', cache: 'immutable', }, { method: 'GET', path: '/thumbnails/{match_id}.png', description: 'Match thumbnails. All thumbnails archived permanently.', cache: 'immutable', }, ], }, ]; // Replay JSON Schema section const replaySchema = `{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://aicodebattle.com/schemas/replay.json", "title": "Match Replay", "description": "Complete replay of an AI Code Battle match", "type": "object", "required": ["match_id", "config", "map", "players", "turns", "result"], "properties": { "match_id": { "type": "string", "description": "Unique match identifier" }, "config": { "$ref": "#/definitions/GameConfig" }, "map": { "$ref": "#/definitions/Map" }, "players": { "type": "array", "items": {"$ref": "#/definitions/Player"} }, "turns": { "type": "array", "items": {"$ref": "#/definitions/Turn"} }, "result": { "$ref": "#/definitions/Result" }, "win_prob": { "type": "array", "description": "Per-turn win probability for each player (computed post-match)", "items": { "type": "array", "items": {"type": "number"} } }, "critical_moments": { "type": "array", "description": "Turns with significant win probability shifts", "items": { "type": "object", "properties": { "turn": {"type": "integer"}, "delta": {"type": "number"}, "description": {"type": "string"} } } } }, "definitions": { "GameConfig": { "type": "object", "properties": { "rows": {"type": "integer", "minimum": 30, "maximum": 120}, "cols": {"type": "integer", "minimum": 30, "maximum": 120}, "max_turns": {"type": "integer", "default": 500}, "vision_radius2": {"type": "integer", "default": 49}, "attack_radius2": {"type": "integer", "default": 5}, "spawn_cost": {"type": "integer", "default": 3}, "energy_interval": {"type": "integer", "default": 10} } }, "Position": { "type": "object", "properties": { "row": {"type": "integer"}, "col": {"type": "integer"} } }, "Map": { "type": "object", "properties": { "rows": {"type": "integer"}, "cols": {"type": "integer"}, "walls": { "type": "array", "items": {"$ref": "#/definitions/Position"} }, "cores": { "type": "array", "items": { "type": "object", "properties": { "position": {"$ref": "#/definitions/Position"}, "owner": {"type": "integer"} } } }, "energy_nodes": { "type": "array", "items": {"$ref": "#/definitions/Position"} } } }, "Player": { "type": "object", "properties": { "id": {"type": "integer"}, "name": {"type": "string"}, "bot_id": {"type": "string"} } }, "Turn": { "type": "object", "properties": { "turn": {"type": "integer"}, "bots": { "type": "array", "items": { "type": "object", "properties": { "id": {"type": "integer"}, "owner": {"type": "integer"}, "position": {"$ref": "#/definitions/Position"}, "alive": {"type": "boolean"} } } }, "cores": { "type": "array", "items": { "type": "object", "properties": { "position": {"$ref": "#/definitions/Position"}, "owner": {"type": "integer"}, "active": {"type": "boolean"} } } }, "energy": { "type": "array", "items": {"$ref": "#/definitions/Position"}, "description": "Energy positions visible this turn" }, "scores": { "type": "array", "items": {"type": "integer"} }, "energy_held": { "type": "array", "items": {"type": "integer"} }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": {"type": "string", "enum": [ "bot_spawned", "bot_died", "energy_collected", "core_captured", "combat_death", "collision_death" ]}, "turn": {"type": "integer"}, "details": {"type": "object"} } } } } }, "Result": { "type": "object", "properties": { "winner": {"type": "integer", "description": "Player index, -1 for draw"}, "reason": {"type": "string", "enum": [ "sole_survivor", "dominance", "turn_limit", "annihilation" ]}, "turns": {"type": "integer"}, "scores": {"type": "array", "items": {"type": "integer"}}, "energy": {"type": "array", "items": {"type": "integer"}}, "bots_alive": {"type": "array", "items": {"type": "integer"}} } } } }`; export function renderDocsApiPage(): void { const app = document.getElementById('app'); if (!app) return; app.innerHTML = `All match data is exposed as static JSON files. There is no live API for data access — everything is pre-computed and served from CDN. This architecture enables unlimited read scale with zero server cost.
The replay format is versioned. The current version is v1.
${escapeHtml(replaySchema)}For replays and match metadata, always try R2 first and fall back to B2:
async function fetchReplay(matchId: string): Promise {
// Try R2 warm cache first
const r2Url = \`https://r2.aicodebattle.com/replays/\${matchId}.json.gz\`;
const r2Resp = await fetch(r2Url);
if (r2Resp.ok) {
return decompress(await r2Resp.arrayBuffer());
}
// Fall back to B2 cold archive
const b2Url = \`https://b2.aicodebattle.com/replays/\${matchId}.json.gz\`;
const b2Resp = await fetch(b2Url);
if (!b2Resp.ok) throw new Error(\`Replay not found: \${matchId}\`);
return decompress(await b2Resp.arrayBuffer());
} There are no rate limits on static file access. The CDN handles unlimited concurrent requests.
${section.description}
${section.endpoints.map(e => renderEndpoint(e, section.title)).join('')}${baseUrl}${endpoint.path}
${endpoint.description}
Cache: ${endpoint.cache}
${endpoint.responseExample ? `${escapeHtml(endpoint.responseExample)}