L'API pour les développeurs

En bref

• Adresse : https://api.leflechoir.fr/v1, en JSON.
• Référence complète : la notice (GET /v1) et la spécification OpenAPI.
• Sans clé pour essayer ; une clé gratuite, créée dans ton compte, pour davantage.
• Les grilles sont à toi, y compris pour un usage commercial ; chaque dessin est signé. Appeler l'API vaut acceptation de ses conditions.

Sans écrire de code

Dans Claude, ChatGPT ou Le Chat : ajoute le connecteur https://mcp.leflechoir.fr/mcp (la marche à suivre). L'assistant appelle alors l'API lui-même.

Le lien préparé : un assistant sans connecteur ne peut pas appeler l'API depuis une conversation, mais il peut donner un lien qui prépare le générateur du site. Le générateur du site s'ouvre avec ces réglages et lance la grille aussitôt, sans compte ni clic.

https://leflechoir.fr/creer?taille=moyenne&mots=eric,anniversaire,gateau&mystere=BRAVO

• mots : les mots à placer, séparés par des virgules (60 au plus)
• taille : petite, moyenne ou grande, ou une taille comme 10x10 (de 5 à 20 cases de côté)
• mystere : un mot mystère, à trouver avec les lettres des cases numérotées
• niveau : facile, moyen ou difficile
• lang : fr (les grilles sont en français)

Une grille en quatre appels

1. Demande la grille : le moteur la construit en tâche de fond.

curl -i -X POST https://api.leflechoir.fr/v1/grids \
  -H "Content-Type: application/json" \
  -d '{"lang": "fr", "width": 10, "height": 10, "level": "medium",
       "required_words": ["Eric"], "preferred_words": ["anniversaire", "gateau", "bougie"]}'

Réponse 202, avec l'identifiant (gen_…), l'adresse à relire (Location) et le délai en secondes (Retry-After).

2. Relis-la jusqu'à ce qu'elle soit finie (quelques secondes) :

curl https://api.leflechoir.fr/v1/grids/gen_XXXXXXXXXXXX

Avec "status": "done", la réponse porte le fichier de grille (grid) : ses lignes, et pour chaque mot sa place, sa direction et le nombre de caractères que tient sa définition (clue_max_chars). Il est à toi : nous l'effaçons au bout de 24 heures.

3. Écris une définition par mot, et fais-les vérifier :

curl -X POST https://api.leflechoir.fr/v1/clues/check \
  -H "Content-Type: application/json" \
  -d '{"id": "gen_XXXXXXXXXXXX",
       "clues": [{"answer": "ERIC", "clue": "Prénom du jour"}, {"answer": "GATEAU", "clue": "Porte des bougies"}]}'

Sans erreur, la réponse donne links.play (jouer en ligne) et links.open (imprimer, PDF, modifier), et le fichier complet avec ses définitions. On peut aussi envoyer le fichier entier (grid) au lieu de l'identifiant.

4. Dessine-la, à remplir ou sa solution :

curl -X POST https://api.leflechoir.fr/v1/render \
  -H "Content-Type: application/json" \
  -d '{"grid": { …le fichier de grille… }, "format": "png", "view": "puzzle"}' -o grille.png

Les routes

• GET /v1 — La notice : les règles du genre, le style des définitions par langue et par niveau, les formats, tes quotas. À lire avant le premier appel (un assistant IA y trouve tout ce qu'il lui faut).
• GET /v1/openapi.json — La spécification OpenAPI 3.1, pour générer un client ou décrire l'API à un agent.
• GET /v1/limits — Tes quotas et ce que tu en as utilisé.
• POST /v1/grids — Lance la construction d'une grille autour de tes mots. Répond 202 avec l'adresse à relire (Location) et le délai (Retry-After).
• GET /v1/grids/{id} — L'état de la construction : en attente, en cours, finie (avec le fichier de grille) ou en échec (avec sa raison).
• POST /v1/clues/check — Vérifie tes définitions : chacune doit tenir dans sa case et ne pas donner la réponse ; les alertes de style sont des conseils. Sans erreur, renvoie les liens pour jouer la grille ou l'imprimer.
• POST /v1/render — Dessine la grille, à remplir ou sa solution, en SVG, PNG ou PDF, signée.

Les réglages d'une grille

Le corps de POST /v1/grids ; un champ inconnu est refusé, et nommé.

• lang — La langue de la grille, obligatoire : fr (l'allemand et l'anglais suivront).
• width, height — La taille, de 5 à 15 cases de côté (10 × 10 par défaut). Les plus sûres : 8 × 8, 10 × 10, 9 × 12, 12 × 12, 12 × 15.
• level — easy, medium ou hard (medium par défaut). Le niveau facile prend des mots plus courants ; pour les autres, la difficulté est dans les définitions.
• required_words — Jusqu'à 10 mots tous placés, ou la construction échoue (must_words_unplaced).
• preferred_words — Jusqu'à 60 mots placés quand c'est possible : le thème de la grille.
• mystery_word — Un mot mystère de 3 à 20 lettres : ses cases sont numérotées dans la grille.
• author — Le nom dont la grille est signée (« Grille de Mamie Jo »), sur le dessin et sur le site.
• seed — Un entier : mêmes réglages et même graine, même grille.

La clé et les quotas

La clé se crée dans ton compte, une fois l'adresse e-mail confirmée, et s'envoie dans l'en-tête Authorization: Bearer flk_…. Elle vaut pour toutes les langues.

Une grille à la fois par appelant ; 5 secondes de calcul au plus par grille. Les valeurs en vigueur : GET /v1/limits. Le site passe d'abord : quand il est très demandé, l'API attend son tour.

Les erreurs

Toujours du JSON : {"error": "…", "reason": "…"}. Le message suit l'en-tête Accept-Language (fr, en, de) ; le code reason ne change jamais : c'est sur lui qu'un programme décide. Un refus pour quota porte l'en-tête Retry-After.

• invalid_request — Un champ manque, est mal formé ou inconnu : le message le nomme.
• size_out_of_range — La taille sort des bornes (5 à 15 cases de côté).
• invalid_letters, word_length — Un mot a des lettres hors de l'alphabet de la langue, ou une longueur impossible.
• generation_in_progress — Une de tes grilles est encore en construction : une à la fois.
• quota_minute, quota_day, quota_words — Un quota est atteint : attends le délai de Retry-After.
• busy, api_paused, lang_unavailable — Le serveur sert d'abord le site : réessaie plus tard.
• must_words_unplaced, no_solution, timeout — La construction a échoué : moins de mots imposés, ou une autre taille.
• invalid_api_key — La clé est fausse ou révoquée.

Le fichier de grille

Un JSON public et versionné ("format": "flechoir.grid", "version": 1) : les lignes de la grille (# pour une case de définition, une lettre sinon), et les mots, chacun avec sa place (x, y), sa direction (across ou down) et sa définition (clue). Les champs inconnus sont ignorés, et les cases de définition recalculées : un fichier venu d'ailleurs se vérifie et se dessine aussi. Son schéma complet est dans la spécification OpenAPI (GridFileIn).

Bon à savoir

• Envoie un en-tête User-Agent qui nomme ton application : certains clients par défaut sont refusés par la protection du serveur.
• L'API ne cherche pas de mots et ne donne pas de listes : pour cela, il y a la recherche par motif du site.
• Les définitions ne servent qu'à vérifier et dessiner la grille : jamais gardées, jamais réutilisées (confidentialité).
• Une question, un bug : écris-nous.