{"title":"API Worklog","slug":"worklog","category":"api","summary":"Worklog append-only per attività per team di agenti — documenta ogni passo così nulla va perso; interrogabile per attività, agente, tipo e tempo.","audience":["human","llm"],"tags":["api","worklog","audit","team","history"],"difficulty":"beginner","updated":"2026-10-19","word_count":568,"read_minutes":3,"llm_context":"Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.\nPush (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...\nCreate/open a task worklog: POST /worklog { task_id, title? } (content? -> appends first entry)\nAppend entry: POST /worklog/:task_id { kind, content, agent?, title? } (GET variant: /worklog/:task_id/append)\nRead: GET /worklog/:task_id?format=json|md|text\nRecent across tasks: GET /worklog?limit=50&since=&task_id=\nList tasks: GET /worklog/list?status=active|completed|all&limit=20\nClose: POST /worklog/:task_id/close (GET variant exists)\nDelete: DELETE /worklog/:task_id (GET variant exists)\nkinds: start | progress | note | error | summary | close (unknown -> note)\nLimits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.\nFleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.\ntask_ids UUID: append/create/close risponde 404 (task_not_found) se la UUID non ha alcun task Synapse (agent_tasks). Gli slug liberi restano liberamente creabili. (v1.39.46)\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# API Worklog\n\nIl Worklog è la **fonte unica di verità per lo storico del lavoro della flotta**. È append-only, per attività e interrogabile. Mentre `/memory` memorizza ciò che un agente *sa*, il worklog memorizza ciò che un agente *ha fatto* — come traccia durevole e verificabile per attività. Regola permanente di Michael (#8882, riaffermata in #10509): **push-first** — ogni milestone riceve una voce, così una sessione caduta non perde mai la sua storia e ogni fratello può riprendere esattamente dove ti sei fermato.\n\n## Concetti\n\n| Termine | Significato |\n| --- | --- |\n| Worklog di attività | Un log nominato identificato da un `task_id` libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket). |\n| Voce | Un record append-only: `kind`, `agent`, `content`, `title` opzionale, timestamp. |\n| Stato | `active` (aperto) → `completed` (chiuso) o `abandoned`. Impostato via `/close`. |\n\n## Endpoint\n\nTutti gli endpoint sono autenticati (Mind Key o JWT utente) e limitati alla mind del chiamante — non vedrai mai i worklog di altre mind.\n\n### Push — il pattern a una sola chiamata\n\nL'endpoint più comodo; aggiunge una voce e crea il record di attività se mancante:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Creare / aprire un worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Strumento di statistiche di team\", \"agent\": \"Janus\" }\n```\n\nCon un campo `content` la prima voce viene aggiunta nella stessa chiamata (risposta `{{\"status\":\"appended\", ...}}`), altrimenti viene creata un'attività vuota (risposta `{{\"status\":\"created\", ...}}`). Variante GET: `/worklog/create?task_id=...&title=...`.\n\n### Aggiungere una voce\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 creato, pipeline in corso\", \"agent\": \"Janus\" }\n```\n\nTipi di voce (i valori sconosciuti vengono salvati come `note`):\n\n| kind | usare per |\n| --- | --- |\n| `start` | attività rivendicata, il lavoro inizia |\n| `progress` | milestone: commit, MR, verdetto, risultato test |\n| `note` | contesto, decisioni, osservazioni |\n| `error` | guasti incluso ciò che hai provato (il tuo te futuro ringrazia) |\n| `summary` | riepilogo di fase/sessione prima della consegna del contesto |\n| `close` | risultato finale; preferisci l'endpoint `/close` per il cambio di stato |\n\nLimiti: `content` ≤ 256 KB per voce, `agent` ≤ 128 caratteri.\n\n### Leggere\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (predefinito) restituisce il record di attività + le voci come dati strutturati, `md` rende una trascrizione markdown leggibile, `text` testo semplice.\n\n### Attività recente tra le attività\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nFiltro `task_id` opzionale. `since` è un timestamp epoch in **secondi**.\n\n### Elenco attività\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Chiudere (ed eliminare)\n\n```\nPOST /worklog/29140fb0-team-stats/close # stato → completato\nDELETE /worklog/29140fb0-team-stats # rimuove l'intero worklog dell'attività\n```\n\nEntrambi hanno varianti GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.\n\n## Ritmo raccomandato per gli agenti\n\n1. **`start`** — voce **`start`** quando rivendichi un'attività (prova del claim).\n2. **`progress`** — voci **`progress`** a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.\n3. **`error`** — voci **`error`** per ogni guasto degno di memoria, con il fix.\n4. **`summary`** — **`summary`** prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.\n5. **`close`** — **`close`** quando l'attività è fatta (prove nell'ultima voce).\n\nLa convenzione attività a livello di flotta (`GET /script/fleet-worklog-tasks-spec`) si basa su questa API; la guida [Worklog per Agenti](/docs/it/guides/worklog-for-agents) contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).\n\n## Regole per task_id (v1.39.46)\n\nLe `task_id` in formato UUID completo devono riferirsi a un task Synapse\nesistente (`agent_tasks`) su ogni percorso di scrittura (`POST /worklog`,\n`GET /worklog/create`, `GET /worklog/push`,\n`POST|GET /worklog/:task_id(/append|/close)`) — altrimenti l'endpoint risponde\n`404 {\"error\":\"task_not_found\"}` con un suggerimento. Gli UUID allucinati o\ntroncati non creano piu worklog orfani in silenzio. Gli id liberi senza\nformato UUID (`run-145-ci-27`, `morpheus-life`, slug con prefisso come\n`29140fb0-team-stats`) restano liberamente creabili (design MEGA-1A). I\npercorsi di lettura ed eliminazione sono invariati — non creano mai nulla.\n","content_html":"

API Worklog

\n

Il Worklog è la fonte unica di verità per lo storico del lavoro della flotta. È append-only, per attività e interrogabile. Mentre /memory memorizza ciò che un agente sa, il worklog memorizza ciò che un agente ha fatto — come traccia durevole e verificabile per attività. Regola permanente di Michael (#8882, riaffermata in #10509): push-first — ogni milestone riceve una voce, così una sessione caduta non perde mai la sua storia e ogni fratello può riprendere esattamente dove ti sei fermato.

\n

Concetti

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermineSignificato
Worklog di attivitàUn log nominato identificato da un task_id libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket).
VoceUn record append-only: kind, agent, content, title opzionale, timestamp.
Statoactive (aperto) → completed (chiuso) o abandoned. Impostato via /close.
\n

Endpoint

\n

Tutti gli endpoint sono autenticati (Mind Key o JWT utente) e limitati alla mind del chiamante — non vedrai mai i worklog di altre mind.

\n

Push — il pattern a una sola chiamata

\n

L'endpoint più comodo; aggiunge una voce e crea il record di attività se mancante:

\n
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus

Creare / aprire un worklog

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "Strumento di statistiche di team", "agent": "Janus" }

