Développeurs

L'API CoolRoom

Construis ton app, ton widget ou ton script sur les données de CoolRoom : devoirs, notes, emploi du temps, cours, exercices… Toujours avec l'accord de l'élève, en lecture seule, avec des limites qu'il choisit.

Adresse de l'APIhttps://api.coolroom.app/api/open/v1

Démarrer

1. Crée une clé
Dans l'appli : Réglages › API et applications › Créer une clé. Coche les données, choisis l'expiration et les limites. Copie la clé : elle commence par crk_ et ne s'affiche qu'une fois.
2. Appelle l'API
Envoie-la dans l'en-tête Authorization de chaque requête. Les réponses sont en JSON, les dates en ISO 8601 (UTC).
3. Pour une app publique
Ne demande jamais de clé à tes utilisateurs : utilise le lien « Se connecter avec CoolRoom ». L'élève accepte en un clic et ton app reçoit sa clé.

La doc en un zip

Toute cette page en Markdown, prête à donner à une IA : un fichier par partie, plus tout en un seul fichier (coolroom-api.md). Toujours à jour avec la page.

Télécharger le zip Juste le fichier .md

Ta première requête

curl

curl "https://api.coolroom.app/api/open/v1/homework" \
  -H "Authorization: Bearer crk_…"

JavaScript

const res = await fetch('https://api.coolroom.app/api/open/v1/homework', {
  headers: { Authorization: `Bearer ${process.env.COOLROOM_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.message}`);
for (const c of data.classes) console.log(c.className, c.homework.length);

Authentification

Chaque route de /api/open/v1 demande une clé, dans Authorization: Bearer crk_… (ou X-API-Key: crk_…). Une clé lit les données d'un seul compte, seulement ses scopes, et jamais rien d'autre de CoolRoom. L'API est en lecture seule : aucune route n'écrit, n'envoie ni ne supprime de données de l'élève.

HTTP

Authorization: Bearer crk_Xb7Qm2LpV0x9…

Une clé, c'est un mot de passe : jamais dans le code d'une page web publique, jamais dans un dépôt Git.
CoolRoom ne garde que l'empreinte (SHA-256) de la clé : si elle est perdue, l'élève en crée une autre.
L'élève voit chaque clé dans Réglages › API et applications et peut la retirer à tout moment.
Ton app reçoit exactement ce que l'élève voit dans l'appli : mêmes classes, mêmes droits. Jamais ses mots de passe ni ses identifiants Pronote.

Se connecter avec CoolRoom

Le moyen le plus rapide pour un élève : ton app ouvre un lien, l'élève voit le nom de ton app, ce qu'elle veut lire et pour combien de temps, puis touche Autoriser. CoolRoom renvoie vers ton app avec un code à usage unique, que ton serveur (ou ton app, avec PKCE) échange contre la clé.

GET/api/public/connectsans clé

1. Le lien « Se connecter avec CoolRoom »

Ouvre-le dans le navigateur de l’élève. CoolRoom vérifie les paramètres puis montre l’écran d’autorisation (l’élève se connecte s’il faut). Un lien cassé répond 400 avec la raison.

Paramètres
`app_name`obligatoire	Le nom de ton app (2 à 60 caractères), montré à l’élève.
`redirect_uri`obligatoire	Où renvoyer l’élève : https://…, http://localhost…, ou le schéma de ton app (monapp://callback). Sans #.
`scope`obligatoire	Les scopes, séparés par des virgules.
`state`	Renvoyé tel quel : vérifie-le au retour (200 caractères au plus).
`code_challenge`	PKCE : base64url(SHA-256(code_verifier)). Recommandé, obligatoire pour une app sans serveur.
`code_challenge_method`	S256 (le seul accepté).
`expires_in`	Durée de vie de la clé en secondes (3 600 à 31 622 400). Sans : jusqu’à ce que l’élève la retire.
`hourly_limit`	Requêtes par heure (1 à 3 600, 600 par défaut).
`total_limit`	Requêtes en tout (sans : illimité).

Requête

curl "https://api.coolroom.app/api/public/connect?app_name=Agenda%20Plus&redirect_uri=https%3A%2F%2Fagenda-plus.example%2Fcallback&scope=homework%2Ctimetable&state=k8Jd2&code_challenge=ITAt2F6NLydvh8G3CenAG9Ty-j_gUaFU1f886B2WqE0&code_challenge_method=S256&expires_in=2592000"

302 · Redirection vers l'écran d'autorisation.

GET{redirect_uri}sans clé

2. Le retour vers ton app

Autorisé : ?code=…&state=…. Refusé : ?error=access_denied&state=…. Le code marche une fois, pendant 10 minutes.

Requête

https://agenda-plus.example/callback?code=Qm9uam91ciBkw6l2ZWxvcHBldXI&state=k8Jd2

POST/api/public/connect/tokensans clé

3. Échanger le code contre la clé

redirectUri doit être exactement celle du lien. codeVerifier est obligatoire si le lien avait un code_challenge. Garde apiKey en lieu sûr : elle n’est plus jamais redonnée.

Paramètres
`code`obligatoire	Le code reçu.
`redirectUri`obligatoire	La même que dans le lien.
`codeVerifier`	Le secret PKCE (43 à 128 caractères).

Requête

curl -X POST "https://api.coolroom.app/api/public/connect/token" \
  -H "Content-Type: application/json" \
  -d '{"code":"Qm9uam91ciBkw6l2ZWxvcHBldXI","redirectUri":"https://agenda-plus.example/callback","codeVerifier":"dBjftJeZ4CVP-mJ92K9eQ_Ft_3zsHpPhEbbsvh3JJPA"}'

Réponse · 200

{
  "apiKey": "crk_Xb7Qm2LpV0x9…",
  "keyId": "0f3b2a1c-9e8d-4c7b-a6f5-e4d3c2b1a090",
  "scopes": [
    "homework",
    "timetable"
  ],
  "expiresAt": "2026-11-20T08:12:40Z",
  "hourlyLimit": 600,
  "totalLimit": null,
  "user": {
    "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
    "displayName": "Léa Martin",
    "accountType": "STUDENT"
  }
}

GET/api/public/connect/scopessans clé

La liste des scopes

Chaque scope avec son nom et sa phrase en français, comme l’élève les voit.

Requête

curl "https://api.coolroom.app/api/public/connect/scopes"

Réponse · 200

[
  {
    "key": "homework",
    "label": "Devoirs",
    "description": "Les devoirs de tes classes et ce que tu as fini"
  }
]

PKCE en JavaScript

Pour une app mobile ou une page sans serveur : crée un secret au hasard, garde-le, envoie son empreinte dans le lien, puis le secret à l'échange. Même si quelqu'un vole le code, il ne peut rien en faire.

JavaScript

// 1. Avant d’ouvrir le lien
const b64url = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = b64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));
const state = b64url(crypto.getRandomValues(new Uint8Array(16)));
sessionStorage.setItem('coolroom', JSON.stringify({ verifier, state }));
location.href = 'https://api.coolroom.app/api/public/connect?' + new URLSearchParams({
  app_name: 'Agenda Plus',
  redirect_uri: 'https://agenda-plus.example/callback',
  scope: 'homework,timetable',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
});

