Задачи
Получить, создать, изменить, выполнить и удалить задачу.
Задача — главный объект DoneBy. Через API её можно получить, создать, изменить, отметить выполненной, вернуть в работу и удалить. Для чтения нужен скоуп tasks:read, для изменений — tasks:write.
| Метод | Что делает |
|---|---|
GET /tasks | Список задач с фильтрами |
GET /tasks/{id} | Одна задача |
POST /tasks | Создать задачу или подзадачу |
PATCH /tasks/{id} | Изменить поля задачи |
POST /tasks/{id}/complete | Отметить выполненной |
POST /tasks/{id}/reopen | Вернуть в работу |
DELETE /tasks/{id} | Удалить |
GET /tasks/{id}/comments | Комментарии к задаче |
POST /tasks/{id}/comments | Добавить комментарий |
Объект задачи
| Поле | Тип | Описание |
|---|---|---|
id | string | Идентификатор вида tsk_8Kd2Lq. Только чтение. |
title | string | Название, до 500 символов. Обязательно при создании. |
notes | string | null | Описание в Markdown, до 20 000 символов. |
list_id | string | null | Список. Если не указать при создании, задача попадёт во «Входящие» владельца токена. |
section_id | string | null | Раздел внутри списка. Должен принадлежать тому же list_id. |
parent_id | string | null | Для подзадачи — id родительской задачи. Задаётся только при создании. |
due_date | string | null | Дата срока: YYYY-MM-DD. |
due_time | string | null | Время срока: HH:MM. null — срок на весь день. Без due_date не задаётся. |
timezone | string | Часовой пояс срока в формате IANA, например Europe/Moscow. По умолчанию — пояс пространства. |
priority | integer | 0 — без приоритета, 1 — P1 (самый высокий), 2 — P2, 3 — P3. |
assignee_ids | string[] | Исполнители — id участников из списка участников. Пустой массив — без исполнителя. |
repeat | string | null | Правило повтора в стиле RRULE, например FREQ=WEEKLY;BYDAY=FR. См. ниже. |
subtasks | object[] | Краткие карточки подзадач: id, title, completed, due_date, assignee_ids. Только чтение. До 100 у задачи. |
checklist | object[] | Пункты чек-листа: id, text, checked. До 200 пунктов. |
completed | boolean | Выполнена ли задача. Только чтение — меняется методами /complete и /reopen. |
completed_at | string | null | Когда задачу выполнили. ISO 8601, UTC. |
created_at | string | Когда задачу создали. ISO 8601, UTC. |
updated_at | string | Когда задачу меняли последний раз. По этому полю удобно синхронизироваться. |
url | string | Ссылка на задачу в веб-приложении. |
{
"id": "tsk_8Kd2Lq",
"title": "Подготовить отчёт за сентябрь",
"notes": "Выручка по каталогу, возвраты, план на октябрь.",
"list_id": "lst_Ka7Tp3",
"section_id": "sec_Rp4Ze8",
"parent_id": null,
"due_date": "2026-09-30",
"due_time": "15:00",
"timezone": "Europe/Moscow",
"priority": 2,
"assignee_ids": ["usr_Ol3gD7"],
"repeat": null,
"subtasks": [
{
"id": "tsk_9Lm3Wr",
"title": "Выгрузить продажи",
"completed": true,
"due_date": "2026-09-28",
"assignee_ids": ["usr_Ol3gD7"]
},
{
"id": "tsk_9Lm3Ws",
"title": "Свести возвраты",
"completed": false,
"due_date": null,
"assignee_ids": []
}
],
"checklist": [
{ "id": "chk_1Qa7", "text": "Сверить цифры с бухгалтерией", "checked": false },
{ "id": "chk_1Qa8", "text": "Отправить клиенту PDF", "checked": false }
],
"completed": false,
"completed_at": null,
"created_at": "2026-09-14T07:12:40Z",
"updated_at": "2026-09-16T10:05:11Z",
"url": "https://doneby.app/app/list/lst_Ka7Tp3?task=tsk_8Kd2Lq"
}Правило повтора
Поле repeat — строка вида КЛЮЧ=значение;КЛЮЧ=значение, похожая на RRULE из календарей. Поддерживаются FREQ (DAILY, WEEKLY, MONTHLY, YEARLY), INTERVAL, BYDAY, BYMONTHDAY, COUNT, UNTIL и FROM=COMPLETION — повтор от даты выполнения, а не по расписанию. Повтору нужен due_date: от него считается первое повторение.
| Строка | Что означает |
|---|---|
FREQ=DAILY | Каждый день |
FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR | По будням |
FREQ=WEEKLY;INTERVAL=2;BYDAY=MO | Каждый второй понедельник |
FREQ=MONTHLY;BYMONTHDAY=-1 | В последний день месяца |
FREQ=MONTHLY;BYDAY=1MO | В первый понедельник месяца |
FREQ=MONTHLY;COUNT=6 | Каждый месяц, шесть раз |
FREQ=WEEKLY;FROM=COMPLETION | Через неделю после того, как выполнили предыдущую |
Те же правила человеческим языком — в статье Правила повтора: примеры.
GET /tasks — список задач
Возвращает задачи, которые видит владелец токена, страницами по limit (см. пагинацию). Подзадачи тоже попадают в выдачу, если подходят под фильтр, — их легко узнать по parent_id.
| Параметр | Описание |
|---|---|
list_id | Только задачи из этого списка. |
assignee_id | Задачи, где участник среди исполнителей. Значение me — владелец токена. |
due_before | Срок не позже указанного, включительно: 2026-09-30 или 2026-09-30T18:00:00+03:00. |
due_after | Срок не раньше указанного, включительно. Формат тот же. |
completed | true — только выполненные, false — только открытые. Без параметра — все. |
updated_since | Задачи, изменённые после метки времени (ISO 8601 с поясом). С этим параметром выдача сортируется по updated_at. |
limit, cursor | Размер страницы (1–100, по умолчанию 50) и курсор следующей страницы. |
По умолчанию задачи отсортированы по сроку (задачи без срока — в конце), затем по дате создания.
curl -G https://doneby.app/api/v1/tasks \
-H "Authorization: Bearer $DONEBY_TOKEN" \
--data-urlencode "assignee_id=me" \
--data-urlencode "completed=false" \
--data-urlencode "due_before=2026-09-20" \
-d limit=20{
"data": [
{
"id": "tsk_3Vn7Hs",
"title": "Ревью PR: быстрые сроки в поле ввода",
"list_id": "lst_R4m2Vx",
"parent_id": null,
"due_date": "2026-09-15",
"due_time": "12:00",
"timezone": "Europe/Moscow",
"priority": 2,
"assignee_ids": ["usr_Me0001", "usr_Ti4mB8"],
"completed": false,
"updated_at": "2026-09-14T16:41:09Z"
},
{
"id": "tsk_6Pw0Ka",
"title": "Обновить changelog и заметки к релизу",
"list_id": "lst_R4m2Vx",
"parent_id": null,
"due_date": "2026-09-15",
"due_time": "17:00",
"timezone": "Europe/Moscow",
"priority": 0,
"assignee_ids": ["usr_Me0001"],
"completed": false,
"updated_at": "2026-09-12T09:03:27Z"
}
],
"next_cursor": null
}Совет
Для синхронизации храните updated_at последней полученной задачи и в следующий раз запрашивайте updated_since — придут только изменения. Удалённые задачи так не увидеть: на них подпишитесь вебхуком task.deleted.
GET /tasks/{id} — одна задача
Возвращает задачу целиком, вместе с подзадачами и чек-листом. Если задачи нет или владелец токена её не видит, ответ — 404 not_found: API не различает эти случаи, чтобы не раскрывать чужие данные.
curl https://doneby.app/api/v1/tasks/tsk_8Kd2Lq \
-H "Authorization: Bearer $DONEBY_TOKEN"POST /tasks — создать задачу
Обязательно только title. Остальные поля — как в объекте задачи, кроме полей только для чтения. Ответ — 201 Created и созданная задача. Передавайте Idempotency-Key, чтобы повтор запроса не создал дубль.
curl -X POST https://doneby.app/api/v1/tasks \
-H "Authorization: Bearer $DONEBY_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2c5d7a1e-9b0f-4f6e-8d3a-71c4e2b9f805" \
-d '{
"title": "Созвон по правкам карточек товара",
"list_id": "lst_Ka7Tp3",
"due_date": "2026-09-18",
"due_time": "14:30",
"timezone": "Europe/Moscow",
"priority": 1,
"assignee_ids": ["usr_Ol3gD7", "usr_Me0001"],
"checklist": [
{ "text": "Собрать правки в один документ" },
{ "text": "Согласовать сроки переделки" }
]
}'{
"id": "tsk_4Gh8Np",
"title": "Созвон по правкам карточек товара",
"notes": null,
"list_id": "lst_Ka7Tp3",
"section_id": null,
"parent_id": null,
"due_date": "2026-09-18",
"due_time": "14:30",
"timezone": "Europe/Moscow",
"priority": 1,
"assignee_ids": ["usr_Ol3gD7", "usr_Me0001"],
"repeat": null,
"subtasks": [],
"checklist": [
{ "id": "chk_7Tz2", "text": "Собрать правки в один документ", "checked": false },
{ "id": "chk_7Tz3", "text": "Согласовать сроки переделки", "checked": false }
],
"completed": false,
"completed_at": null,
"created_at": "2026-09-15T08:20:14Z",
"updated_at": "2026-09-15T08:20:14Z",
"url": "https://doneby.app/app/list/lst_Ka7Tp3?task=tsk_4Gh8Np"
}Важно
Быстрый ввод в API не разбирается: "title": "Отчёт пт 15:00 !1" создаст задачу ровно с таким названием. Срок, приоритет и список передавайте отдельными полями.
Подзадача
Подзадача — обычная задача с parent_id. Она живёт в списке родителя, поэтому list_id для неё не передаётся. Вложенность — один уровень: у подзадачи не может быть своих подзадач. Лимит — 100 подзадач у одной задачи.
curl -X POST https://doneby.app/api/v1/tasks \
-H "Authorization: Bearer $DONEBY_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b3e6f9c-52a4-4d71-b8e0-9c1f7a2d4e36" \
-d '{
"title": "Свести возвраты",
"parent_id": "tsk_8Kd2Lq",
"due_date": "2026-09-29",
"assignee_ids": ["usr_Ol3gD7"]
}'PATCH /tasks/{id} — изменить задачу
Меняет только переданные поля и возвращает задачу целиком. null очищает поле: "due_date": null снимает срок вместе со временем, "repeat": null — повтор. Если передать новый list_id без section_id, раздел сбросится.
checklist передаётся целиком: пункты с id сохраняются и обновляются, пункты без id добавляются, а пункты, которых нет в массиве, удаляются. Подзадачи через PATCH родителя не меняются — у каждой свой id и свой PATCH.
curl -X PATCH https://doneby.app/api/v1/tasks/tsk_8Kd2Lq \
-H "Authorization: Bearer $DONEBY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"due_date": "2026-10-01",
"due_time": null,
"priority": 1,
"assignee_ids": ["usr_Ol3gD7", "usr_An9aK2"]
}'| Что нужно | Тело запроса |
|---|---|
| Перенести срок | {"due_date": "2026-10-01"} |
| Сделать срок на весь день | {"due_time": null} |
| Снять срок | {"due_date": null} |
| Убрать всех исполнителей | {"assignee_ids": []} |
| Перенести в другой список | {"list_id": "lst_R4m2Vx"} |
| Повторять каждую пятницу | {"repeat": "FREQ=WEEKLY;BYDAY=FR"} |
| Отметить пункт чек-листа | {"checklist": [{"id": "chk_1Qa7", "checked": true}, {"id": "chk_1Qa8"}]} |
POST /tasks/{id}/complete — выполнить
Отмечает задачу выполненной, ставит completed_at и отправляет вебхук task.completed. Повторный вызов для уже выполненной задачи ничего не меняет и возвращает 200. Тело запроса не обязательно.
Открытые подзадачи остаются открытыми. Чтобы закрыть их вместе с родителем, передайте {"include_subtasks": true}.
curl -X POST https://doneby.app/api/v1/tasks/tsk_8Kd2Lq/complete \
-H "Authorization: Bearer $DONEBY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"include_subtasks": true}'У повторяющейся задачи закрывается текущее повторение. В ответе задача остаётся открытой (completed: false), due_date переезжает на следующую дату по правилу, а completed_at хранит время последнего закрытого повторения.
{
"id": "tsk_2Fd9Ue",
"title": "Собрать дайджест обновлений",
"repeat": "FREQ=WEEKLY;BYDAY=FR",
"due_date": "2026-09-25",
"due_time": "12:00",
"completed": false,
"completed_at": "2026-09-18T09:14:52Z"
}POST /tasks/{id}/reopen — вернуть в работу
Снимает отметку: completed становится false, completed_at — null, уходит вебхук task.reopened. Срок не меняется: если он уже прошёл, задача сразу окажется просроченной — перенесите её через PATCH.
У повторяющейся задачи reopen не работает (422 unprocessable): следующее повторение уже назначено. Верните нужную дату через PATCH.
curl -X POST https://doneby.app/api/v1/tasks/tsk_8Kd2Lq/reopen \
-H "Authorization: Bearer $DONEBY_TOKEN"DELETE /tasks/{id} — удалить
Удаляет задачу вместе с подзадачами, чек-листом и комментариями. Ответ — 204 No Content без тела, уходит вебхук task.deleted. Через API удаление необратимо.
curl -X DELETE https://doneby.app/api/v1/tasks/tsk_8Kd2Lq \
-H "Authorization: Bearer $DONEBY_TOKEN"Важно
Если задача может понадобиться для истории или отчётов, не удаляйте её — выполните или перенесите в архивный список. Удалённую задачу не вернёт даже поддержка.
Комментарии
Комментарии читаются со скоупом comments:read и добавляются с comments:write — от имени владельца токена. GET /tasks/{id}/comments отдаёт их по времени, страницами, как все коллекции. Чтобы упомянуть участника, передайте его id в mentions: он получит уведомление так же, как при упоминании в приложении. Каждый новый комментарий отправляет вебхук comment.created.
curl -X POST https://doneby.app/api/v1/tasks/tsk_8Kd2Lq/comments \
-H "Authorization: Bearer $DONEBY_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5e2b9d14-7c3a-4f80-a6d1-3b8e0f2c9a57" \
-d '{
"text": "Цифры сверили, отчёт можно отправлять.",
"mentions": ["usr_Ol3gD7"]
}'{
"id": "cmt_4Rw8Yt",
"task_id": "tsk_8Kd2Lq",
"author_id": "usr_Me0001",
"text": "Цифры сверили, отчёт можно отправлять.",
"mentions": ["usr_Ol3gD7"],
"created_at": "2026-09-29T11:42:08Z"
}Ограничение
Комментарии через API не редактируются и не удаляются — это делается в приложении.
Типичные ошибки
| Ответ | Когда бывает |
|---|---|
400 validation_error | Нет title, дата в неверном формате, due_time без due_date, priority вне диапазона 0–3, метка времени без часового пояса. |
403 forbidden | У токена нет tasks:write, или роль владельца токена не позволяет менять задачи в этом списке. |
404 not_found | Задачи нет или владелец токена её не видит. |
409 conflict | Idempotency-Key уже использован с другим телом запроса. |
422 unprocessable | Список в архиве, в списке уже 5 000 задач, исполнитель не состоит в списке, у подзадачи пытаются создать подзадачу. |
Полный список кодов и что с ними делать — в разделе Коды ошибок.