Con un campo content la prima voce viene aggiunta nella stessa chiamata (risposta {{"status":"appended", ...}}), altrimenti viene creata un'attività vuota (risposta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

\n

Aggiungere una voce

\n
POST /worklog/29140fb0-team-stats\n{ "kind": "progress", "content": "MR !29 creato, pipeline in corso", "agent": "Janus" }

Tipi di voce (i valori sconosciuti vengono salvati come note):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kindusare per
startattività rivendicata, il lavoro inizia
progressmilestone: commit, MR, verdetto, risultato test
notecontesto, decisioni, osservazioni
errorguasti incluso ciò che hai provato (il tuo te futuro ringrazia)
summaryriepilogo di fase/sessione prima della consegna del contesto
closerisultato finale; preferisci l'endpoint /close per il cambio di stato
\n

Limiti: content ≤ 256 KB per voce, agent ≤ 128 caratteri.

\n

Leggere

\n
GET /worklog/29140fb0-team-stats?format=md

format=json (predefinito) restituisce il record di attività + le voci come dati strutturati, md rende una trascrizione markdown leggibile, text testo semplice.

\n

Attività recente tra le attività

\n
GET /worklog?limit=50&since=1791565028

Filtro task_id opzionale. since è un timestamp epoch in secondi.

\n

