L'API

← Retour au calendrier

Tu veux piloter APES autrement que depuis Together ? Donne le lien de cette page — https://apes.lirlya.fr/info — à ton agent : tout ce qu'il lui faut est ici, et il devrait se débrouiller seul.

Une API publique et versionnée, en deux moitiés : lire tout ce que montre le calendrier, sans rien demander ; écrire ses propres dispos, avec un token. Les statuts sont déjà calculés côté lecture : rien à recoder. Dans la v1, il n'y aura que des ajouts, jamais de rupture. Les membres sont désignés par un identifiant opaque et leur nom d'affichage, jamais par leur compte Discord.

Lire, sans rien demander

GET /api/v1/members · GET /api/v1/availability?from=&to= · GET /api/v1/status/now · GET /api/v1/voice

Écrire ses dispos, avec un token

Le token donne accès à tes propres dispos, rien d'autre : ni ton seuil, ni ton nom, ni /ping, ni les dispos d'un autre membre. C'est fait pour un script, un raccourci ou une automatisation — pas pour une page web.

Le token

L'obtenir: Écris au bot en message privé, en langage naturel : « donne-moi un token pour l'API ». Il te le montre une seule fois.
Le remplacer: Redemande-en un : l'ancien cesse de fonctionner immédiatement, mets à jour tes clients.
Le couper: « révoque mon token ». « montre ma config » indique son état et son dernier usage.
L'envoyer: En-tête Authorization: Bearer sj_… sur chaque requête, en HTTPS uniquement.

Les routes

Base : https://apes.lirlya.fr

GET /api/me/v1/: qui je suis : {"id": "…", "display_name": "…"} (le même identifiant opaque que la lecture).
GET /api/me/v1/availability: mes déclarations brutes, soirée par soirée, d'aujourd'hui à +366 jours. Une date absente n'est pas déclarée : elle vaut « inconnu ». À lire avant d'écrire : une écriture remplace la soirée entière.
PUT /api/me/v1/day/{date}: déclare la soirée date (AAAA-MM-JJ), d'aujourd'hui à +366 jours.
POST /api/me/v1/repeat: les mêmes plages sur plusieurs soirées : weekdays (0 = lundi … 6 = dimanche), from_date (absent = la soirée en cours) et until, obligatoire. Un an au plus par appel. Il n'y a pas d'« habitude » stockée : cet appel écrit de vraies soirées, une par date.

Corps d'une écriture, Content-Type: application/json :

{"ranges": [{"start": "20:00", "end": "02:00", "status": 66}]}

{"weekdays": [1, 3], "until": "2027-02-07", "mode": "skip",
 "ranges": [{"start": "20:00", "end": "22:00", "status": 66}]}

Les règles qui piègent

Une écriture remplace la soirée entière : envoie toutes les plages que tu veux garder. "mode" change ça : "merge" masque seulement les heures données et laisse le reste, "skip" laisse intactes les soirées qui portent déjà quelque chose.
Le passé ne bouge plus : sur la soirée en cours, les heures déjà écoulées (à la demi-heure près) gardent ce qu'elles portaient, quel que soit le mode. Une écriture qui ne toucherait que ces heures-là est refusée (422) ; sur une répétition, la soirée en cours est alors laissée telle quelle et listée dans skipped.
"ranges": [] efface : la soirée redevient « inconnu ». Ce n'est pas « non dispo » — pour ça, déclare une plage au statut 0.
HH:MM en heure de Paris, aligné sur la demi-heure (:00 ou :30). 24:00 = minuit.
Dans les réponses, les heures après minuit s'écrivent en continu : 24:00 = minuit, 25:00 = 1h du matin, jusqu'à 27:00 = 3h. Cette forme est acceptée en entrée : tu peux renvoyer telle quelle une liste ranges reçue.
end <= start = passage de minuit : "20:00" → "02:00" est une seule plage, sur la soirée du jour de départ. Une soirée va jusqu'à 03:00.
Des plages toutes avant 03:00 appartiennent à la soirée de la veille : elles y sont écrites en plus de ce qui y était déjà (pas en remplacement), et la réponse te le dit. Mélanger petit matin et soirée dans un même appel est refusé.
status de 0 à 100 : 0 non dispo · 33 possible · 66 probable · 100 confirmé, ou toute valeur. null = « inconnu » déclaré : tu dis que tu ne sais pas encore, ce qui n'est pas 0.
Une soirée qui porte au moins une plage est déterminée : ce qu'elle ne couvre pas vaut 0. Une soirée sans aucune plage est « inconnu ». C'est toute la règle.
Une soirée se déclare d'aujourd'hui (la soirée en cours, jusqu'à 03:00) à +366 jours.

La réponse

La soirée réellement écrite et ses plages. La date renvoyée peut différer de celle demandée (règle de la veille). Pour une répétition, dates liste les soirées écrites et skipped celles qui ont été laissées intactes.

{"date": "2026-11-10", "ranges": [{"start": "21:00", "end": "25:00", "status": 100}]}

Les erreurs

401: token absent, inconnu ou révoqué : demande-en un au bot en message privé.
422: règle non respectée. detail est une phrase et code une étiquette stable quand c'est une règle métier (chevauchement, demi-heure, date passée…) ; detail est une liste quand le corps est mal formé.
429: tu vas trop vite : ta requête n'est pas invalide, ralentis et réessaie. Le rythme soutenu autorisé est de deux requêtes par seconde.

Exemple complet : lire, puis écrire

Remplace <TON_TOKEN> par ton token. Les deux commandes se suffisent.

curl https://apes.lirlya.fr/api/me/v1/availability \
  -H "Authorization: Bearer <TON_TOKEN>"

curl -X PUT https://apes.lirlya.fr/api/me/v1/day/2026-11-10 \
  -H "Authorization: Bearer <TON_TOKEN>" -H "Content-Type: application/json" \
  -d '{"ranges":[{"start":"21:00","end":"01:00","status":100}]}'