Référence API

L’API cahier.online

Poussez par programmation le cahier de textes d’un enseignant vers son handle : classes, devoirs et échéances. Une API REST simple, réponses en JSON, pensée pour un ENT, un agenda ou un outil de préparation de cours (Teetsh, Pronote, le vôtre).

URL de base

https://cahier.online/api/v1

Format

application/json · UTF-8

Authentification

Toutes les requêtes s’authentifient avec une clé secrète passée en en-tête Authorization: Bearer. Générez votre clé dans le panel, onglet Connexions. Ne l’exposez jamais côté client.

En-tête d’authentification

Authorization: Bearer co_live_a1b2c3d4e5f6

Une clé identifie à la fois le prof et la source(son label, ex. « Agenda »). Révoquez-la à tout moment depuis l’onglet Connexions.

Vérifier la connexion

Vérifie la clé et renvoie le handle du prof ainsi que la source associée.

GET/api/v1/me

RequêtecURL

curl https://cahier.online/api/v1/me \
  -H "Authorization: Bearer co_live_a1b2c3"

Réponse · 200

{
  "handle": "mme-laurent",
  "label": "Agenda"
}

Synchroniser le cahier

Sync déclaratif et idempotent. Envoyez l’état COURANT complet de votre source : cahier.online réconcilie pour (prof, source de la clé) — upsert des classes et devoirs par externalId, et suppression de ce qui n’est plus envoyé (les documents rattachés sont purgés). Seuls les devoirs à échéance future sont exposés aux élèves.

PUT/api/v1/cahier

Corps de la requête

externalIdstring · requisId stable de la classe côté source.

namestring · requisNom de la classe (ex. 6e B).

subjectstring · optionnelMatière affichée dans l'en-tête.

entries[].contentstring · requisÉnoncé du devoir affiché à l'élève.

entries[].dueDatestring · requisÉchéance ISO 8601 (AAAA-MM-JJ). Passée, le devoir est purgé.

entries[].sourceUrlstring · optionnelLien profond vers le devoir dans l'outil source ; affiché comme « Modifier sur … ».

RequêtecURL

curl -X PUT https://cahier.online/api/v1/cahier \
  -H "Authorization: Bearer co_live_a1b2c3" \
  -H "Content-Type: application/json" \
  -d '{"classes":[{"externalId":"cls-6eB","name":"6e B","subject":"SVT","entries":[{"externalId":"ev-123","content":"Exercices 4 et 5 p.112","dueDate":"2026-07-10","sourceUrl":"https://agenda.exemple.fr/devoirs/ev-123"}]}]}'

Réponse · 200

{
  "synced": { "classes": 1, "entries": 1 }
}

Documents

Un devoir peut porter des documents (fiche d’exercices, etc.). Pour l’instant, ils s’ajoutent depuis le panel ; leur gestion par l’API arrive en v1.1.

Suppression automatique. Quand l’échéance d’un devoir est dépassée, le devoir quitte la page publique et ses documents sont purgés du bucket. Ne comptez pas sur cahier.online pour archiver des fichiers.

Limites & erreurs

L’API renvoie des codes HTTP standards. Le corps d’erreur contient un champ error (et details par champ en cas de validation).

401unauthorizedClé absente, invalide ou révoquée.

422invalid_requestCorps invalide — le détail par champ est dans « details ».

Une limite de débit par clé est prévue (non appliquée en v1). Spécification complète : openapi.json.