Списки и участники · Документация

Списки группируют задачи, разделы делят список на части, а участники — это те, кого можно назначить исполнителем. Скоупы: lists:read и lists:write для списков и разделов, members:read для участников.

Объект списка

Поле	Тип	Описание
`id`	string	Идентификатор вида `lst_R4m2Vx`. Только чтение.
`name`	string	Название списка. Обязательно при создании.
`description`	string \| null	Короткое описание: зачем список и что в нём лежит.
`color`	string	Цвет метки: `violet`, `coral`, `amber`, `sage`, `sky` или `ink`. По умолчанию `violet`.
`archived`	boolean	В архиве ли список. Только чтение — меняется методом `/archive`.
`task_count`	integer	Задач в списке, включая выполненные. Не больше 5 000.
`open_task_count`	integer	Открытых задач.
`created_at`, `updated_at`	string	ISO 8601, UTC.
`url`	string	Ссылка на список в веб-приложении.

GET /lists — все списки

Возвращает списки, к которым у владельца токена есть доступ. По умолчанию — только активные, с archived=true — только архивные. Пагинация — как у всех коллекций: limit и cursor.

bash

curl "https://doneby.app/api/v1/lists?limit=50" \
  -H "Authorization: Bearer $DONEBY_TOKEN"

Ответ

{
  "data": [
    {
      "id": "lst_R4m2Vx",
      "name": "Релиз 2.4",
      "description": "Всё, что должно уехать в релиз до четверга.",
      "color": "violet",
      "archived": false,
      "task_count": 38,
      "open_task_count": 7,
      "created_at": "2026-08-25T06:00:12Z",
      "updated_at": "2026-09-15T11:47:30Z",
      "url": "https://doneby.app/app/list/lst_R4m2Vx"
    },
    {
      "id": "lst_Ka7Tp3",
      "name": "Клиент: магазин чая",
      "description": null,
      "color": "amber",
      "archived": false,
      "task_count": 24,
      "open_task_count": 5,
      "created_at": "2026-07-02T10:31:44Z",
      "updated_at": "2026-09-15T08:20:14Z",
      "url": "https://doneby.app/app/list/lst_Ka7Tp3"
    }
  ],
  "next_cursor": null
}

POST /lists — создать список

Обязательно только name. Ответ — 201 Created и созданный список, уходит вебхук list.created. Владелец токена становится участником списка; кого ещё добавить, настраивается в приложении — см. Совместные списки и гости.

bash

curl -X POST https://doneby.app/api/v1/lists \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d41c7b2-6e3f-4a90-b1d5-f27a0c9e8b14" \
  -d '{
    "name": "Контент-план · ноябрь",
    "color": "coral",
    "description": "Статьи, рассылки и обложки на ноябрь."
  }'

PATCH /lists/{id} — изменить список

Меняет name, description и color. Передавайте только то, что меняется.

bash

curl -X PATCH https://doneby.app/api/v1/lists/lst_R4m2Vx \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Релиз 2.4 · хотфиксы", "color": "sky"}'

POST /lists/{id}/archive — в архив

Список пропадает из боковой панели и представлений: его задачи больше не попадают в «Сегодня» и «Неделю», напоминания по ним не приходят. Задачи не удаляются — через API их можно читать, но не менять (422 unprocessable). Уходит вебхук list.archived.

bash

curl -X POST https://doneby.app/api/v1/lists/lst_R4m2Vx/archive \
  -H "Authorization: Bearer $DONEBY_TOKEN"

Вернуть список из архива можно в приложении: меню списка → «Вернуть из архива».

Совет

Перед архивацией проверьте, не осталось ли открытых задач: GET /tasks?list_id=lst_R4m2Vx&completed=false. В архиве их никто не увидит, и напоминаний по ним не будет.

Разделы

Раздел — заголовок внутри списка: «Дизайн», «Вёрстка», «Тесты». У задачи может быть один раздел (section_id) или ни одного. Разделы читаются со скоупом lists:read, меняются — с lists:write.

Метод	Что делает
`GET /lists/{id}/sections`	Разделы списка по порядку.
`POST /lists/{id}/sections`	Создать раздел: `name`, необязательный `position`.
`PATCH /lists/{id}/sections/{section_id}`	Переименовать или переставить раздел.
`DELETE /lists/{id}/sections/{section_id}`	Удалить раздел. Задачи остаются в списке без раздела.

position — порядковый номер с нуля. Остальные разделы сдвигаются сами; без position новый раздел встаёт в конец.

Создать раздел

curl -X POST https://doneby.app/api/v1/lists/lst_R4m2Vx/sections \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Тесты", "position": 1}'

Ответ · 201 Created

{
  "id": "sec_Wq3Hn5",
  "list_id": "lst_R4m2Vx",
  "name": "Тесты",
  "position": 1,
  "created_at": "2026-09-15T12:02:51Z"
}

GET /members — участники

Участники рабочего пространства и их роли. Нужен скоуп members:read. id участника — то самое значение, которое передаётся в assignee_ids задачи. Фильтр по роли — параметр role, например ?role=guest.

`role` в API	Роль	Что может
`owner`	Владелец	Оплата, удаление пространства, передача прав. Один на пространство.
`admin`	Администратор	Участники и роли, настройки, интеграции, все списки.
`member`	Участник	Создаёт списки и задачи, работает в списках, куда добавлен.
`guest`	Гость	Видит только списки, которыми с ним поделились. Комментирует и отмечает свои задачи.

bash

curl "https://doneby.app/api/v1/members?limit=50" \
  -H "Authorization: Bearer $DONEBY_TOKEN"

Ответ

{
  "data": [
    {
      "id": "usr_Ma1nL6",
      "name": "Марина Лаптева",
      "email": "marina@example.com",
      "role": "admin",
      "timezone": "Europe/Moscow",
      "joined_at": "2026-03-11T08:15:00Z"
    },
    {
      "id": "usr_Ol3gD7",
      "name": "Олег Дьяченко",
      "email": "oleg@example.com",
      "role": "member",
      "timezone": "Asia/Yekaterinburg",
      "joined_at": "2026-04-02T12:40:19Z"
    },
    {
      "id": "usr_Sv2tP9",
      "name": "Света Панина",
      "email": "sveta@example.com",
      "role": "guest",
      "timezone": "Europe/Moscow",
      "joined_at": "2026-09-01T07:05:33Z"
    }
  ],
  "next_cursor": null
}

Важно

Приглашать и удалять участников, менять роли через API нельзя — только в Настройки → Участники. Так управление доступом к пространству не уходит во внешние системы.

Совет

Состав команды меняется редко. Кэшируйте ответ GET /members и обновляйте кэш по вебхуку member.joined — это экономит запросы при каждом назначении исполнителя.