// 2. Sur https://agenda-plus.example/callback
const q = new URLSearchParams(location.search);
const saved = JSON.parse(sessionStorage.getItem('coolroom'));
if (q.get('state') !== saved.state) throw new Error('state');
if (q.get('error')) throw new Error(q.get('error')); // access_denied
const res = await fetch('https://api.coolroom.app/api/public/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: q.get('code'),
    redirectUri: 'https://agenda-plus.example/callback',
    codeVerifier: saved.verifier,
  }),
});
const { apiKey, user } = await res.json();

Limites

Chaque clé a ses limites, choisies à la création (dans l'appli, ou par les paramètres du lien) :

Par heure	1 à 3 600 requêtes (600 par défaut). Au-delà : 429 avec Retry-After.
En tout	Facultatif. Une fois atteint : 429 quota_exceeded, pour toujours.
Expiration	1 heure à 366 jours, ou jamais. Après : 401 key_expired.
Clés par compte	20 clés actives au plus.

Chaque réponse dit où tu en es : X-RateLimit-Limit, X-RateLimit-Remaining (dans l'heure) et X-Total-Remaining (si la clé a une limite totale).

Ton app peut aussi se limiter elle-même : PATCH /key pour réduire ses scopes, son expiration ou ses limites, DELETE /key pour rendre la clé (un bouton « Déconnecter » dans ton app). Jamais pour en avoir plus. PATCH /key · DELETE /key

Erreurs

Une erreur répond toujours avec la même forme. Teste code, affiche message (en français).

JSON

{
  "status": 403,
  "code": "insufficient_scope",
  "message": "Cette clé n’a pas le scope « grades » (Notes)",
  "path": "/api/open/v1/grades",
  "timestamp": "2026-10-21T17:30:00Z"
}

Statut	code	Quand
400	`invalid_request`	Un paramètre manque ou ne va pas (le message dit lequel).
400	`invalid_scope`	Un scope inconnu dans le lien de connexion.
400	`invalid_grant`	Code de connexion inconnu, déjà utilisé, expiré, ou redirectUri / codeVerifier différents.
401	`missing_key`	Pas de clé dans la requête.
401	`invalid_key`	Clé inconnue ou mal formée (une clé commence par crk_).
401	`key_revoked`	L’élève (ou ton app) a révoqué la clé.
401	`key_expired`	La clé a passé sa date d’expiration.
403	`insufficient_scope`	La clé n’a pas le scope de cette route.
403	`cannot_widen`	PATCH /key ne peut que réduire une clé.
403	`forbidden`	L’élève n’a pas accès à cette chose dans l’appli non plus.
404	`not_found`	Introuvable, ou pas à cet élève.
405	`method_not_allowed`	L’API est en lecture seule.
409	`too_many_keys`	L’élève a déjà 20 clés actives.
429	`rate_limited`	Limite par heure atteinte : attends Retry-After secondes.
429	`quota_exceeded`	La clé a utilisé toutes ses requêtes (limite totale).
500	`server_error`	Erreur de notre côté. Réessaie plus tard.

Scopes

Les données qu'une clé peut lire. Dans le lien, sépare-les par des virgules (scope=homework,grades) ; all les demande toutes.

Scope	Donne accès à
`profile`	Profil · Nom, bio, type de compte, langue.
`email`	Adresse email · Ajoute l’adresse email au profil (avec profile).
`classes`	Classes · Les classes, leurs membres et leurs annonces.
`homework`	Devoirs · Les devoirs de chaque classe, faits ou non, votes et notes.
`grades`	Notes · Les notes, les moyennes de classe et les objectifs.
`timetable`	Emploi du temps · Les cours, salles, profs, annulations et retenues.
`school_life`	Vie scolaire · Absences et retards.
`mail`	Messagerie · Les mails de l’ENT (Pronote, Skolengo), en lecture.
`school_accounts`	Comptes scolaires · Les comptes reliés et leur synchro. Jamais les identifiants.
`chat`	Chat de classe · Les messages des chats de classe.
`cours`	Cours · La bibliothèque de cours, chaque cours en Markdown, le programme.
`exercises`	Exercices · Entraînements : résultats carte par carte, erreurs, points faibles.
`flashcards`	Flash cards · Les paquets de cartes et les parties jouées.
`progress`	Niveau et CC · Niveau, XP, CC, série, saison.
`notifications`	Notifications · Les 100 dernières notifications.
`ai`	IA · La conversation avec l’IA de CoolRoom.
`family`	Famille · Pour un compte parent : notes, devoirs et emploi du temps des enfants reliés.

Routes

Toutes les routes, avec leur requête et un exemple de réponse. Les élèves et les identifiants des exemples sont inventés. De nouveaux champs peuvent arriver dans v1 ; aucun ne disparaîtra ni ne changera de nom.

La clé elle-mêmetoute clé

Sans scope : toute clé valide peut lire ses limites, les réduire, ou se révoquer (un bouton « Déconnecter » dans ton app).

GET/api/open/v1/key

Lire la clé

Ses scopes, son expiration, ses limites et ce qui reste dans l’heure.

Requête

curl "https://api.coolroom.app/api/open/v1/key" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "id": "0f3b2a1c-9e8d-4c7b-a6f5-e4d3c2b1a090",
  "name": "Agenda Plus",
  "prefix": "crk_Xb7Qm2Lp",
  "scopes": [
    "homework",
    "timetable"
  ],
  "createdAt": "2026-10-21T08:12:40Z",
  "expiresAt": "2026-11-20T08:12:40Z",
  "hourlyLimit": 600,
  "hourlyRemaining": 597,
  "totalLimit": null,
  "usedRequests": 214
}

PATCH/api/open/v1/key

Réduire la clé

Ton app se limite elle-même : moins de scopes, une expiration plus proche, des limites plus basses. Jamais l’inverse (403 cannot_widen). Ce que tu n’envoies pas ne change pas.

Paramètres
`scopes`corps	Une partie des scopes actuels.
`expiresAt`corps	Date ISO 8601, dans le futur et avant l’expiration actuelle.
`hourlyLimit`corps	De 1 à la limite actuelle.
`totalLimit`corps	Requêtes en tout, au plus la limite actuelle.

Requête

curl -X PATCH "https://api.coolroom.app/api/open/v1/key" \
  -H "Authorization: Bearer $COOLROOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["homework"],"hourlyLimit":100,"totalLimit":5000}'

Réponse · 200

{
  "id": "0f3b2a1c-9e8d-4c7b-a6f5-e4d3c2b1a090",
  "name": "Agenda Plus",
  "prefix": "crk_Xb7Qm2Lp",
  "scopes": [
    "homework"
  ],
  "createdAt": "2026-10-21T08:12:40Z",
  "expiresAt": "2026-11-20T08:12:40Z",
  "hourlyLimit": 100,
  "hourlyRemaining": 97,
  "totalLimit": 5000,
  "usedRequests": 214
}

DELETE/api/open/v1/key

Révoquer la clé

La clé s’arrête tout de suite, pour toujours.

Requête

curl -X DELETE "https://api.coolroom.app/api/open/v1/key" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 204 · Pas de contenu.

Profilprofile

Le compte derrière la clé.

GET/api/open/v1/me

Le compte

accountType vaut STUDENT ou PARENT. email et emailVerified ne sont remplis qu’avec le scope email (null sinon).

Requête

curl "https://api.coolroom.app/api/open/v1/me" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
  "displayName": "Léa Martin",
  "bio": "Seconde 4, team SVT",
  "accountType": "STUDENT",
  "locale": "fr",
  "avatarIconId": "fox",
  "memberSince": "2026-09-02T17:21:05Z",
  "email": "[email protected]",
  "emailVerified": true
}

