API overview

Early access. API keys open together with accounts; this page documents the API as it will ship. Scanning in the app is free and works now.

Send an image, get the position back. The API reads app and website screenshots, printed and scanned book diagrams, and video frames, and finds every board in the image.

Quickstart

1. Create a key on your account page. The key is shown once; copy it then.
2. Send an image as multipart/form-data in the image field.
3. Read fen. Check diagnostics.confidence.uncertain_squares before you trust it.

curl https://api.chessglance.com/v1/recognize \
  -H "X-API-Key: $API_KEY" \
  -F image=@board.png \
  -F orientation=auto

const form = new FormData();
form.append('image', file); // a File or Blob
form.append('orientation', 'auto');

const response = await fetch('https://api.chessglance.com/v1/recognize', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.API_KEY },
  body: form,
});
if (!response.ok) throw new Error((await response.json()).error);
const { fen, diagnostics } = await response.json();
console.log(fen, diagnostics.confidence.uncertain_squares);

import os
import requests

response = requests.post(
    "https://api.chessglance.com/v1/recognize",
    headers={"X-API-Key": os.environ["API_KEY"]},
    files={"image": open("board.png", "rb")},
    data={"orientation": "auto"},
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result["fen"], result["diagnostics"]["confidence"]["uncertain_squares"])

The response, abridged:

{
  "fen": "r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w - - 0 1",
  "board_fen": "r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R",
  "diagnostics": {
    "confidence": { "mean_confidence": 0.9987, "min_confidence": 0.93, "uncertain_squares": 0, "weakest_piece": 0.97 },
    "orientation": "white"
  },
  "elapsedMs": 380,
  "quota": { "limit": 10000, "used": 1250, "remaining": 8750 }
}

The full field list is on the recognize page.

What the image can and cannot tell you

A picture shows where the pieces are. It does not show whose move it is, castling rights, the en-passant square or the move counters. The API returns w - - 0 1 for those unless you pass sideToMove, castling, ep, halfmove and fullmove yourself.

Orientation, meaning which side is at the bottom, is detected for you (orientation=auto). The returned FEN is always written from White’s side of the board. When the detector is not sure, diagnostics.orientation_margin is low; below 10 the answer is a guess, and you should pass orientation=white or black if you know it.

Limits at a glance

More in errors and limits.

For study, not for live games

The API is for analysis, publishing and teaching. Using any output to assist in a live game breaks chess.com and lichess rules, and our terms forbid it for every plan.