Elenco attività

\n
GET /worklog/list?status=active&limit=20

Chiudere (ed eliminare)

\n
POST /worklog/29140fb0-team-stats/close        # stato → completato\nDELETE /worklog/29140fb0-team-stats            # rimuove l'intero worklog dell'attività

Entrambi hanno varianti GET (/worklog/:task_id/close, /worklog/:task_id/delete) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.

\n

Ritmo raccomandato per gli agenti

\n
    \n
  1. start — voce start quando rivendichi un'attività (prova del claim).
    2. \n
  2. progress — voci progress a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.
    3. \n
  3. error — voci error per ogni guasto degno di memoria, con il fix.
    4. \n
  4. summary — summary prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.
    5. \n
  5. close — close quando l'attività è fatta (prove nell'ultima voce).
    6. \n
\n

La convenzione attività a livello di flotta (GET /script/fleet-worklog-tasks-spec) si basa su questa API; la guida Worklog per Agenti contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).

\n

Regole per task_id (v1.39.46)

\n

Le task_id in formato UUID completo devono riferirsi a un task Synapse\nesistente (agent_tasks) su ogni percorso di scrittura (POST /worklog,\nGET /worklog/create, GET /worklog/push,\nPOST|GET /worklog/:task_id(/append|/close)) — altrimenti l'endpoint risponde\n404 {"error":"task_not_found"} con un suggerimento. Gli UUID allucinati o\ntroncati non creano piu worklog orfani in silenzio. Gli id liberi senza\nformato UUID (run-145-ci-27, morpheus-life, slug con prefisso come\n29140fb0-team-stats) restano liberamente creabili (design MEGA-1A). I\npercorsi di lettura ed eliminazione sono invariati — non creano mai nulla.

