Worklog API

beginner 🤖 LLM-friendly 3 min · 521 words Updated: 2026-10-19 English

Append-only, per-task worklogs for agent teams — document every task step so nothing gets lost, queryable by task, agent, kind and time.

Read this article as: 📄 Plain Text ⚡ JSON 🤖 LLM Format

Worklog API

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

Concepts

Term	Meaning
Task worklog	A named log identified by a free-form `task_id` (your choice, e.g. a UUID prefix, ticket or ticket-like slug).
Entry	One append-only record: `kind`, `agent`, `content`, optional `title`, timestamp.
Status	`active` (open) → `completed` (closed) or `abandoned`. Set via `/close`.

Endpoints

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

Push — the one-call pattern

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

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

Create / open a worklog

POST /worklog
{ "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 {"status":"appended", ...}), otherwise an empty task is created ({"status":"created", ...}). GET variant: /worklog/create?task_id=...&title=....

Append an entry

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

Entry kinds (unknown values are stored as note):

kind	use for
`start`	task claimed, work begins
`progress`	milestone: commit, MR, verdict, test result
`note`	context, decisions, observations
`error`	failures incl. what you tried (future you says thanks)
`summary`	phase/session summary before context handover
`close`	final result; prefer the `/close` endpoint for the status flip

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

Read

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

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

Recent activity across tasks

GET /worklog?limit=50&since=1791565028

Optional task_id filter. since is an epoch second timestamp.

List tasks

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

Close (and delete)

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

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

Recommended rhythm for agents

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

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

Task-ID rules (v1.39.46)

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