Classesclasses

Les classes de l’élève. Le code d’invitation n’est jamais donné.

GET/api/open/v1/classes

Mes classes

myRole : MEMBER, CO_ADMIN ou CLASS_MASTER. status : APPROVED, LOCKED, ARCHIVED…

Requête

curl "https://api.coolroom.app/api/open/v1/classes" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
    "name": "2nde 4",
    "description": "La meilleure classe du lycée",
    "etablissementId": "e7ab1100-4c3d-4e2f-9a8b-7c6d5e4f3a2b",
    "etablissementName": "Lycée Jean Zay",
    "classMasterName": "Tom Durand",
    "status": "APPROVED",
    "memberCount": 28,
    "myRole": "MEMBER",
    "subjectColors": {
      "Mathématiques": "#3B82F6",
      "SVT": "#22C55E"
    },
    "languages": {
      "LV2": [
        "ESPAGNOL LV2",
        "ALLEMAND LV2"
      ]
    }
  }
]

GET/api/open/v1/classes/{classId}

Une classe

Même forme qu’un élément de /classes.

Paramètres
`classId`cheminobligatoire	Une classe de l’élève.

Requête

curl "https://api.coolroom.app/api/open/v1/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "id": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
  "name": "2nde 4",
  "memberCount": 28,
  "myRole": "MEMBER",
  "…": "…"
}

GET/api/open/v1/classes/{classId}/members

Les membres

status : ONLINE, FOCUS, IN_LESSON, AWAY ou OFFLINE. lastSeenAt est arrondi à 5 minutes, null après une semaine.

Requête

curl "https://api.coolroom.app/api/open/v1/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/members" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "userId": "a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d",
    "displayName": "Tom Durand",
    "avatarIconId": "owl",
    "avatarPhotoVersion": null,
    "bio": "Délégué",
    "role": "CLASS_MASTER",
    "online": true,
    "muted": false,
    "inFocus": false,
    "status": "ONLINE",
    "lastSeenAt": "2026-10-21T15:40:00Z",
    "frame": null
  }
]

GET/api/open/v1/classes/{classId}/announcements

Les annonces

Les annonces de la classe, les plus récentes d’abord.

Requête

curl "https://api.coolroom.app/api/open/v1/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/announcements" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "title": "Sortie au musée jeudi",
    "body": "Rendez-vous 8 h devant le lycée, prévoyez un pique-nique.",
    "authorName": "Tom Durand",
    "authorRole": "CLASS_MASTER",
    "createdAt": "2026-10-20T18:05:00Z",
    "seen": true,
    "canDelete": false
  }
]

Chat de classechat

Les messages, du plus ancien au plus récent, par pages.

GET/api/open/v1/classes/{classId}/chat

Les messages

type : TEXT, LESSON, FLASHCARDS, GIVEAWAY, MEDIA, STICKER, ASSISTANT… Les photos et vidéos ne sont pas servies par l’API (media donne seulement leurs infos).

Paramètres
`before`requête	Date ISO : les messages avant (page précédente).
`limit`requête	1 à 100.

Requête

