# Worklog 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.

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 answers 404 (task_not_found) when the UUID has no Synapse task (agent_tasks). Free-form slugs stay freely creatable. (v1.39.46)

Worklog API
The Worklog is the single source of truth for fleet work history. It is
append-only, per-task and queryable. While  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  (your choice, e.g. a UUID prefix, ticket or ticket-like slug). |
| Entry | One append-only record: , , , optional , timestamp. |
| Status |  (open) →  (closed) or . Set via . |
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:
[CODE BLOCK]
Create / open a worklog
[CODE BLOCK]
With a  field the first entry is appended in the same call (response
), otherwise an empty task is created
(). GET variant: .
Append an entry
[CODE BLOCK]
Entry kinds (unknown values are stored as ):
| kind | use for |
| --- | --- |
|  | task claimed, work begins |
|  | milestone: commit, MR, verdict, test result |
|  | context, decisions, observations |
|  | failures incl. what you tried (future you says thanks) |
|  | phase/session summary before context handover |
|  | final result; prefer the  endpoint for the status flip |
Limits:  ≤ 256 KB per entry,  ≤ 128 chars.
Read
[CODE BLOCK]
 (default) returns the task record + entries as structured data,
 renders a human-readable markdown transcript,  plain text.
Recent activity across tasks
[CODE BLOCK]
Optional  filter.  is an epoch second timestamp.
List tasks
[CODE BLOCK]
Close (and delete)
[CODE BLOCK]
Both have GET variants (, )
for open-tool LLM clients. Closing keeps the log — deletion is the only
destructive operation.
Recommended rhythm for agents
1.  entry when you claim a task (claim evidence).
2.  entries at every milestone — commit SHA, MR number, verdict,
   pipeline state. Push-first (Michael #8882): do not batch to session end.
3.  entries for every failure worth remembering, with the fix.
4.  before you run out of context — the next run resumes from the
   state script + the worklog.
5.  when the task is done (evidence in the last entry).
The fleet-wide task convention () 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 s must reference an existing Synapse task ()
on every writing path (, ,
, ) — otherwise
the endpoint answers  with a hint. This stops
hallucinated/truncated UUIDs from silently creating orphan worklog tasks.
Free-form, non-UUID ids (, , prefix slugs like
) stay freely creatable (MEGA-1A design). Read and delete
paths are unchanged — they never create anything.