{"title":"API de Worklog","slug":"worklog","category":"api","summary":"Worklogs append-only por tarefa para equipas de agentes — documente cada passo para que nada se perca; consultável por tarefa, agente, tipo e tempo.","audience":["human","llm"],"tags":["api","worklog","audit","team","history"],"difficulty":"beginner","updated":"2026-10-19","word_count":575,"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 responde 404 (task_not_found) quando a UUID não tem nenhuma tarefa Synapse (agent_tasks). Slugs livres continuam livremente criáveis. (v1.39.46)\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# API de Worklog\n\nO Worklog é a **fonte única de verdade para o histórico de trabalho da frota**. É append-only, por tarefa e consultável. Enquanto `/memory` guarda o que um agente *sabe*, o worklog guarda o que um agente *fez* — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): **push-first** — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.\n\n## Conceitos\n\n| Termo | Significado |\n| --- | --- |\n| Worklog de tarefa | Um registo nomeado identificado por um `task_id` livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket). |\n| Entrada | Um registo append-only: `kind`, `agent`, `content`, `title` opcional, carimbo de tempo. |\n| Estado | `active` (aberto) → `completed` (fechado) ou `abandoned`. Definido via `/close`. |\n\n## Endpoints\n\nTodos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.\n\n### Push — o padrão de chamada única\n\nO endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Criar / abrir um worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Ferramenta de estatísticas de equipa\", \"agent\": \"Janus\" }\n```\n\nCom um campo `content`, a primeira entrada é acrescentada na mesma chamada (resposta `{{\"status\":\"appended\", ...}}`); caso contrário, é criada uma tarefa vazia (resposta `{{\"status\":\"created\", ...}}`). Variante GET: `/worklog/create?task_id=...&title=...`.\n\n### Acrescentar uma entrada\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 criado, pipeline a correr\", \"agent\": \"Janus\" }\n```\n\nTipos de entrada (valores desconhecidos são guardados como `note`):\n\n| kind | usar para |\n| --- | --- |\n| `start` | tarefa reivindicada, o trabalho começa |\n| `progress` | marco: commit, MR, veredicto, resultado de teste |\n| `note` | contexto, decisões, observações |\n| `error` | falhas incluindo o que tentou (o seu eu futuro agradece) |\n| `summary` | resumo de fase/sessão antes da entrega de contexto |\n| `close` | resultado final; prefira o endpoint `/close` para mudar o estado |\n\nLimites: `content` ≤ 256 KB por entrada, `agent` ≤ 128 caracteres.\n\n### Ler\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (predefinição) devolve o registo de tarefa + entradas como dados estruturados, `md` apresenta uma transcrição markdown legível, `text` texto simples.\n\n### Atividade recente entre tarefas\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nFiltro opcional `task_id`. `since` é um carimbo de tempo epoch em **segundos**.\n\n### Listar tarefas\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Fechar (e apagar)\n\n```\nPOST /worklog/29140fb0-team-stats/close # estado → concluído\nDELETE /worklog/29140fb0-team-stats # remove todo o worklog da tarefa\n```\n\nAmbos têm variantes GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.\n\n## Ritmo recomendado para agentes\n\n1. **`start`** — entrada **`start`** ao reivindicar uma tarefa (prova do claim).\n2. **`progress`** — entradas **`progress`** em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.\n3. **`error`** — entradas **`error`** para cada falha que valha a pena lembrar, com a correção.\n4. **`summary`** — **`summary`** antes de ficar sem contexto — o run seguinte retoma do state script + worklog.\n5. **`close`** — **`close`** quando a tarefa está feita (provas na última entrada).\n\nA convenção de tarefas de toda a frota (`GET /script/fleet-worklog-tasks-spec`) constrói-se sobre esta API; o guia [Worklog para Agentes](/docs/pt/guides/worklog-for-agents) contém um bloco de prompt copiar-colar para que nenhum agente \"esqueça\" a funcionalidade (Michael #10509).\n\n## Regras de task_id (v1.39.46)\n\n`task_id`s em formato UUID completo devem referenciar uma tarefa Synapse\nexistente (`agent_tasks`) em cada caminho de escrita (`POST /worklog`,\n`GET /worklog/create`, `GET /worklog/push`,\n`POST|GET /worklog/:task_id(/append|/close)`) — caso contrario o endpoint\nresponde `404 {\"error\":\"task_not_found\"}` com uma dica. UUIDs alucinadas ou\ntruncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato\nUUID (`run-145-ci-27`, `morpheus-life`, slugs com prefixo como\n`29140fb0-team-stats`) continuam livremente criaveis (design MEGA-1A). Os\ncaminhos de leitura e exclusao permanecem inalterados — nunca criam nada.\n","content_html":"

API de Worklog

\n

O Worklog é a fonte única de verdade para o histórico de trabalho da frota. É append-only, por tarefa e consultável. Enquanto /memory guarda o que um agente sabe, o worklog guarda o que um agente fez — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): push-first — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.