curl "https://api.coolroom.app/api/open/v1/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/chat?limit=50" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "pinned": null,
  "messages": [
    {
      "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
      "type": "TEXT",
      "author": {
        "id": "a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d",
        "displayName": "Tom Durand",
        "avatarIconId": "owl",
        "avatarPhotoVersion": null,
        "frame": null
      },
      "body": "Quelqu’un a compris l’exo 14 ?",
      "createdAt": "2026-10-21T16:02:33Z",
      "quote": null,
      "reactions": [
        {
          "emoji": "👀",
          "count": 3,
          "names": [
            "Léa",
            "Inès",
            "Hugo"
          ],
          "reactedByMe": true
        }
      ],
      "mentionedRaw": null,
      "pinned": false,
      "mine": false,
      "deck": null,
      "giveaway": null,
      "lesson": null,
      "sources": null,
      "media": null,
      "sticker": null
    }
  ],
  "typing": []
}

Devoirshomework

source : OFFICIAL (Pronote, ENT) ou MANUAL (ajouté par un élève). status : OFFICIEL, CONFIRME ou A_VERIFIER. done et snoozed sont propres à l’élève.

GET/api/open/v1/homework

Les devoirs, par classe

Toutes les classes, ou une seule avec ?classId=.

Paramètres
`classId`requête	Une seule classe.

Requête

curl "https://api.coolroom.app/api/open/v1/homework" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "classes": [
    {
      "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
      "className": "2nde 4",
      "homework": [
        {
          "id": "9d2f7a10-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
          "subject": "Mathématiques",
          "title": "Exercices 12 à 15 p. 84",
          "description": "Faire les exercices sur les fonctions affines.",
          "dueAt": "2026-10-23T06:00:00Z",
          "source": "OFFICIAL",
          "status": "OFFICIEL",
          "isExam": false,
          "done": false,
          "completedAt": null,
          "snoozed": false,
          "submitterId": null,
          "submitterName": null,
          "confirmations": 0,
          "disagreements": 0,
          "myVote": null,
          "latestNote": "Le 15 b) est corrigé en classe",
          "latestNoteAuthor": "Tom",
          "photoVersion": null
        }
      ]
    }
  ]
}

GET/api/open/v1/homework/{homeworkId}

Un devoir

Le devoir et toutes ses notes.

Requête

curl "https://api.coolroom.app/api/open/v1/homework/9d2f7a10-3b4c-4d5e-8f6a-7b8c9d0e1f2a" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "homework": {
    "id": "9d2f7a10-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
    "subject": "Mathématiques",
    "title": "Exercices 12 à 15 p. 84",
    "description": "Faire les exercices sur les fonctions affines.",
    "dueAt": "2026-10-23T06:00:00Z",
    "source": "OFFICIAL",
    "status": "OFFICIEL",
    "isExam": false,
    "done": false,
    "completedAt": null,
    "snoozed": false,
    "submitterId": null,
    "submitterName": null,
    "confirmations": 0,
    "disagreements": 0,
    "myVote": null,
    "latestNote": "Le 15 b) est corrigé en classe",
    "latestNoteAuthor": "Tom",
    "photoVersion": null
  },
  "notes": [
    {
      "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
      "authorId": "a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d",
      "authorName": "Tom",
      "authorAvatarIconId": "owl",
      "authorPhotoVersion": null,
      "body": "Le 15 b) est corrigé en classe",
      "createdAt": "2026-10-21T12:30:00Z",
      "mine": false,
      "canDelete": false
    }
  ],
  "canEdit": false,
  "canVote": false,
  "confirmationThreshold": 3
}

Notesgrades

Les notes de l’élève, les plus récentes d’abord. Les nombres sont des décimaux.

GET/api/open/v1/grades

Les notes

revealed : déjà ouverte dans l’appli. La valeur est toujours donnée.

Requête

curl "https://api.coolroom.app/api/open/v1/grades" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "3a4b5c6d-7e8f-4a1b-9c2d-3e4f5a6b7c8d",
    "subject": "Physique-Chimie",
    "title": "Contrôle : les ondes",
    "value": 15.5,
    "outOf": 20,
    "classAverage": 12.25,
    "classMin": 6,
    "classMax": 18.5,
    "coefficient": 2,
    "period": "Trimestre 1",
    "date": "2026-10-17",
    "revealed": true,
    "masked": false
  }
]

GET/api/open/v1/grades/goals

Les objectifs

subject vide = la moyenne générale.

Requête

curl "https://api.coolroom.app/api/open/v1/grades/goals" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "subject": "",
    "target": 14
  },
  {
    "subject": "Mathématiques",
    "target": 15
  }
]

Emploi du tempstimetable

Les heures sont en UTC (Z). detention : une retenue.

GET/api/open/v1/timetable

Les cours entre deux dates

De from à to inclus, 62 jours au plus (heure de Paris).

Paramètres
`from`requêteobligatoire	AAAA-MM-JJ.
`to`requêteobligatoire	AAAA-MM-JJ.

Requête

curl "https://api.coolroom.app/api/open/v1/timetable?from=2026-10-19&to=2026-10-25" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "subject": "Histoire-Géographie",
    "teacher": "M. Laurent",
    "room": "B204",
    "startAt": "2026-10-22T07:00:00Z",
    "endAt": "2026-10-22T08:00:00Z",
    "canceled": false,
    "note": null,
    "detention": false
  },
  {
    "id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
    "subject": "Anglais",
    "teacher": "Mme Smith",
    "room": "A12",
    "startAt": "2026-10-22T08:00:00Z",
    "endAt": "2026-10-22T09:00:00Z",
    "canceled": true,
    "note": "Prof absente",
    "detention": false
  }
]

Vie scolaireschool_life

kind : ABSENCE ou DELAY. Les retenues sont dans l’emploi du temps.

GET/api/open/v1/school-life

Absences et retards

Les plus récents d’abord.

Requête

curl "https://api.coolroom.app/api/open/v1/school-life" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c",
    "kind": "DELAY",
    "title": "Retard",
    "reason": "Transport",
    "detail": null,
    "giver": null,
    "startAt": "2026-10-20T07:05:00Z",
    "endAt": null,
    "scheduledAt": null,
    "durationMinutes": 10,
    "justified": true
  }
]

Messageriemail

