# API Worklog
SUMMARY: Journaux de travail (worklogs) append-only par tâche pour les équipes d'agents — documentez chaque étape pour ne rien perdre ; interrogeable par tâche, agent, type et temps.

KEY CONTEXT:
Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.
Push (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...
Create/open a task worklog: POST /worklog { task_id, title? }  (content? -> appends first entry)
Append entry: POST /worklog/:task_id { kind, content, agent?, title? }  (GET variant: /worklog/:task_id/append)
Read: GET /worklog/:task_id?format=json|md|text
Recent across tasks: GET /worklog?limit=50&since=<epoch sec>&task_id=
List tasks: GET /worklog/list?status=active|completed|all&limit=20
Close: POST /worklog/:task_id/close  (GET variant exists)
Delete: DELETE /worklog/:task_id  (GET variant exists)
kinds: start | progress | note | error | summary | close (unknown -> note)
Limits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.
Fleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.
task_ids UUID : append/create/close répond 404 (task_not_found) si l’UUID ne correspond à aucune tâche Synapse (agent_tasks). Les slugs libres restent librement créables. (v1.39.46)

API Worklog
Le Worklog est la source unique de vérité de l'historique de travail de la flotte. Il est append-only, par tâche et interrogeable. Tandis que  stocke ce qu'un agent sait, le worklog stocke ce qu'un agent a fait — comme une trace durable et auditable par tâche. Règle permanente de Michael (#8882, réaffirmée dans #10509) : push-first — chaque jalon reçoit une entrée, de sorte qu'une session plantée ne perd jamais son histoire et qu'un frère puisse reprendre exactement là où vous vous êtes arrêté.
Concepts
| Terme | Signification |
| --- | --- |
| Worklog de tâche | Un journal nommé identifié par un  libre (à votre choix : préfixe d'UUID, ticket ou slug apparenté). |
| Entrée | Un enregistrement append-only : , , ,  optionnel, horodatage. |
| Statut |  (ouvert) →  (fermé) ou . Défini via . |
Endpoints
Tous les endpoints sont authentifiés (Mind Key ou JWT utilisateur) et limités au mind de l'appelant — vous ne verrez jamais les worklogs des autres minds.
Push — le motif en un seul appel
L'endpoint le plus pratique ; ajoute une entrée et crée l'enregistrement de tâche s'il manque :
[CODE BLOCK]
Créer / ouvrir un worklog
[CODE BLOCK]
Avec un champ , la première entrée est ajoutée dans le même appel (réponse ), sinon une tâche vide est créée (réponse ). Variante GET : .
Ajouter une entrée
[CODE BLOCK]
Types d'entrée (les valeurs inconnues sont stockées comme ) :
| kind | utiliser pour |
| --- | --- |
|  | tâche revendiquée, le travail commence |
|  | jalon : commit, MR, verdict, résultat de test |
|  | contexte, décisions, observations |
|  | échecs y compris ce que vous avez tenté (votre futur vous vous en remercie) |
|  | résumé de phase/session avant la transmission du contexte |
|  | résultat final ; préférez l'endpoint  pour le changement de statut |
Limites :  ≤ 256 Ko par entrée,  ≤ 128 caractères.
Lire
[CODE BLOCK]
 (défaut) renvoie l'enregistrement de tâche + les entrées en données structurées,  rend une transcription markdown lisible,  en texte brut.
Activité récente entre tâches
[CODE BLOCK]
Filtre  optionnel.  est un horodatage en secondes d'époque.
Lister les tâches
[CODE BLOCK]
Fermer (et supprimer)
[CODE BLOCK]
Les deux ont des variantes GET (, ) pour les clients LLM open-tool. La fermeture conserve le journal — la suppression est la seule opération destructive.
Rythme recommandé pour les agents
1.  — entrée  quand vous revendiquez une tâche (preuve de claim).
2.  — entrées  à chaque jalon — SHA du commit, numéro de MR, verdict, état du pipeline. Push-first (Michael #8882) : ne groupez pas jusqu'à la fin de session.
3.  — entrées  pour chaque échec digne de mémoire, avec le fix.
4.  —  avant de manquer de contexte — le run suivant reprend depuis le state script + le worklog.
5.  —  quand la tâche est faite (preuves dans la dernière entrée).
La convention de tâches à l'échelle de la flotte () repose sur cette API ; le guide Worklog pour Agents contient un bloc de prompt à copier-coller pour qu'aucun agent n'« oublie » la fonctionnalité (Michael #10509).
Regles des taskid (v1.39.46)
Les  au format UUID complet doivent referencer une tache Synapse
existante () sur chaque chemin d'ecriture (,
, ,
) — sinon l'endpoint repond
 avec un indice. Les UUID hallucinees ou
tronquees ne creent plus silencieusement des worklogs orphelins. Les ids
libres sans format UUID (, , slugs a prefixe
comme ) restent librement creables (design MEGA-1A). Les
chemins de lecture et de suppression sont inchanges — ils ne creent jamais
rien.