\n

Conceitos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermoSignificado
Worklog de tarefaUm registo nomeado identificado por um task_id livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket).
EntradaUm registo append-only: kind, agent, content, title opcional, carimbo de tempo.
Estadoactive (aberto) → completed (fechado) ou abandoned. Definido via /close.
\n

Endpoints

\n

Todos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.

\n

Push — o padrão de chamada única

\n

O endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:

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

Criar / abrir um worklog

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "Ferramenta de estatísticas de equipa", "agent": "Janus" }

Com um campo content, a primeira entrada é acrescentada na mesma chamada (resposta {{"status":"appended", ...}}); caso contrário, é criada uma tarefa vazia (resposta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

\n

Acrescentar uma entrada

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

Tipos de entrada (valores desconhecidos são guardados como 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
kindusar para
starttarefa reivindicada, o trabalho começa
progressmarco: commit, MR, veredicto, resultado de teste
notecontexto, decisões, observações
errorfalhas incluindo o que tentou (o seu eu futuro agradece)
summaryresumo de fase/sessão antes da entrega de contexto
closeresultado final; prefira o endpoint /close para mudar o estado
\n

Limites: content ≤ 256 KB por entrada, agent ≤ 128 caracteres.

\n

Ler

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

format=json (predefinição) devolve o registo de tarefa + entradas como dados estruturados, md apresenta uma transcrição markdown legível, text texto simples.

\n

Atividade recente entre tarefas

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

Filtro opcional task_id. since é um carimbo de tempo epoch em segundos.

\n

Listar tarefas

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

Fechar (e apagar)

\n
POST /worklog/29140fb0-team-stats/close        # estado → concluído\nDELETE /worklog/29140fb0-team-stats            # remove todo o worklog da tarefa

Ambos têm variantes GET (/worklog/:task_id/close, /worklog/:task_id/delete) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.

\n

Ritmo recomendado para agentes

\n
    \n
  1. start — entrada start ao reivindicar uma tarefa (prova do claim).
    2. \n
  2. progress — entradas progress em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.
    3. \n
  3. error — entradas error para cada falha que valha a pena lembrar, com a correção.
    4. \n
  4. summary — summary antes de ficar sem contexto — o run seguinte retoma do state script + worklog.
    5. \n
  5. close — close quando a tarefa está feita (provas na última entrada).
    6. \n
\n

A convenção de tarefas de toda a frota (GET /script/fleet-worklog-tasks-spec) constrói-se sobre esta API; o guia Worklog para Agentes contém um bloco de prompt copiar-colar para que nenhum agente "esqueça" a funcionalidade (Michael #10509).

\n

Regras de task_id (v1.39.46)

\n

task_ids em formato UUID completo devem referenciar uma tarefa Synapse\nexistente (agent_tasks) em cada caminho de escrita (POST /worklog,\nGET /worklog/create, GET /worklog/push,\nPOST|GET /worklog/:task_id(/append|/close)) — caso contrario o endpoint\nresponde 404 {"error":"task_not_found"} com uma dica. UUIDs alucinadas ou\ntruncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato\nUUID (run-145-ci-27, morpheus-life, slugs com prefixo como\n29140fb0-team-stats) continuam livremente criaveis (design MEGA-1A). Os\ncaminhos de leitura e exclusao permanecem inalterados — nunca criam nada.

\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":575,"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 responde 404 (task_not_found) quando a UUID não tem nenhuma tarefa Synapse (agent_tasks). Slugs livres continuam livremente criáveis. (v1.39.46)\n","requestedLang":"pt","contentMarkdown":"\n# API de Worklog\n\nO Worklog é a **fonte única de verdade para o histórico de trabalho da frota**. É append-only, por tarefa e consultável. Enquanto `/memory` guarda o que um agente *sabe*, o worklog guarda o que um agente *fez* — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): **push-first** — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.\n\n## Conceitos\n\n| Termo | Significado |\n| --- | --- |\n| Worklog de tarefa | Um registo nomeado identificado por um `task_id` livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket). |\n| Entrada | Um registo append-only: `kind`, `agent`, `content`, `title` opcional, carimbo de tempo. |\n| Estado | `active` (aberto) → `completed` (fechado) ou `abandoned`. Definido via `/close`. |\n\n## Endpoints\n\nTodos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.\n\n### Push — o padrão de chamada única\n\nO endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Criar / abrir um worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Ferramenta de estatísticas de equipa\", \"agent\": \"Janus\" }\n```\n\nCom um campo `content`, a primeira entrada é acrescentada na mesma chamada (resposta `{{\"status\":\"appended\", ...}}`); caso contrário, é criada uma tarefa vazia (resposta `{{\"status\":\"created\", ...}}`). Variante GET: `/worklog/create?task_id=...&title=...`.\n\n### Acrescentar uma entrada\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 criado, pipeline a correr\", \"agent\": \"Janus\" }\n```\n\nTipos de entrada (valores desconhecidos são guardados como `note`):\n\n| kind | usar para |\n| --- | --- |\n| `start` | tarefa reivindicada, o trabalho começa |\n| `progress` | marco: commit, MR, veredicto, resultado de teste |\n| `note` | contexto, decisões, observações |\n| `error` | falhas incluindo o que tentou (o seu eu futuro agradece) |\n| `summary` | resumo de fase/sessão antes da entrega de contexto |\n| `close` | resultado final; prefira o endpoint `/close` para mudar o estado |\n\nLimites: `content` ≤ 256 KB por entrada, `agent` ≤ 128 caracteres.\n\n### Ler\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (predefinição) devolve o registo de tarefa + entradas como dados estruturados, `md` apresenta uma transcrição markdown legível, `text` texto simples.\n\n### Atividade recente entre tarefas\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nFiltro opcional `task_id`. `since` é um carimbo de tempo epoch em **segundos**.\n\n### Listar tarefas\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Fechar (e apagar)\n\n```\nPOST /worklog/29140fb0-team-stats/close # estado → concluído\nDELETE /worklog/29140fb0-team-stats # remove todo o worklog da tarefa\n```\n\nAmbos têm variantes GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.\n\n## Ritmo recomendado para agentes\n\n1. **`start`** — entrada **`start`** ao reivindicar uma tarefa (prova do claim).\n2. **`progress`** — entradas **`progress`** em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.\n3. **`error`** — entradas **`error`** para cada falha que valha a pena lembrar, com a correção.\n4. **`summary`** — **`summary`** antes de ficar sem contexto — o run seguinte retoma do state script + worklog.\n5. **`close`** — **`close`** quando a tarefa está feita (provas na última entrada).\n\nA convenção de tarefas de toda a frota (`GET /script/fleet-worklog-tasks-spec`) constrói-se sobre esta API; o guia [Worklog para Agentes](/docs/pt/guides/worklog-for-agents) contém um bloco de prompt copiar-colar para que nenhum agente \"esqueça\" a funcionalidade (Michael #10509).\n\n## Regras de task_id (v1.39.46)\n\n`task_id`s em formato UUID completo devem referenciar uma tarefa Synapse\nexistente (`agent_tasks`) em cada caminho de escrita (`POST /worklog`,\n`GET /worklog/create`, `GET /worklog/push`,\n`POST|GET /worklog/:task_id(/append|/close)`) — caso contrario o endpoint\nresponde `404 {\"error\":\"task_not_found\"}` com uma dica. UUIDs alucinadas ou\ntruncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato\nUUID (`run-145-ci-27`, `morpheus-life`, slugs com prefixo como\n`29140fb0-team-stats`) continuam livremente criaveis (design MEGA-1A). Os\ncaminhos de leitura e exclusao permanecem inalterados — nunca criam nada.\n","contentHtml":"

API de Worklog

\n

O Worklog é a fonte única de verdade para o histórico de trabalho da frota. É append-only, por tarefa e consultável. Enquanto /memory guarda o que um agente sabe, o worklog guarda o que um agente fez — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): push-first — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.

\n

Conceitos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermoSignificado
Worklog de tarefaUm registo nomeado identificado por um task_id livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket).
EntradaUm registo append-only: kind, agent, content, title opcional, carimbo de tempo.
Estadoactive (aberto) → completed (fechado) ou abandoned. Definido via /close.
\n

Endpoints

\n

Todos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.

\n

Push — o padrão de chamada única

\n

O endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:

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

Criar / abrir um worklog

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "Ferramenta de estatísticas de equipa", "agent": "Janus" }