Les mails de l’ENT, en lecture. Les lire ici ne les marque pas comme lus.

GET/api/open/v1/mail

La boîte de réception

type : TEACHER, ADMIN, SYSTEM ou OTHER. q cherche dans le sujet, l’expéditeur et le texte.

Paramètres
`q`requête	Recherche.
`type`requête	Filtre par expéditeur.

Requête

curl "https://api.coolroom.app/api/open/v1/mail?type=TEACHER" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "messages": [
    {
      "id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",
      "provider": "PRONOTE",
      "providers": [
        "PRONOTE"
      ],
      "subject": "Conseil de classe",
      "snippet": "Bonjour, le conseil de classe aura lieu le…",
      "senderName": "Mme Bernard",
      "senderType": "TEACHER",
      "receivedAt": "2026-10-21T10:15:00Z",
      "read": false,
      "messageCount": 1,
      "sharedAt": null
    }
  ],
  "unreadCount": 1,
  "countsByType": {
    "TEACHER": 4,
    "ADMIN": 2,
    "SYSTEM": 0,
    "OTHER": 1
  }
}

GET/api/open/v1/mail/{mailId}

Un mail et sa conversation

Peut prendre quelques secondes la première fois (CoolRoom va chercher le texte chez Pronote ou Skolengo).

Requête

curl "https://api.coolroom.app/api/open/v1/mail/a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "mail": {
    "id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",
    "subject": "Conseil de classe",
    "senderName": "Mme Bernard",
    "…": "…"
  },
  "thread": [
    {
      "author": "Mme Bernard",
      "sentAt": "2026-10-21T10:15:00Z",
      "content": "Bonjour, le conseil de classe aura lieu le 4 décembre.",
      "fromMe": false
    }
  ]
}

Comptes scolairesschool_accounts

Les comptes reliés et leur synchro. Les identifiants ne sortent jamais du serveur.

GET/api/open/v1/school-accounts

Les comptes reliés

provider : PRONOTE, SKOLENGO ou PRONOTE_ENT_AURA. status : PENDING, CONNECTED, ERROR ou DISCONNECTED.

Requête

curl "https://api.coolroom.app/api/open/v1/school-accounts" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "b8c9d0e1-f2a3-4b4c-9d5e-6f7a8b9c0d1e",
    "provider": "PRONOTE",
    "status": "CONNECTED",
    "schoolLabel": "Lycée Jean Zay",
    "lastSyncAt": "2026-10-21T16:00:00Z",
    "lastLogonRefreshAt": "2026-10-21T16:04:00Z",
    "lastError": null,
    "syncMail": true,
    "syncHomework": true,
    "syncGrades": true,
    "syncTimetable": true,
    "available": [
      "GRADES",
      "HOMEWORK",
      "MAIL",
      "SCHOOL_LIFE",
      "TIMETABLE"
    ],
    "unavailable": []
  }
]

Courscours

La bibliothèque de cours de chaque classe. Chaque cours est du Markdown.

GET/api/open/v1/cours/classes/{classId}

La bibliothèque

Matières, dossiers, cours (sans leur texte), liens et tags.

Requête

curl "https://api.coolroom.app/api/open/v1/cours/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
  "className": "2nde 4",
  "subjects": [
    {
      "key": "svt",
      "name": "SVT",
      "icon": "microscope",
      "lessonCount": 7,
      "folderCount": 2,
      "fromTimetable": true,
      "lastUpdated": "2026-10-15T09:40:00Z"
    }
  ],
  "folders": [
    {
      "id": "1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
      "subjectKey": "svt",
      "parentId": null,
      "title": "Chapitre 2",
      "icon": null,
      "aiMade": false,
      "position": 0
    }
  ],
  "lessons": [
    {
      "id": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
      "subjectKey": "svt",
      "subjectName": "SVT",
      "folderId": null,
      "title": "La cellule, unité du vivant",
      "tags": [
        "chapitre-2",
        "cellule"
      ],
      "visibility": "CLASS",
      "status": "COMPLETE",
      "givenOn": "2026-10-14",
      "createdAt": "2026-10-14T16:02:11Z",
      "updatedAt": "2026-10-15T09:40:00Z",
      "revision": 3,
      "readingMinutes": 6,
      "author": {
        "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
        "displayName": "Léa Martin",
        "avatarIconId": "fox",
        "avatarPhotoVersion": null
      },
      "badges": [
        "NEW"
      ]
    }
  ],
  "links": [],
  "tags": [
    {
      "path": "cellule",
      "count": 3
    }
  ],
  "canManage": false
}

GET/api/open/v1/cours/classes/{classId}/search

Chercher dans les cours

Les cours qui parlent de q, avec un extrait.

Paramètres
`q`requêteobligatoire	Les mots cherchés.
`subject`requête	Une matière (subjectKey).

Requête

curl "https://api.coolroom.app/api/open/v1/cours/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/search?q=mitochondrie" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "lesson": {
      "id": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
      "subjectKey": "svt",
      "subjectName": "SVT",
      "folderId": null,
      "title": "La cellule, unité du vivant",
      "tags": [
        "chapitre-2",
        "cellule"
      ],
      "visibility": "CLASS",
      "status": "COMPLETE",
      "givenOn": "2026-10-14",
      "createdAt": "2026-10-14T16:02:11Z",
      "updatedAt": "2026-10-15T09:40:00Z",
      "revision": 3,
      "readingMinutes": 6,
      "author": {
        "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
        "displayName": "Léa Martin",
        "avatarIconId": "fox",
        "avatarPhotoVersion": null
      },
      "badges": [
        "NEW"
      ]
    },
    "excerpt": "…la **mitochondrie** produit l’énergie de la cellule…",
    "anchor": "les-organites",
    "score": 12
  }
]

GET/api/open/v1/cours/classes/{classId}/programme

Le programme

Chaque chapitre du programme officiel : COMPLETE, PARTIAL ou MISSING selon les cours de la classe.

Requête