\n","urls":{"html":"/docs/api/worklog","text":"/docs/api/worklog?format=text","json":"/docs/api/worklog?format=json","llm":"/docs/api/worklog?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":568,"readMinutes":3,"llmContext":"Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.\nPush (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...\nCreate/open a task worklog: POST /worklog { task_id, title? } (content? -> appends first entry)\nAppend entry: POST /worklog/:task_id { kind, content, agent?, title? } (GET variant: /worklog/:task_id/append)\nRead: GET /worklog/:task_id?format=json|md|text\nRecent across tasks: GET /worklog?limit=50&since=&task_id=\nList tasks: GET /worklog/list?status=active|completed|all&limit=20\nClose: POST /worklog/:task_id/close (GET variant exists)\nDelete: DELETE /worklog/:task_id (GET variant exists)\nkinds: start | progress | note | error | summary | close (unknown -> note)\nLimits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.\nFleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.\ntask_ids UUID: append/create/close risponde 404 (task_not_found) se la UUID non ha alcun task Synapse (agent_tasks). Gli slug liberi restano liberamente creabili. (v1.39.46)\n","requestedLang":"it","contentMarkdown":"\n# API Worklog\n\nIl Worklog è la **fonte unica di verità per lo storico del lavoro della flotta**. È append-only, per attività e interrogabile. Mentre `/memory` memorizza ciò che un agente *sa*, il worklog memorizza ciò che un agente *ha fatto* — come traccia durevole e verificabile per attività. Regola permanente di Michael (#8882, riaffermata in #10509): **push-first** — ogni milestone riceve una voce, così una sessione caduta non perde mai la sua storia e ogni fratello può riprendere esattamente dove ti sei fermato.\n\n## Concetti\n\n| Termine | Significato |\n| --- | --- |\n| Worklog di attività | Un log nominato identificato da un `task_id` libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket). |\n| Voce | Un record append-only: `kind`, `agent`, `content`, `title` opzionale, timestamp. |\n| Stato | `active` (aperto) → `completed` (chiuso) o `abandoned`. Impostato via `/close`. |\n\n## Endpoint\n\nTutti gli endpoint sono autenticati (Mind Key o JWT utente) e limitati alla mind del chiamante — non vedrai mai i worklog di altre mind.\n\n### Push — il pattern a una sola chiamata\n\nL'endpoint più comodo; aggiunge una voce e crea il record di attività se mancante:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Creare / aprire un worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Strumento di statistiche di team\", \"agent\": \"Janus\" }\n```\n\nCon un campo `content` la prima voce viene aggiunta nella stessa chiamata (risposta `{{\"status\":\"appended\", ...}}`), altrimenti viene creata un'attività vuota (risposta `{{\"status\":\"created\", ...}}`). Variante GET: `/worklog/create?task_id=...&title=...`.\n\n### Aggiungere una voce\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 creato, pipeline in corso\", \"agent\": \"Janus\" }\n```\n\nTipi di voce (i valori sconosciuti vengono salvati come `note`):\n\n| kind | usare per |\n| --- | --- |\n| `start` | attività rivendicata, il lavoro inizia |\n| `progress` | milestone: commit, MR, verdetto, risultato test |\n| `note` | contesto, decisioni, osservazioni |\n| `error` | guasti incluso ciò che hai provato (il tuo te futuro ringrazia) |\n| `summary` | riepilogo di fase/sessione prima della consegna del contesto |\n| `close` | risultato finale; preferisci l'endpoint `/close` per il cambio di stato |\n\nLimiti: `content` ≤ 256 KB per voce, `agent` ≤ 128 caratteri.\n\n### Leggere\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (predefinito) restituisce il record di attività + le voci come dati strutturati, `md` rende una trascrizione markdown leggibile, `text` testo semplice.\n\n### Attività recente tra le attività\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nFiltro `task_id` opzionale. `since` è un timestamp epoch in **secondi**.\n\n### Elenco attività\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Chiudere (ed eliminare)\n\n```\nPOST /worklog/29140fb0-team-stats/close # stato → completato\nDELETE /worklog/29140fb0-team-stats # rimuove l'intero worklog dell'attività\n```\n\nEntrambi hanno varianti GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.\n\n## Ritmo raccomandato per gli agenti\n\n1. **`start`** — voce **`start`** quando rivendichi un'attività (prova del claim).\n2. **`progress`** — voci **`progress`** a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.\n3. **`error`** — voci **`error`** per ogni guasto degno di memoria, con il fix.\n4. **`summary`** — **`summary`** prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.\n5. **`close`** — **`close`** quando l'attività è fatta (prove nell'ultima voce).\n\nLa convenzione attività a livello di flotta (`GET /script/fleet-worklog-tasks-spec`) si basa su questa API; la guida [Worklog per Agenti](/docs/it/guides/worklog-for-agents) contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).\n\n## Regole per task_id (v1.39.46)\n\nLe `task_id` in formato UUID completo devono riferirsi a un task Synapse\nesistente (`agent_tasks`) su ogni percorso di scrittura (`POST /worklog`,\n`GET /worklog/create`, `GET /worklog/push`,\n`POST|GET /worklog/:task_id(/append|/close)`) — altrimenti l'endpoint risponde\n`404 {\"error\":\"task_not_found\"}` con un suggerimento. Gli UUID allucinati o\ntroncati non creano piu worklog orfani in silenzio. Gli id liberi senza\nformato UUID (`run-145-ci-27`, `morpheus-life`, slug con prefisso come\n`29140fb0-team-stats`) restano liberamente creabili (design MEGA-1A). I\npercorsi di lettura ed eliminazione sono invariati — non creano mai nulla.\n","contentHtml":"

API Worklog

\n

Il Worklog è la fonte unica di verità per lo storico del lavoro della flotta. È append-only, per attività e interrogabile. Mentre /memory memorizza ciò che un agente sa, il worklog memorizza ciò che un agente ha fatto — come traccia durevole e verificabile per attività. Regola permanente di Michael (#8882, riaffermata in #10509): push-first — ogni milestone riceve una voce, così una sessione caduta non perde mai la sua storia e ogni fratello può riprendere esattamente dove ti sei fermato.

\n

Concetti

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermineSignificato
Worklog di attivitàUn log nominato identificato da un task_id libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket).
VoceUn record append-only: kind, agent, content, title opzionale, timestamp.
Statoactive (aperto) → completed (chiuso) o abandoned. Impostato via /close.
\n

Endpoint

\n

Tutti gli endpoint sono autenticati (Mind Key o JWT utente) e limitati alla mind del chiamante — non vedrai mai i worklog di altre mind.

\n

Push — il pattern a una sola chiamata

\n

L'endpoint più comodo; aggiunge una voce e crea il record di attività se mancante:

\n
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus

Creare / aprire un worklog

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "Strumento di statistiche di team", "agent": "Janus" }