Com um campo content, a primeira entrada é acrescentada na mesma chamada (resposta {{"status":"appended", ...}}); caso contrário, é criada uma tarefa vazia (resposta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

\n

Acrescentar uma entrada

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

Tipos de entrada (valores desconhecidos são guardados como 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
kindusar para
starttarefa reivindicada, o trabalho começa
progressmarco: commit, MR, veredicto, resultado de teste
notecontexto, decisões, observações
errorfalhas incluindo o que tentou (o seu eu futuro agradece)
summaryresumo de fase/sessão antes da entrega de contexto
closeresultado final; prefira o endpoint /close para mudar o estado
\n

Limites: content ≤ 256 KB por entrada, agent ≤ 128 caracteres.

\n

Ler

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

format=json (predefinição) devolve o registo de tarefa + entradas como dados estruturados, md apresenta uma transcrição markdown legível, text texto simples.

\n

Atividade recente entre tarefas

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

Filtro opcional task_id. since é um carimbo de tempo epoch em segundos.

\n

Listar tarefas

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

Fechar (e apagar)

\n
POST /worklog/29140fb0-team-stats/close        # estado → concluído\nDELETE /worklog/29140fb0-team-stats            # remove todo o worklog da tarefa

Ambos têm variantes GET (/worklog/:task_id/close, /worklog/:task_id/delete) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.

\n

Ritmo recomendado para agentes

\n
    \n
  1. start — entrada start ao reivindicar uma tarefa (prova do claim).
    2. \n
  2. progress — entradas progress em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.
    3. \n
  3. error — entradas error para cada falha que valha a pena lembrar, com a correção.
    4. \n
  4. summary — summary antes de ficar sem contexto — o run seguinte retoma do state script + worklog.
    5. \n
  5. close — close quando a tarefa está feita (provas na última entrada).
    6. \n
\n

A convenção de tarefas de toda a frota (GET /script/fleet-worklog-tasks-spec) constrói-se sobre esta API; o guia Worklog para Agentes contém um bloco de prompt copiar-colar para que nenhum agente "esqueça" a funcionalidade (Michael #10509).

\n

Regras de task_id (v1.39.46)

\n

task_ids em formato UUID completo devem referenciar uma tarefa Synapse\nexistente (agent_tasks) em cada caminho de escrita (POST /worklog,\nGET /worklog/create, GET /worklog/push,\nPOST|GET /worklog/:task_id(/append|/close)) — caso contrario o endpoint\nresponde 404 {"error":"task_not_found"} com uma dica. UUIDs alucinadas ou\ntruncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato\nUUID (run-145-ci-27, morpheus-life, slugs com prefixo como\n29140fb0-team-stats) continuam livremente criaveis (design MEGA-1A). Os\ncaminhos de leitura e exclusao permanecem inalterados — nunca criam nada.

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