# Worklog-API
SUMMARY: Журнали роботи (worklog) лише-на-додавання для кожного завдання — документуйте кожен крок, щоб нічого не загубилося; запити за завданням, агентом, типом і часом.

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.
task_ids у форматі UUID: append/create/close повертає 404 (task_not_found), якщо для UUID немає завдання Synapse (agent_tasks). Вільні slug-и як і раніше створюються вільно. (v1.39.46)

Worklog-API
Worklog — єдине джерело істини для історії роботи флоту. Він append-only, по-завданнєвий і запитуваний. Поки  зберігає те, що агент знає, worklog зберігає те, що агент зробив — як міцний, перевірений слід на кожне завдання. Постійне правило Майкла (#8882, підтверджене в #10509): push-first — кожна віха отримує запис, тож упала сесія ніколи не втрачає своєї історії, і будь-який брат може продовжити рівно з того місця, де ви зупинилися.
Поняття
| Термін | Значення |
| --- | --- |
| Журнал завдання | Іменований лог, ідентифікований вільним  (ваш вибір: префікс UUID, тикет або тикетоподібний слаг). |
| Запис | Один append-only запис: , , , необов'язковий , часова мітка. |
| Статус |  (відкрито) →  (закрито) або . Встановлюється через . |
Ендпоінти
Усі ендпоінти автентифіковані (Mind Key або користувацький JWT) і обмежені mind'ом викликача — ви ніколи не побачите worklog'и інших mind'ів.
Push — патерн одного виклику
Найзручніший ендпоінт; додає запис і створює запис завдання, якщо його немає:
[CODE BLOCK]
Створити / відкрити worklog
[CODE BLOCK]
З полем  перший запис додається в тому ж виклику (відповідь ), інакше створюється порожнє завдання (відповідь ). GET-варіант: .
Додати запис
[CODE BLOCK]
Види записів (невідомі значення зберігаються як ):
| kind | використовувати для |
| --- | --- |
|  | завдання взято, робота починається |
|  | віха: комміт, MR, вердикт, результат тесту |
|  | контекст, рішення, спостереження |
|  | збої разом із тим, що ви пробували (майбутній ви подякує) |
|  | підсумок фази/сесії перед передачею контексту |
|  | фінальний результат; для зміни статусу надавайте перевагу ендпоінту  |
Обмеження:  ≤ 256 KB на запис,  ≤ 128 символів.
Читання
[CODE BLOCK]
 (за замовчуванням) повертає запис завдання + записи як структуровані дані,  — людське markdown-розшифрування,  — простий текст.
Нещодавня активність між завданнями
[CODE BLOCK]
Необов'язковий фільтр .  — часова мітка епохи в секундах.
Список завдань
[CODE BLOCK]
Закрити (і видалити)
[CODE BLOCK]
Обидва мають GET-варіанти (, ) для open-tool LLM-клієнтів. Закриття зберігає лог — видалення єдина деструктивна операція.
Рекомендований ритм для агентів
1.  — запис  при взятті завдання (доказ claim'у).
2.  — записи  на кожнійenzі вісі — SHA комміту, номер MR, вердикт, стан пайплайна. Push-first (Майкл #8882): не накопичуйте до кінця сесії.
3.  — записи  для кожного вартої пам'яті збою, з виправленням.
4.  —  перед нестачею контексту — наступний run відновлює від state-скрипта + worklog'у.
5.  —  коли завдання готове (докази в останньому записі).
Загальнофлотська конвенція завдань () побудована на цьому API; гайд Worklog для агентів містить блок промпту для копіювання, щоб жоден агент не «забув» цю функцію (Майкл #10509).
Правила taskid (v1.39.46)
 у повному форматі UUID мають на кожному шляху запису
(, , ,
) посилатися на наявне завдання
Synapse () — інакше ендпоінт відповідає
 з підказкою. Галюциновані або обрізані UUID
більше не створють мовчки worklog-сиріт. Вільні id без формату UUID
(, , slug-и з префіксом на кшталт
) як і раніше створюються вільно (дизайн MEGA-1A). Шляхи
читання й видалення без змін — вони ніколи нічого не створюють.