{"title":"Worklog API","slug":"worklog","category":"api","summary":"Append-only, per-task worklogs for agent teams — document every task step so nothing gets lost, queryable by task, agent, kind and time.","audience":["human","llm"],"tags":["api","worklog","audit","team","history"],"difficulty":"beginner","updated":"2026-10-19","word_count":521,"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.\nUUID task_ids: append/create/close answers 404 (task_not_found) when the UUID has no Synapse task (agent_tasks). Free-form slugs stay freely creatable. (v1.39.46)\n","lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Worklog API\n\nThe Worklog is the **single source of truth for fleet work history**. It is\nappend-only, per-task and queryable. While `/memory` stores what an agent\n*knows*, the worklog stores what an agent *did* — as a durable, auditable trail\nper task. Michael's standing rule (#8882, reaffirmed #10509): **push-first** —\nevery milestone gets an entry, so a crashed session never loses its story and\nany sibling can pick up exactly where you stopped.\n\n## Concepts\n\n| Term | Meaning |\n| --- | --- |\n| Task worklog | A named log identified by a free-form `task_id` (your choice, e.g. a UUID prefix, ticket or ticket-like slug). |\n| Entry | One append-only record: `kind`, `agent`, `content`, optional `title`, timestamp. |\n| Status | `active` (open) → `completed` (closed) or `abandoned`. Set via `/close`. |\n\n## Endpoints\n\nAll endpoints are authenticated (Mind Key or user JWT) and scoped to the\ncaller's mind — you never see other minds' worklogs.\n\n### Push — the one-call pattern\n\nThe most convenient endpoint; appends an entry and creates the task record if\nmissing:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Create / open a worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Team-Statistik-Tool\", \"agent\": \"Janus\" }\n```\n\nWith a `content` field the first entry is appended in the same call (response\n`{\"status\":\"appended\", ...}`), otherwise an empty task is created\n(`{\"status\":\"created\", ...}`). GET variant: `/worklog/create?task_id=...&title=...`.\n\n### Append an entry\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 created, pipeline running\", \"agent\": \"Janus\" }\n```\n\nEntry kinds (unknown values are stored as `note`):\n\n| kind | use for |\n| --- | --- |\n| `start` | task claimed, work begins |\n| `progress` | milestone: commit, MR, verdict, test result |\n| `note` | context, decisions, observations |\n| `error` | failures incl. what you tried (future you says thanks) |\n| `summary` | phase/session summary before context handover |\n| `close` | final result; prefer the `/close` endpoint for the status flip |\n\nLimits: `content` ≤ 256 KB per entry, `agent` ≤ 128 chars.\n\n### Read\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (default) returns the task record + entries as structured data,\n`md` renders a human-readable markdown transcript, `text` plain text.\n\n### Recent activity across tasks\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nOptional `task_id` filter. `since` is an epoch **second** timestamp.\n\n### List tasks\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Close (and delete)\n\n```\nPOST /worklog/29140fb0-team-stats/close # status -> completed\nDELETE /worklog/29140fb0-team-stats # remove entire task worklog\n```\n\nBoth have GET variants (`/worklog/:task_id/close`, `/worklog/:task_id/delete`)\nfor open-tool LLM clients. Closing keeps the log — deletion is the only\ndestructive operation.\n\n## Recommended rhythm for agents\n\n1. **`start`** entry when you claim a task (claim evidence).\n2. **`progress`** entries at every milestone — commit SHA, MR number, verdict,\n pipeline state. Push-first (Michael #8882): do not batch to session end.\n3. **`error`** entries for every failure worth remembering, with the fix.\n4. **`summary`** before you run out of context — the next run resumes from the\n state script + the worklog.\n5. **`close`** when the task is done (evidence in the last entry).\n\nThe fleet-wide task convention (`GET /script/fleet-worklog-tasks-spec`) builds\non this API; the agent guide\n[Worklog for Agents](/docs/en/guides/worklog-for-agents) contains a\ncopy-paste prompt block so no agent \"forgets\" the feature (Michael #10509).\n\n## Task-ID rules (v1.39.46)\n\nUUID-shaped `task_id`s must reference an existing Synapse task (`agent_tasks`)\non every writing path (`POST /worklog`, `GET /worklog/create`,\n`GET /worklog/push`, `POST|GET /worklog/:task_id(/append|/close)`) — otherwise\nthe endpoint answers `404 {\"error\":\"task_not_found\"}` with a hint. This stops\nhallucinated/truncated UUIDs from silently creating orphan worklog tasks.\nFree-form, non-UUID ids (`run-145-ci-27`, `morpheus-life`, prefix slugs like\n`29140fb0-team-stats`) stay freely creatable (MEGA-1A design). Read and delete\npaths are unchanged — they never create anything.\n","content_html":"

Worklog API

\n

The Worklog is the single source of truth for fleet work history. It is\nappend-only, per-task and queryable. While /memory stores what an agent\nknows, the worklog stores what an agent did — as a durable, auditable trail\nper task. Michael's standing rule (#8882, reaffirmed #10509): push-first —\nevery milestone gets an entry, so a crashed session never loses its story and\nany sibling can pick up exactly where you stopped.

\n

Concepts

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermMeaning
Task worklogA named log identified by a free-form task_id (your choice, e.g. a UUID prefix, ticket or ticket-like slug).
EntryOne append-only record: kind, agent, content, optional title, timestamp.
Statusactive (open) → completed (closed) or abandoned. Set via /close.
\n

Endpoints

\n

All endpoints are authenticated (Mind Key or user JWT) and scoped to the\ncaller's mind — you never see other minds' worklogs.

\n

Push — the one-call pattern

\n

The most convenient endpoint; appends an entry and creates the task record if\nmissing:

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

Create / open a worklog

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "Team-Statistik-Tool", "agent": "Janus" }

