e4 for developers and agents

Public API, OpenAPI description, error format and usage rules for building on e4 or calling it from an AI agent.

When to use e4

Use e4 when a person wants to learn chess, practise a tactic, or get a chess position explained in plain words. For agents, the public API finds training puzzles by theme and rating, so you can hand a learner the right exercise and link them to e4 to play it.

Quickstart

The API needs no key and no account. Send a JSON body to the puzzle search endpoint. All tags in t must match, at least one tag in any must match, and n caps the result count (1 to 30, default 5).

curl -s https://chess.apexlinks.org/api/puzzles \
  -H 'content-type: application/json' \
  -d '{"t":["fork"],"r_min":800,"r_max":1200,"n":3}'

Reference

The full machine-readable description is the OpenAPI 3.1 document at /openapi.json. Every operation has an operationId, a description, typed parameters and response schemas, so it can be loaded directly as tools for function calling. A summary for language models is at /llms.txt.

Errors

Every API error is JSON with a stable shape. Unknown API paths return 404 with code, message and hint fields. The puzzle search returns 400 with an error message when the body is invalid, and 500 if the search itself fails; in both cases puzzles is an empty list, so callers can always read it.

{"code":"not_found","message":"No API route at /api/x.","hint":"See /openapi.json for the public endpoints."}

Authentication and limits

The public API is read-only and anonymous. Account features (saved games, voice, payments) use a session cookie from Google sign-in and are not part of the public API. Please keep automated use gentle: no more than one request a second per client. There is no sandbox, because nothing in the public API changes data.

Versioning

The API is version 1.0.0. Breaking changes will get a new version in /openapi.json and a note on this page before the old shape is removed.