Documentation technique

La référence API

Routes REST, authentification, concurrence, rapports et synchronisation du client ordinateur.

Documentation de la version 0.1.0Documentation Markdown ↓

REST : /api/v1. MCP : /mcp, avec le SDK officiel Streamable HTTP. Les objets REST utilisent camelCase. L’export de portabilité est un document JSON distinct avec schema_version: 2 et des champs historiques snake_case.

Authentification

Le navigateur reçoit un cookie minutrel HttpOnly, SameSite=Strict, Secure lorsque APP_SECURE_COOKIES=true. Les écritures authentifiées portent X-CSRF-Token, retourné à la connexion et par GET /me. Une origine tierce est refusée. Les routes d’installation/connexion sont limitées en fréquence.

Le client natif utilise native: true lors de la connexion. Sa session est retournée une seule fois au pont Rust, conservée dans le trousseau puis envoyée avec Authorization: Bearer <session>. Ce jeton est retiré de la réponse remise au rendu JavaScript.

Un jeton MCP est différent d’une session d’application : il ouvre /mcp et les outils correspondant à ses droits. Avec work.draft_own, il autorise aussi le webhook entrant de notes privées. Il n’autorise aucune route REST. Voir API et webhook.

MéthodeChemin RESTFonction et droit
GET/instance, /health/live, /health/readyVersion et état public de l’instance
GET/setupIndique si le premier espace doit être créé
POST/setupPremier administrateur avec setupToken, nom de l’espace, fuseau, identité et mot de passe
POST/auth/login, /auth/logoutConnexion et révocation de la session courante
GET/meCompte, espace, CSRF et heure serveur
POST/me/passwordMot de passe actuel et nouveau ; révoque sessions et jetons personnels
PATCH/workspaceNom/fuseau ; administrateur, fuseau figé après première saisie
GET/membersListe des membres ; responsable ou administrateur
POST/membersCréer un compte et son rôle ; administrateur
PATCH/members/{id}Identité, rôle et activation ; administrateur
POST/members/{id}/passwordRéinitialiser et révoquer les accès ; administrateur
GET, POST/members/{id}/timer, /members/{id}/timer/stopVoir/résoudre un temps actif avec version et motif ; administrateur
GET, POST/projectsProjets autorisés ; création responsable/administrateur
PATCH/projects/{id}Modifier, archiver, affecter les membres ; responsable/administrateur avec version
POST/projects/{id}/tasksAjouter une tâche ; responsable/administrateur
PATCH/tasks/{id}Renommer/archiver une tâche ; responsable/administrateur
GET/timerChronomètre personnel et heure serveur
POST/timer/start, /timer/pause, /timer/resume, /timer/stopÉcritures personnelles idempotentes, contrôlées par version
GET, POST/time-entriesListe paginée et saisie personnelle manuelle
PATCH, DELETE/time-entries/{id}Correction ou retrait d’un temps finalisé, version et motif obligatoires
PATCH/time-entries/{id}/descriptionModifier le texte sans remplacer les segments
GET, POST/notesNotes personnelles ; création humaine privée ou partagée
PATCH, DELETE/notes/{id}Relire/partager ou supprimer sa note
GET, POST/summariesComptes rendus personnels, création d’un brouillon manuel
PATCH/summaries/{id}Texte et état draft/approved, par l’auteur
POST/summaries/generateBrouillon IA personnel, fournisseur configuré et consent: true
GET/reports/monthly?month=AAAA-MMRapport personnel ; l’administrateur peut choisir les membres
POST/exportsCréer un instantané CSV/PDF/ZIP ; administrateur
GET/exports/{id}Télécharger son instantané encore valide ; droit administrateur revérifié
GET/workspace/exportExport JSON du travail partagé et finalisé ; administrateur
GET/auditDernières opérations de gestion ; administrateur
GET, POST/mcp-tokensVoir/créer ses accès assistant, sans réafficher leur secret
DELETE/mcp-tokens/{id}Révoquer un accès personnel
GET/providersProfils IA sans secrets ; compte connecté
POST, PATCH, DELETE/providers, /providers/{id}Gestion des fournisseurs ; administrateur
GET/eventsSSE authentifié : connected, change et heartbeat, sans données métier dans l’événement
POST/sync/time-entryInstantané de chronomètre personnel avec mutationId, baseVersion et segments ; droits et historique revalidés
POST/sync/importNouvelle saisie personnelle avec localId stable et formulaire input ; reçu durable sans doublon