curl "https://api.coolroom.app/api/open/v1/cours/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/programme" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
  "level": "SECONDE",
  "levelGuessed": false,
  "canManage": false,
  "levels": [
    "SIXIEME",
    "CINQUIEME",
    "QUATRIEME",
    "TROISIEME",
    "SECONDE",
    "PREMIERE",
    "TERMINALE"
  ],
  "subjects": [
    {
      "subjectKey": "svt",
      "subjectName": "SVT",
      "programmeKey": "SVT",
      "total": 8,
      "complete": 2,
      "partial": 1,
      "chapters": [
        {
          "id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
          "title": "La cellule",
          "state": "COMPLETE",
          "lessons": [
            {
              "id": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
              "title": "La cellule, unité du vivant",
              "pinned": false
            }
          ],
          "requestId": null
        }
      ]
    }
  ]
}

GET/api/open/v1/cours/lessons/{lessonId}

Un cours

Le cours en Markdown (blocs CoolRoom compris), son chemin, ses auteurs et ses liens.

Requête

curl "https://api.coolroom.app/api/open/v1/cours/lessons/5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
  "lesson": {
    "id": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
    "subjectKey": "svt",
    "subjectName": "SVT",
    "folderId": null,
    "title": "La cellule, unité du vivant",
    "tags": [
      "chapitre-2",
      "cellule"
    ],
    "visibility": "CLASS",
    "status": "COMPLETE",
    "givenOn": "2026-10-14",
    "createdAt": "2026-10-14T16:02:11Z",
    "updatedAt": "2026-10-15T09:40:00Z",
    "revision": 3,
    "readingMinutes": 6,
    "author": {
      "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
      "displayName": "Léa Martin",
      "avatarIconId": "fox",
      "avatarPhotoVersion": null
    },
    "badges": [
      "NEW"
    ]
  },
  "markdown": "# La cellule, unité du vivant\n\n## Le noyau\n\nLe noyau contient l’ADN…",
  "path": [
    "Chapitre 2"
  ],
  "contributors": [
    {
      "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
      "displayName": "Léa Martin",
      "avatarIconId": "fox",
      "avatarPhotoVersion": null
    }
  ],
  "links": [],
  "canEdit": false,
  "canDelete": false,
  "canManage": false,
  "social": {
    "thanks": 4,
    "thanked": true,
    "reported": false,
    "reports": 0,
    "hidden": false
  }
}

Exercicesexercises

S’entraîner et Apprendre : chaque carte d’entraînement, ce que l’élève a réussi ou raté, ses erreurs et ses points faibles.

GET/api/open/v1/exercises/classes/{classId}/results

Résultats carte par carte

Chaque carte jouée : vue, réussie, ratée (lapses), dans le carnet d’erreurs ou non, prochaine révision (dueOn). Les plus récentes d’abord.

Requête

curl "https://api.coolroom.app/api/open/v1/exercises/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/results" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
  "total": 42,
  "inMistakes": 3,
  "due": 5,
  "results": [
    {
      "itemKey": "svt-cellule-q3",
      "lessonId": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
      "lessonTitle": "La cellule, unité du vivant",
      "seen": 4,
      "correct": 2,
      "lapses": 2,
      "inMistakes": true,
      "reps": 0,
      "intervalDays": 1,
      "dueOn": "2026-10-22",
      "lastAnswerAt": "2026-10-21T17:10:00Z"
    }
  ]
}

GET/api/open/v1/exercises/classes/{classId}/mistakes

Le carnet d’erreurs

Les cartes ratées (20 au plus), avec la question et la bonne réponse. kind : FLASH, QCM, VF, CLOZE, ORDER, MATCH…

Requête

curl "https://api.coolroom.app/api/open/v1/exercises/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/mistakes" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "scope": "errors",
  "title": "Mes erreurs",
  "subtitle": "Les cartes ratées reviennent jusqu’à deux bonnes réponses d’affilée",
  "timed": false,
  "secondsPerItem": 0,
  "items": [
    {
      "key": "svt-cellule-q3",
      "lessonId": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
      "lessonTitle": "La cellule, unité du vivant",
      "kind": "QCM",
      "anchor": "le-noyau",
      "source": "LESSON",
      "prompt": "Où se trouve l’ADN dans une cellule animale ?",
      "answer": null,
      "options": [
        "Dans le noyau",
        "Dans la membrane",
        "Dans le cytoplasme seulement"
      ],
      "correct": [
        0
      ],
      "explanation": "L’ADN est dans le noyau (et un peu dans les mitochondries).",
      "sequence": null,
      "pairs": null,
      "truth": null,
      "game": "quiz"
    }
  ]
}

GET/api/open/v1/exercises/classes/{classId}/weak

Points faibles

Les cours où l’élève rate le plus.

Requête

curl "https://api.coolroom.app/api/open/v1/exercises/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/weak" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "lessonId": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
    "seen": 12,
    "missed": 5,
    "errors": 3
  }
]

GET/api/open/v1/exercises/classes/{classId}

Résumé de l’entraînement

Cartes à revoir, erreurs, plans de révision avant un contrôle et défi de classe.

Requête

curl "https://api.coolroom.app/api/open/v1/exercises/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "due": 5,
  "errors": 3,
  "weekLessons": 4,
  "challenge": {
    "goal": 300,
    "done": 212,
    "players": 17,
    "reached": false,
    "rewardCc": 20
  },
  "plans": [
    {
      "id": "3f4a5b6c-7d8e-4f9a-0b1c-2d3e4f5a6b7c",
      "title": "Contrôle SVT",
      "examOn": "2026-10-28",
      "daysLeft": 7,
      "lessons": [
        {
          "id": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
          "title": "La cellule, unité du vivant",
          "subjectKey": "svt"
        }
      ],
      "total": 30,
      "seen": 18,
      "mastered": 9,
      "doneToday": false,
      "examDay": false,
      "sessionDays": [
        "2026-10-20"
      ]
    }
  ],
  "suggestions": []
}

GET/api/open/v1/exercises/classes/{classId}/learn

Apprendre

Chaque cours avec des jeux, et ce qui est su dans chacun.

Requête

