Overview
Send a flat picture of a chess position and the response tells you where the pieces are. That is a diagram printed in a book or a magazine, a page exported from a PDF, or a screenshot from a stream, an app or an analysis board.
What you get back is one FEN. You do not train anything, host anything, or keep a GPU warm.
Authentication
A bearer key in the Authorization header on every request. There is no other scheme, no query parameter, and no cookie.
Keys are issued by arrangement rather than by signup, so there is nothing to generate yourself. Access says how to ask.
Recognize a position
One command, and it is the whole API. The body is multipart/form-data with the image in it. The request is synchronous: the position comes back on the same connection, and there is no job to poll.
The image is kept, exactly as you sent it — metadata included, so a photograph keeps whatever your camera recorded in it, location and all. We store it alongside the placement the reader returned, for as long as the account exists: a reading that came back wrong is otherwise impossible to look into, and the reader cannot be measured against real pictures. Deleting the account deletes both.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| image | file | Yes | — | The picture of the position. PNG or JPEG, up to 5 MB, with no side under 16 or over 12000 pixels. See below for what happens to it after we answer. |
| orientation_hint | white | black | auto | No | auto | Which colour sits at the bottom of the board, when you already know. Left at auto, the reader works it out from the image. |
| side_to_move | w | b | No | w | Whose turn it is. Not in the picture, so not read: this is the value composed into the fen field below. |
Response
200 with a JSON object carrying one field. An image that yields no position is not a 200 at all: it is a 422 not_recognised, because with one field there is nowhere in the body to say so.
One field is deliberate. It is the notation, and everything else a reader could report about a position — which squares it doubted, how sure it was, which way round the board sat — is left out until a caller needs it rather than shipped because it exists.
| Field | Type | Description |
|---|---|---|
| fen | string | The position, as the notation every chess program reads. Only the first field of it — the piece placement — was read off your image. Side to move, castling rights, en passant and both counters are not visible in a picture, so they are the defaults w - - 0 1 and you should overwrite any you know. |
Errors
Every error carries a machine-readable code. That string is the part we promise not to change inside v1; the sentence beside it is free to be reworded or translated.
{
"code": "unsupported_format"
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_body | The multipart body could not be read. |
| 401 | unauthenticated | No key, or a key that is no longer valid. |
| 413 | too_large | Over 5 MB. |
| 415 | no_file | No image part in the body. |
| 415 | unsupported_format | Not a PNG or a JPEG. |
| 415 | unreadable_image | The header does not parse. |
| 415 | dimensions_out_of_range | A side under 16 or over 12000 pixels. |
| 422 | not_recognised | No position could be read out of the image. This one is about your picture. |
| 429 | rate_limited | Your key is over its quota, or has too many requests in flight. See Retry-After. |
| 502 | recogniser_unavailable | Ours, not yours. We could not get an answer out of the reader. Retry the same image. |
| 503 | at_capacity | Ours, not yours. Too much in flight right now. See Retry-After. |
What it will not read
Flat pictures of a position, and that is the whole of it. The boundary is not a limitation to be lifted later, it is what the reader is for.
- Photographs of a physical board, at any angle
- Video, or a position that is still moving
- Handwritten scoresheets and move lists
A photographed 3D board is a harder problem with a worse answer, so Chesslord does not pretend to solve it. Flat diagrams it can be held to.
Access
Write to [email protected] and say what you are building and roughly how many images a month it would send. Those two answers are what we need, and there is no form to fill in.
The endpoint is not open yet, and there is no self-serve signup to join instead. Access will be limited on purpose while it is new: a key will carry a rate limit and a quota, and it can be turned off. If the answer is no you will get a reason rather than silence.