Chronomètre et concurrence

Chaque écriture de chronomètre et chaque création manuelle porte Idempotency-Key, unique par demande, de 8 à 128 caractères alphanumériques, tirets ou _. Le serveur conserve le résultat d’origine pendant 30 jours. Une même clé avec un autre contenu donne 409.

http
POST /api/v1/timer/start
Idempotency-Key: 6c508152-4964-4d50-82a1-30f7c4545d90
Content-Type: application/json

{"projectId":"UUID_DU_PROJET","taskId":null,"description":"Préparer les maquettes"}

pause, resume et stop reçoivent {"version":1} avec la version courante. La réponse contient l’entrée et sa nouvelle version. GET /timer retourne {"timer":...,"serverNow":...}. Un conflit demande une relecture ; il ne faut pas recommencer aveuglément avec une nouvelle version.

Saisies et listes

Une durée manuelle contient projectId, taskId facultatif, description, kind: "duration", workDate: "2026-11-05" et duration: "1h30". Un intervalle contient kind: "interval", startedAt, endedAt en ISO avec décalage explicite, et éventuellement allowOverlap: true après confirmation.

La liste accepte memberId=me ou un UUID autorisé, month, offset et limit (1 à 100, 50 par défaut). Elle retourne items, total et serverNow. Un contributeur ne peut pas choisir un autre membre.

La correction complète reprend le formulaire manuel avec version et reason. La correction de description conserve les segments et ne reçoit que ces deux champs et le nouveau texte.

Rapports

memberIds est une liste d’UUID séparés par des virgules dans le rapport GET, ou un tableau dans la création d’export POST. Sans sélection, l’administrateur voit l’équipe entière ; les autres rôles voient leur rapport personnel.

Le rapport contient totalSeconds, entryCount, les agrégats par membre/projet, un aperçu de 100 entries, les notes partagées et les comptes rendus validés. Chaque ligne d’aperçu porte reportSeconds pour la portion du mois concerné.

POST /exports reçoit month, format (csv, pdf, zip), language (fr, en, de, français par défaut) et les memberIds facultatifs. La réponse contient id, url, filename et expiresAt. Le snapshot est privé au créateur et conserve le même contenu et la même langue lors d’une modification ultérieure des temps.

Synchronisation ordinateur

Le client peut rester autonome sans ouvrir d’API réseau. Pour un compte relié, POST /sync/time-entry reçoit un UUID mutationId, la version serveur attendue baseVersion ou null pour une création, et entry : id, projectId, taskId, description, state, segments (startedAt, endedAt en secondes). Le serveur calcule les durées, refuse les états incohérents et ne réécrit pas les segments déjà finalisés. La réponse est {entry, serverNow}.

POST /sync/import reçoit localId et input au format d’une saisie manuelle. Une répétition restitue le même enregistrement. Changer le contenu associé à un identifiant déjà reçu produit 409. Les reçus sont conservés séparément de l’idempotence de 30 jours des routes courantes. Voir SYNCHRONISATION.md.

Erreurs

Les erreurs ont la forme {"error":"...","message":"..."}. Les codes courants sont 400 (données), 401 (session), 403 (droits/CSRF/origine), 404 (objet ou export expiré), 409 (concurrence/état), 429 (limite) et 502 (fournisseur IA). Un détail de base, mot de passe ou clé ne doit pas apparaître dans une erreur destinée au client.

Ctrl/Cmd + K pour ouvrir · Échap pour fermer · La recherche reste sur ce site.