curl "https://api.coolroom.app/api/open/v1/exercises/classes/c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c/learn" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "lessons": [
    {
      "lessonId": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
      "title": "La cellule, unité du vivant",
      "subjectKey": "svt",
      "subjectName": "SVT",
      "givenOn": "2026-10-14",
      "total": 24,
      "seen": 20,
      "mastered": 11,
      "due": 3,
      "games": [
        {
          "game": "quiz",
          "label": "Quiz",
          "count": 8,
          "mastered": 5
        }
      ],
      "decks": []
    }
  ]
}

GET/api/open/v1/exercises/lessons/{lessonId}

Les cartes d’un cours

Toutes les cartes d’entraînement du cours et les compteurs de l’élève.

Requête

curl "https://api.coolroom.app/api/open/v1/exercises/lessons/5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "lessonId": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
  "items": [
    {
      "key": "svt-cellule-q3",
      "lessonId": "5e550a11-8c2d-4b7a-9f3e-1d2c3b4a5f60",
      "lessonTitle": "La cellule, unité du vivant",
      "kind": "QCM",
      "anchor": "le-noyau",
      "source": "LESSON",
      "prompt": "Où se trouve l’ADN dans une cellule animale ?",
      "answer": null,
      "options": [
        "Dans le noyau",
        "Dans la membrane",
        "Dans le cytoplasme seulement"
      ],
      "correct": [
        0
      ],
      "explanation": "L’ADN est dans le noyau (et un peu dans les mitochondries).",
      "sequence": null,
      "pairs": null,
      "truth": null,
      "game": "quiz"
    }
  ],
  "sections": [
    {
      "anchor": "le-noyau",
      "title": "Le noyau",
      "ai": true
    }
  ],
  "sectionsToGenerate": 0,
  "errors": 1,
  "due": 2,
  "seen": 20,
  "mastered": 11
}

Flash cardsflashcards

Les paquets de l’élève, ceux partagés avec lui, et ses parties.

GET/api/open/v1/flashcards/decks

Les paquets

kind : VOCAB ou DEFINITION. myBest : meilleure partie, null si jamais joué.

Requête

curl "https://api.coolroom.app/api/open/v1/flashcards/decks" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "mine": [
    {
      "id": "4a5b6c7d-8e9f-4a0b-1c2d-3e4f5a6b7c8d",
      "title": "Verbes irréguliers",
      "subject": "Anglais",
      "emoji": "🇬🇧",
      "cardCount": 40,
      "owner": {
        "id": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
        "displayName": "Léa Martin",
        "avatarIconId": "fox",
        "avatarPhotoVersion": null
      },
      "mine": true,
      "sharedIn": [
        {
          "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
          "className": "2nde 4"
        }
      ],
      "myBest": {
        "correct": 37,
        "total": 40
      },
      "myPlays": 6,
      "updatedAt": "2026-10-18T19:00:00Z",
      "lessonId": null,
      "kind": "VOCAB"
    }
  ],
  "shared": [],
  "stats": {
    "points": 1240,
    "runs": 18,
    "cardsReviewed": 610,
    "accuracy": 87,
    "perfectRuns": 2,
    "decksCreated": 3
  }
}

GET/api/open/v1/flashcards/decks/{deckId}

Un paquet et ses cartes

Les images des cartes ne sont pas servies par l’API.

Requête

curl "https://api.coolroom.app/api/open/v1/flashcards/decks/4a5b6c7d-8e9f-4a0b-1c2d-3e4f5a6b7c8d" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "deck": {
    "id": "4a5b6c7d-8e9f-4a0b-1c2d-3e4f5a6b7c8d",
    "title": "Verbes irréguliers",
    "…": "…"
  },
  "cards": [
    {
      "id": "5b6c7d8e-9f0a-4b1c-2d3e-4f5a6b7c8d9e",
      "position": 0,
      "frontText": "to begin",
      "backText": "began, begun",
      "frontImageVersion": null,
      "backImageVersion": null
    }
  ]
}

GET/api/open/v1/flashcards/runs

Les parties jouées

Les 200 dernières, les plus récentes d’abord.

Requête

curl "https://api.coolroom.app/api/open/v1/flashcards/runs" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "6c7d8e9f-0a1b-4c2d-3e4f-5a6b7c8d9e0f",
    "deckId": "4a5b6c7d-8e9f-4a0b-1c2d-3e4f5a6b7c8d",
    "deckTitle": "Verbes irréguliers",
    "correct": 37,
    "total": 40,
    "durationMs": 182000,
    "playedAt": "2026-10-18T19:04:00Z"
  }
]

Niveau et CCprogress

Comptes élèves seulement.

GET/api/open/v1/progress

La progression

level.into / level.needed : XP dans le niveau en cours / pour le suivant.

Requête

curl "https://api.coolroom.app/api/open/v1/progress" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

{
  "level": {
    "level": 9,
    "xp": 4210,
    "into": 310,
    "needed": 600
  },
  "cc": 185,
  "loginStreak": 12,
  "bestLoginStreak": 21,
  "season": {
    "season": {
      "id": "7d8e9f0a-1b2c-4d3e-4f5a-6b7c8d9e0f1a",
      "name": "Saison d’automne",
      "beta": false,
      "startsAt": "2026-09-01T00:00:00Z",
      "endsAt": "2026-12-20T00:00:00Z",
      "colorA": "#31AAA9",
      "colorB": "#A82020",
      "backgroundVersion": null
    },
    "level": {
      "level": 14,
      "xp": 2100,
      "into": 100,
      "needed": 200
    },
    "seenLevel": 14,
    "passMax": 50
  },
  "stats": {
    "questsDone": 34,
    "homeworkVerified": 12,
    "homeworkDone": 88,
    "flashGames": 18,
    "cosmeticsOwned": 7,
    "ccEarned": 640
  }
}

Notificationsnotifications

Les 100 dernières, les plus récentes d’abord.

GET/api/open/v1/notifications

Les notifications

type : NEW_HOMEWORK, NEW_GRADE, NEW_MAIL, LESSON_CHANGED, MENTION, CHAT_MESSAGE… relatedId : la chose concernée (devoir, note…).

Requête