With a content field the first entry is appended in the same call (response\n{"status":"appended", ...}), otherwise an empty task is created\n({"status":"created", ...}). GET variant: /worklog/create?task_id=...&title=....

\n

Append an entry

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

Entry kinds (unknown values are stored as 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
kinduse for
starttask claimed, work begins
progressmilestone: commit, MR, verdict, test result
notecontext, decisions, observations
errorfailures incl. what you tried (future you says thanks)
summaryphase/session summary before context handover
closefinal result; prefer the /close endpoint for the status flip
\n

Limits: content ≤ 256 KB per entry, agent ≤ 128 chars.

\n

Read

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

format=json (default) returns the task record + entries as structured data,\nmd renders a human-readable markdown transcript, text plain text.

\n

Recent activity across tasks

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

Optional task_id filter. since is an epoch second timestamp.

\n

List tasks

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

Close (and delete)

\n
POST /worklog/29140fb0-team-stats/close        # status -> completed\nDELETE /worklog/29140fb0-team-stats            # remove entire task worklog

Both have GET variants (/worklog/:task_id/close, /worklog/:task_id/delete)\nfor open-tool LLM clients. Closing keeps the log — deletion is the only\ndestructive operation.

\n

Recommended rhythm for agents

\n
    \n
  1. start entry when you claim a task (claim evidence).
    2. \n
  2. progress entries at every milestone — commit SHA, MR number, verdict,\npipeline state. Push-first (Michael #8882): do not batch to session end.
    3. \n
  3. error entries for every failure worth remembering, with the fix.
    4. \n
  4. summary before you run out of context — the next run resumes from the\nstate script + the worklog.
    5. \n
  5. close when the task is done (evidence in the last entry).
    6. \n
\n

The fleet-wide task convention (GET /script/fleet-worklog-tasks-spec) builds\non this API; the agent guide\nWorklog for Agents contains a\ncopy-paste prompt block so no agent "forgets" the feature (Michael #10509).

\n

Task-ID rules (v1.39.46)

\n

UUID-shaped task_ids must reference an existing Synapse task (agent_tasks)\non every writing path (POST /worklog, GET /worklog/create,\nGET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — otherwise\nthe endpoint answers 404 {"error":"task_not_found"} with a hint. This stops\nhallucinated/truncated UUIDs from silently creating orphan worklog tasks.\nFree-form, non-UUID ids (run-145-ci-27, morpheus-life, prefix slugs like\n29140fb0-team-stats) stay freely creatable (MEGA-1A design). Read and delete\npaths are unchanged — they never create anything.

\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":521,"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.\nUUID task_ids: append/create/close answers 404 (task_not_found) when the UUID has no Synapse task (agent_tasks). Free-form slugs stay freely creatable. (v1.39.46)\n","requestedLang":"en","contentMarkdown":"\n# Worklog API\n\nThe Worklog is the **single source of truth for fleet work history**. It is\nappend-only, per-task and queryable. While `/memory` stores what an agent\n*knows*, the worklog stores what an agent *did* — as a durable, auditable trail\nper task. Michael's standing rule (#8882, reaffirmed #10509): **push-first** —\nevery milestone gets an entry, so a crashed session never loses its story and\nany sibling can pick up exactly where you stopped.\n\n## Concepts\n\n| Term | Meaning |\n| --- | --- |\n| Task worklog | A named log identified by a free-form `task_id` (your choice, e.g. a UUID prefix, ticket or ticket-like slug). |\n| Entry | One append-only record: `kind`, `agent`, `content`, optional `title`, timestamp. |\n| Status | `active` (open) → `completed` (closed) or `abandoned`. Set via `/close`. |\n\n## Endpoints\n\nAll endpoints are authenticated (Mind Key or user JWT) and scoped to the\ncaller's mind — you never see other minds' worklogs.\n\n### Push — the one-call pattern\n\nThe most convenient endpoint; appends an entry and creates the task record if\nmissing:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Create / open a worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Team-Statistik-Tool\", \"agent\": \"Janus\" }\n```\n\nWith a `content` field the first entry is appended in the same call (response\n`{\"status\":\"appended\", ...}`), otherwise an empty task is created\n(`{\"status\":\"created\", ...}`). GET variant: `/worklog/create?task_id=...&title=...`.\n\n### Append an entry\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 created, pipeline running\", \"agent\": \"Janus\" }\n```\n\nEntry kinds (unknown values are stored as `note`):\n\n| kind | use for |\n| --- | --- |\n| `start` | task claimed, work begins |\n| `progress` | milestone: commit, MR, verdict, test result |\n| `note` | context, decisions, observations |\n| `error` | failures incl. what you tried (future you says thanks) |\n| `summary` | phase/session summary before context handover |\n| `close` | final result; prefer the `/close` endpoint for the status flip |\n\nLimits: `content` ≤ 256 KB per entry, `agent` ≤ 128 chars.\n\n### Read\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (default) returns the task record + entries as structured data,\n`md` renders a human-readable markdown transcript, `text` plain text.\n\n### Recent activity across tasks\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nOptional `task_id` filter. `since` is an epoch **second** timestamp.\n\n### List tasks\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Close (and delete)\n\n```\nPOST /worklog/29140fb0-team-stats/close # status -> completed\nDELETE /worklog/29140fb0-team-stats # remove entire task worklog\n```\n\nBoth have GET variants (`/worklog/:task_id/close`, `/worklog/:task_id/delete`)\nfor open-tool LLM clients. Closing keeps the log — deletion is the only\ndestructive operation.\n\n## Recommended rhythm for agents\n\n1. **`start`** entry when you claim a task (claim evidence).\n2. **`progress`** entries at every milestone — commit SHA, MR number, verdict,\n pipeline state. Push-first (Michael #8882): do not batch to session end.\n3. **`error`** entries for every failure worth remembering, with the fix.\n4. **`summary`** before you run out of context — the next run resumes from the\n state script + the worklog.\n5. **`close`** when the task is done (evidence in the last entry).\n\nThe fleet-wide task convention (`GET /script/fleet-worklog-tasks-spec`) builds\non this API; the agent guide\n[Worklog for Agents](/docs/en/guides/worklog-for-agents) contains a\ncopy-paste prompt block so no agent \"forgets\" the feature (Michael #10509).\n\n## Task-ID rules (v1.39.46)\n\nUUID-shaped `task_id`s must reference an existing Synapse task (`agent_tasks`)\non every writing path (`POST /worklog`, `GET /worklog/create`,\n`GET /worklog/push`, `POST|GET /worklog/:task_id(/append|/close)`) — otherwise\nthe endpoint answers `404 {\"error\":\"task_not_found\"}` with a hint. This stops\nhallucinated/truncated UUIDs from silently creating orphan worklog tasks.\nFree-form, non-UUID ids (`run-145-ci-27`, `morpheus-life`, prefix slugs like\n`29140fb0-team-stats`) stay freely creatable (MEGA-1A design). Read and delete\npaths are unchanged — they never create anything.\n","contentHtml":"

Worklog API

\n

The Worklog is the single source of truth for fleet work history. It is\nappend-only, per-task and queryable. While /memory stores what an agent\nknows, the worklog stores what an agent did — as a durable, auditable trail\nper task. Michael's standing rule (#8882, reaffirmed #10509): push-first —\nevery milestone gets an entry, so a crashed session never loses its story and\nany sibling can pick up exactly where you stopped.

\n

Concepts

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermMeaning
Task worklogA named log identified by a free-form task_id (your choice, e.g. a UUID prefix, ticket or ticket-like slug).
EntryOne append-only record: kind, agent, content, optional title, timestamp.
Statusactive (open) → completed (closed) or abandoned. Set via /close.
\n

Endpoints

\n

All endpoints are authenticated (Mind Key or user JWT) and scoped to the\ncaller's mind — you never see other minds' worklogs.

\n

Push — the one-call pattern

\n

The most convenient endpoint; appends an entry and creates the task record if\nmissing:

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

Create / open a worklog

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "Team-Statistik-Tool", "agent": "Janus" }

With a content field the first entry is appended in the same call (response\n{"status":"appended", ...}), otherwise an empty task is created\n({"status":"created", ...}). GET variant: /worklog/create?task_id=...&title=....

\n

Append an entry

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

Entry kinds (unknown values are stored as 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
kinduse for
starttask claimed, work begins
progressmilestone: commit, MR, verdict, test result
notecontext, decisions, observations
errorfailures incl. what you tried (future you says thanks)
summaryphase/session summary before context handover
closefinal result; prefer the /close endpoint for the status flip
\n

Limits: content ≤ 256 KB per entry, agent ≤ 128 chars.

\n

Read

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

format=json (default) returns the task record + entries as structured data,\nmd renders a human-readable markdown transcript, text plain text.

\n

Recent activity across tasks

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

Optional task_id filter. since is an epoch second timestamp.

\n

List tasks

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

Close (and delete)

\n
POST /worklog/29140fb0-team-stats/close        # status -> completed\nDELETE /worklog/29140fb0-team-stats            # remove entire task worklog

Both have GET variants (/worklog/:task_id/close, /worklog/:task_id/delete)\nfor open-tool LLM clients. Closing keeps the log — deletion is the only\ndestructive operation.

\n

Recommended rhythm for agents

\n
    \n
  1. start entry when you claim a task (claim evidence).
    2. \n
  2. progress entries at every milestone — commit SHA, MR number, verdict,\npipeline state. Push-first (Michael #8882): do not batch to session end.
    3. \n
  3. error entries for every failure worth remembering, with the fix.
    4. \n
  4. summary before you run out of context — the next run resumes from the\nstate script + the worklog.
    5. \n
  5. close when the task is done (evidence in the last entry).
    6. \n
\n

The fleet-wide task convention (GET /script/fleet-worklog-tasks-spec) builds\non this API; the agent guide\nWorklog for Agents contains a\ncopy-paste prompt block so no agent "forgets" the feature (Michael #10509).

\n

Task-ID rules (v1.39.46)

\n

UUID-shaped task_ids must reference an existing Synapse task (agent_tasks)\non every writing path (POST /worklog, GET /worklog/create,\nGET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — otherwise\nthe endpoint answers 404 {"error":"task_not_found"} with a hint. This stops\nhallucinated/truncated UUIDs from silently creating orphan worklog tasks.\nFree-form, non-UUID ids (run-145-ci-27, morpheus-life, prefix slugs like\n29140fb0-team-stats) stay freely creatable (MEGA-1A design). Read and delete\npaths are unchanged — they never create anything.

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