# Worklog-API
SUMMARY: Append-only worklogs per taak voor agententeams — documenteer elke stap zodat niets verloren gaat; doorzoekbaar op taak, agent, soort en tijd.

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.
UUID task_ids: append/create/close antwoordt 404 (task_not_found) wanneer de UUID geen Synapse-taak (agent_tasks) heeft. Vrije slugs blijven vrij aanmaakbaar. (v1.39.46)

Worklog-API
De worklog is de enige bron van waarheid voor de werkgeschiedenis van de vloot. Hij is append-only, per taak en doorzoekbaar. Waar  opslaat wat een agent weet, slaat de worklog op wat een agent heeft gedaan — als duurzaam, controleerbaar spoor per taak. Michaels permanente regel (#8882, bevestigd in #10509): push-first — elke mijlpaal krijgt een entry, zodat een gecrashte sessie nooit haar verliest verliest en elk broertje/zusje precies verder kan waar jij stopte.
Concepten
| Term | Betekenis |
| --- | --- |
| Taakworklog | Een benoemd log geïdentificeerd door een vrij -veld (jouw keuze: UUID-prefix, ticket of ticket-achtige slug). |
| Entry | Eén append-only record: , , , optionele , timestamp. |
| Status |  (open) →  (gesloten) of . Ingesteld via . |
Endpoints
Alle endpoints zijn geauthenticeerd (Mind Key of gebruikers-JWT) en begrensd tot de mind van de aanroeper — je ziet nooit de worklogs van andere minds.
Push — het één-aanroep-patroon
Handigste endpoint; voegt een entry toe en maakt het taakrecord aan als het ontbreekt:
[CODE BLOCK]
Worklog aanmaken / openen
[CODE BLOCK]
Met een -veld wordt de eerste entry in dezelfde aanroep toegevoegd (antwoord ), anders wordt een lege taak aangemaakt (antwoord ). GET-variant: .
Een entry toevoegen
[CODE BLOCK]
Entry-soorten (onbekende waarden worden als  opgeslagen):
| kind | gebruik voor |
| --- | --- |
|  | taak geclaimd, werk begint |
|  | mijlpaal: commit, MR, verdict, testresultaat |
|  | context, beslissingen, observaties |
|  | fouten inclusief wat je probeerde (je toekomstige ik zegt dank) |
|  | fase/sessie-samenvatting vóór contextoverdracht |
|  | eindresultaat; gebruik de -endpoint voor de statusflip |
Limieten:  ≤ 256 KB per entry,  ≤ 128 tekens.
Lezen
[CODE BLOCK]
 (standaard) geeft het taakrecord + entries als gestructureerde data,  rendert een leesbare markdown-transcriptie,  platte tekst.
Recente activiteit over taken heen
[CODE BLOCK]
Optioneel -filter.  is een epoch-timestamp in seconden.
Takenlijst
[CODE BLOCK]
Sluiten (en verwijderen)
[CODE BLOCK]
Beide hebben GET-varianten (, ) voor open-tool LLM-clients. Sluiten bewaart het log — verwijderen is de enige destructieve operatie.
Aanbevolen ritme voor agenten
1.  — -entry bij het claimen van een taak (claim-bewijs).
2.  — -entries bij elke mijlpaal — commit-SHA, MR-nummer, verdict, pipeline-status. Push-first (Michael #8882): niet stappelen tot sessie-einde.
3.  — -entries voor elke fout die het onthouden waard is, met de fix.
4.  —  voordat je context opraakt — de volgende run pakt verder van state script + worklog.
5.  —  als de taak af is (bewijs in de laatste entry).
De vlootbrede taakconventie () bouwt op deze API; de gids Worklog voor Agenten bevat een copy-paste promptblok zodat geen enkele agent de functie "vergeet" (Michael #10509).
Task-ID-regels (v1.39.46)
s in volledig UUID-formaat moeten op elk schrijfpad
(, , ,
) naar een bestaande
Synapse-taak () verwijzen — anders antwoordt de endpoint met
 incl. hint. Hallucinated of afgekapte
UUID's creeren zo geen stille orphan-worklogs meer. Vrije, niet-UUID-ids
(, , prefix-slugs zoals )
blijven vrij aanmaakbaar (MEGA-1A-design). Lees- en verwijderpaden zijn
ongewijzigd — ze maken nooit iets aan.