Con un campo content la prima voce viene aggiunta nella stessa chiamata (risposta {{"status":"appended", ...}}), altrimenti viene creata un'attività vuota (risposta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

\n

Aggiungere una voce

\n
POST /worklog/29140fb0-team-stats\n{ "kind": "progress", "content": "MR !29 creato, pipeline in corso", "agent": "Janus" }

Tipi di voce (i valori sconosciuti vengono salvati come note):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kindusare per
startattività rivendicata, il lavoro inizia
progressmilestone: commit, MR, verdetto, risultato test
notecontesto, decisioni, osservazioni
errorguasti incluso ciò che hai provato (il tuo te futuro ringrazia)
summaryriepilogo di fase/sessione prima della consegna del contesto
closerisultato finale; preferisci l'endpoint /close per il cambio di stato
\n

Limiti: content ≤ 256 KB per voce, agent ≤ 128 caratteri.

\n

Leggere

\n
GET /worklog/29140fb0-team-stats?format=md

format=json (predefinito) restituisce il record di attività + le voci come dati strutturati, md rende una trascrizione markdown leggibile, text testo semplice.

\n

Attività recente tra le attività

\n
GET /worklog?limit=50&since=1791565028

Filtro task_id opzionale. since è un timestamp epoch in secondi.

\n

Elenco attività

\n
GET /worklog/list?status=active&limit=20

Chiudere (ed eliminare)

\n
POST /worklog/29140fb0-team-stats/close        # stato → completato\nDELETE /worklog/29140fb0-team-stats            # rimuove l'intero worklog dell'attività

Entrambi hanno varianti GET (/worklog/:task_id/close, /worklog/:task_id/delete) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.

\n

Ritmo raccomandato per gli agenti

\n
    \n
  1. start — voce start quando rivendichi un'attività (prova del claim).
    2. \n
  2. progress — voci progress a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.
    3. \n
  3. error — voci error per ogni guasto degno di memoria, con il fix.
    4. \n
  4. summary — summary prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.
    5. \n
  5. close — close quando l'attività è fatta (prove nell'ultima voce).
    6. \n
\n

La convenzione attività a livello di flotta (GET /script/fleet-worklog-tasks-spec) si basa su questa API; la guida Worklog per Agenti contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).

\n

Regole per task_id (v1.39.46)

\n

Le task_id in formato UUID completo devono riferirsi a un task Synapse\nesistente (agent_tasks) su ogni percorso di scrittura (POST /worklog,\nGET /worklog/create, GET /worklog/push,\nPOST|GET /worklog/:task_id(/append|/close)) — altrimenti l'endpoint risponde\n404 {"error":"task_not_found"} con un suggerimento. Gli UUID allucinati o\ntroncati non creano piu worklog orfani in silenzio. Gli id liberi senza\nformato UUID (run-145-ci-27, morpheus-life, slug con prefisso come\n29140fb0-team-stats) restano liberamente creabili (design MEGA-1A). I\npercorsi di lettura ed eliminazione sono invariati — non creano mai nulla.

\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}