curl "https://api.coolroom.app/api/open/v1/notifications" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "8e9f0a1b-2c3d-4e4f-5a6b-7c8d9e0f1a2b",
    "type": "NEW_HOMEWORK",
    "category": "DEVOIRS",
    "title": "Nouveau devoir en Mathématiques",
    "body": "Exercices 12 à 15 p. 84, pour jeudi",
    "relatedId": "9d2f7a10-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
    "classId": "c1a55e00-2b7d-4f1e-8a3c-6d9e0f1a2b3c",
    "read": false,
    "silent": false,
    "createdAt": "2026-10-21T16:00:05Z"
  }
]

IAai

La conversation de l’élève avec l’IA de CoolRoom.

GET/api/open/v1/ai/chat

La conversation

role : user ou assistant. degree : le degré d’aide choisi (1 à 3).

Requête

curl "https://api.coolroom.app/api/open/v1/ai/chat" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "9f0a1b2c-3d4e-4f5a-6b7c-8d9e0f1a2b3c",
    "role": "user",
    "content": "Explique-moi la mitose simplement",
    "degree": 2,
    "createdAt": "2026-10-21T17:20:00Z"
  },
  {
    "id": "0a1b2c3d-4e5f-4a6b-7c8d-9e0f1a2b3c4d",
    "role": "assistant",
    "content": "La mitose, c’est quand une cellule se divise en deux cellules identiques…",
    "degree": 2,
    "createdAt": "2026-10-21T17:20:09Z"
  }
]

Famille (comptes parents)family

Pour un compte parent : les enfants reliés et leurs données. 403 pour un compte élève.

GET/api/open/v1/family/children

Les enfants reliés

status : APPROVED quand l’enfant a accepté.

Requête

curl "https://api.coolroom.app/api/open/v1/family/children" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "linkId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "userId": "7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15",
    "displayName": "Léa Martin",
    "avatarIconId": "fox",
    "avatarPhotoVersion": null,
    "status": "APPROVED",
    "createdAt": "2026-09-05T18:00:00Z",
    "approvedAt": "2026-09-05T18:03:00Z",
    "classNames": [
      "2nde 4"
    ]
  }
]

GET/api/open/v1/family/children/{studentId}/grades

Les notes d’un enfant

Même forme que /grades.

Requête

curl "https://api.coolroom.app/api/open/v1/family/children/7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15/grades" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "3a4b5c6d-7e8f-4a1b-9c2d-3e4f5a6b7c8d",
    "subject": "Physique-Chimie",
    "title": "Contrôle : les ondes",
    "value": 15.5,
    "outOf": 20,
    "classAverage": 12.25,
    "classMin": 6,
    "classMax": 18.5,
    "coefficient": 2,
    "period": "Trimestre 1",
    "date": "2026-10-17",
    "revealed": true,
    "masked": false
  }
]

GET/api/open/v1/family/children/{studentId}/homework

Les devoirs d’un enfant

Avec la classe de chaque devoir.

Requête

curl "https://api.coolroom.app/api/open/v1/family/children/7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15/homework" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "9d2f7a10-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
    "subject": "Mathématiques",
    "title": "Exercices 12 à 15 p. 84",
    "description": "Faire les exercices sur les fonctions affines.",
    "dueAt": "2026-10-23T06:00:00Z",
    "status": "OFFICIEL",
    "isExam": false,
    "done": true,
    "completedAt": "2026-10-21T19:30:00Z",
    "className": "2nde 4"
  }
]

GET/api/open/v1/family/children/{studentId}/timetable

L’emploi du temps d’un enfant

Comme /timetable : from et to, 62 jours au plus.

Requête

curl "https://api.coolroom.app/api/open/v1/family/children/7b1e4c2a-5d3f-4e8a-9c61-2f0d8b3a4e15/timetable?from=2026-10-19&to=2026-10-25" \
  -H "Authorization: Bearer $COOLROOM_KEY"

Réponse · 200

[
  {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "subject": "Histoire-Géographie",
    "teacher": "M. Laurent",
    "room": "B204",
    "startAt": "2026-10-22T07:00:00Z",
    "endAt": "2026-10-22T08:00:00Z",
    "canceled": false,
    "note": null,
    "detention": false
  }
]

En utilisant l'API, tu respectes les élèves : n'utilise leurs données que pour ce que ton app leur annonce, ne les revends jamais, ne les garde pas plus longtemps qu'il ne faut, et supprime-les quand l'élève retire l'accès. Les conditions d'utilisation de CoolRoom s'appliquent. Conditions d'utilisation

L'API CoolRoom

Démarrer

1. Crée une clé

2. Appelle l'API

3. Pour une app publique

La doc en un zip

Ta première requête

Authentification

Se connecter avec CoolRoom

1. Le lien « Se connecter avec CoolRoom »

2. Le retour vers ton app

3. Échanger le code contre la clé

La liste des scopes

PKCE en JavaScript

Limites

Erreurs

Scopes

Routes

La clé elle-mêmetoute clé

Lire la clé

Réduire la clé

Révoquer la clé

Profilprofile

Le compte

Classesclasses

Mes classes

Une classe

Les membres

Les annonces

Chat de classechat

Les messages

Devoirshomework

Les devoirs, par classe

Un devoir

Notesgrades

Les notes

Les objectifs

Emploi du tempstimetable

Les cours entre deux dates

Vie scolaireschool_life

Absences et retards

Messageriemail

La boîte de réception

Un mail et sa conversation

Comptes scolairesschool_accounts

Les comptes reliés

Courscours

La bibliothèque

Chercher dans les cours

Le programme

Un cours

Exercicesexercises

Résultats carte par carte

Le carnet d’erreurs

Points faibles

Résumé de l’entraînement

Apprendre

Les cartes d’un cours

Flash cardsflashcards

Les paquets

Un paquet et ses cartes

Les parties jouées

Niveau et CCprogress

La progression

Notificationsnotifications

Les notifications

IAai

La conversation

Famille (comptes parents)family

Les enfants reliés

Les notes d’un enfant

Les devoirs d’un enfant

L’emploi du temps d’un enfant