APIProElite

Для работы с API вам нужен токен — это ключ доступа, который позволяет внешним системам подключаться к SingularityApp от вашего имени.

Токен работает как пропуск: вы выбираете, какие права даёте внешней системе (может ли она создавать задачи, редактировать проекты и т.д.), и система использует этот пропуск для доступа. Токен всегда привязан к одному аккаунту и работает только в нём.

Swagger — интерактивная документация API для изучения методов и тестирования запросов в браузере при условии, что токен уже получен.

Управление токенами (создание, удаление, обновление) производится в личном кабинете, а сами токены используются при отправке реальных запросов через скрипты и программы.

Все детали о работе с токенами и использовании Swagger мы разбираем ниже.

Для работы с API необходимо создать токен в личном кабинете:

1. В личном кабинете SingularityApp нужно перейти на экран «Доступ к API». Там вы увидите список существующих токенов и кнопку «Создать токен».
2. Нажмите на кнопку «Создать токен». Откроется окно с настройками.
3. В окне создания нужно:
   • Ввести название токена (любое произвольное название, которое поможет отличить его от других);
   • Выбрать сущности, с которыми этот токен может работать (задачи, проекты, привычки и т.д.):

     Например, если выбрать только «проект», токен сможет только создавать, изменять и удалять проекты. Если нужно работать со всеми сущности, выберите все.

4. После настройки нажмите «Создать токен».
5. После создания, токен появится в списке. Нажмите на Token — токен скопируется в буфер обмена. Эту строку вам нужно использовать в своих скриптах для авторизации в API. Передавайте этот токен в заголовке Authorization в формате Bearer token при каждом запросе к API.

Редактирование и удаление токена

Важно! Существующий токен нельзя отредактировать. Его можно только удалить и создать новый.

Чтобы удалить токен, нажмите на строку с нужным токеном в списке. Откроется детальный просмотр токена, где можно нажать «Удалить токен». После удаления токен станет недействительным.

Два основных вопроса при работе с API:

1. Где искать информацию о методах? (Ответ — Swagger).
2. Какие типы операций доступны? (Ответ — CRUD).

Swagger — это документация к API. Она показывает, какие команды (методы) можно отправить, какие параметры нужно в них передать, и что вы получите в ответе.

CRUD — это четыре основные операции, которые охватывают всё, что можно делать с данными:

• Create (Создать) — добавить новую задачу, проект или другую сущность. Используется метод POST;
• Read (Читать) — получить информацию о задаче, проекте или другой доступной сущности. Используется метод GET;
• Update (Обновить) — изменить название, описание или другие данные доступной сущности. Используется метод PATCH;
• Delete (Удалить) — удалить задачу, проект или другую сущность. Используется метод DELETE.

Наш API охватывает основные операции для работы с данными: создание, чтение, обновление и удаление (CRUD). API на текущий момент не поддерживает вебхуки, потоки событий, подписки на изменения.

Через API можно полностью управлять задачами: создавать новые, получать информацию о них, добавлять заметки, перемещать между колонками в канбан-режиме и создавать чек-листы. Методы, которые можно использовать:

Получение списка задач

Метод GET к endpoint `/v2/task` позволяет получить все задачи. Задачи можно отфильтровать по query полям.

• Фильтрация по статусу: используйте `includeRemoved` и `includeArchived` (true/false), чтобы выбрать, какие задачи показывать;
• Ограничение результатов: параметр `maxCount` (number) позволяет получить только нужное количество задач, а `includeAllRecurrenceInstances` (true/false) контролирует отображение повторяющихся задач;
• Фильтрация по проекту и подзадачам: укажите `projectId` (string) для задач конкретного проекта или `parent` (string) для подзадач определённой задачи;
• Фильтрация по датам: параметры `startDateFrom` и `startDateTo` (строка с датой в ISO формате: `2025-11-28`) помогут выбрать задачи в нужном диапазоне дат.

Создание задачи

Используйте метод POST к endpoint `/v2/task` для создания новой задачи. Передайте данные в body запроса в формате JSON с необходимыми полями.

Обязательные поля: "title" (string) — название задачи. Это поле, без которого задачу создать не получится (пример: "Купить продукты").

Основные параметры:

• "start" (string, ISO формат) — дата начала задачи (пример: "2025-11-28");
• "note" (string) — заметка или описание к задаче (пример: "Текст заметки");
• "priority" (number) — приоритет задачи (0 — высокий приоритет, 1 — обычный (средний) приоритет, 2 — низкий приоритет).

Дополнительные параметры:

• "isNote" (boolean) — установите true, чтобы создать заметку вместо обычной задачи;
• "journalDate" (string, ISO формат) — дата архивации. Если указать эту дату, задача сразу перейдёт в архив;
• "deleteDate" (string, ISO формат) — дата удаления. Если указать эту дату, задача перейдёт в корзину.

Важно! Повторяющиеся задачи пока создать не получится — API поддерживает только обычные задачи.

Получение задачи по ID

Получить задачу поможет метод GET к endpoint `/v2/task`. Необходимо указать ID задачи в качестве параметра path в URL. Где найти ID: из ответа при создании задачи или в интерфейсе приложения — правой кнопкой мыши по задаче → скопировать приватную ссылку → строка, которая начинается с «T» и есть ID задачи.

Изменение задачи

Используйте метод PATCH к endpoint `/v2/task` для изменения существующей задачи. Укажите ID задачи в пути запроса (path параметр). В body запроса передайте JSON с полями, которые хотите изменить.

Основные параметры для изменения:

• "title" (string) — новое название задачи (пример: "Купить продукты");
• "start" (string, ISO формат) — дата начала задачи (пример: "2025-11-28");
• "note" (string) — описание или заметка к задаче (пример: "Текст заметки");
• "priority" (number) — приоритет задачи (0 — высокий приоритет, 1 — обычный (средний) приоритет, 2 — низкий приоритет);
• "isNote" (boolean) — измените тип сущности: true преобразует задачу в заметку, false — заметку в задачу.

Важно! "title" не обязателен при изменении (в отличие от создания), так как ID задачи уже передан в пути. Вы можете изменять только те поля, которые нужно обновить.

Удаление задачи

Удалить задачу поможет метод DELETE к endpoint `/v2/task`. Необходимо указать ID задачи в качестве параметра path в URL. Удаление через метод DELETE происходит безвозвратно.

Если вы хотите отправить задачу в архив или в корзину (вместо полного удаления), используйте метод PATCH с соответствующими полями:

• "journalDate" (string, ISO формат) — архивируйте задачу, указав дату архивации;
• "deleteDate" (string, ISO формат) — отправьте задачу в корзину, указав дату удаления.

Перемещение задачи в канбане

Для перемещения задачи из одной колонки в другую используйте метод POST к endpoint `/v2/kanban-task-status`. Передайте ID задачи и ID колонки в body запроса в формате JSON. Оба должны существовать до этого запроса, иначе будет ошибка.

Чек-листы

Работать с чек-листами можно через методы GET, POST, PATCH, DELETE к endpoint `/v2/checklist-item`. Для создания чек-листа передайте его имя в поле "title" и укажите ID задачи в поле «parent» для body запроса в формате JSON.

Через API можно полностью управлять проектами: создавать новые, получать информацию о них, добавлять описание проекта, создавать секции и колонки для канбан-режима. Методы, которые можно использовать:

Поиск проекта

Метод GET к endpoint `/v2/project` позволяет получить все проекты. Проекты можно отфильтровать по query полям.

Фильтрация по статусу:

• "includeRemoved" (boolean) — показывать или скрывать удалённые проекты;
• "includeArchived" (boolean) — показывать или скрывать архивные проекты.

Ограничение результатов:

• "maxCount" (number) — ограничить количество проектов в ответе (например, 10, 50).

Важно! Совместные проекты не попадут в результаты выборки — API возвращает только ваши личные проекты.

Создание проекта

Используйте метод POST к endpoint `/v2/project` для создания нового проекта. Передайте данные в body запроса в формате JSON с необходимыми полями.

Обязательные поля:

• "title" (string) — название проекта (пример: "Мой проект").

Основные параметры:

• "note" (string) — описание или заметка проекта (пример: "Заметка проекта");
• "isNotebook" (boolean) — тип сущности:
  • true — создать блокнот вместо проекта;
  • false — создать обычный проект.

Оформление:

• "emoji" (string) — эмодзи проекта в виде шестнадцатеричного кода (пример: "1f49e");
• "color" (string) — цвет проекта в HEX формате (пример: "#ad1457").

Доступные цвета:

Изменение проекта

Для изменения полей задачи поможет метод PATCH к endpoint `/v2/project`. Обязательным является только поле "id" в качестве параметра path. Чтобы изменить поля у проекта, необходимо в body запроса добавить JSON аналогичный созданию проекта, за одним исключением — "title" не обязателен, так как вы уже передали ID в path.

Канбан колонки

Сущность `kanban-status` олицетворяет колонку в проекте. Работать с ними можно через методы GET, POST, PATCH, DELETE к endpoint `/v2/kanban-status`. Для создания колонки передайте название колонки в поле "title" и ID проекта в поле "parent" в body запроса в формате JSON. Для перемещения задачи из одной колонки в другую используйте метод POST.

В body запроса передайте:

• "taskId" (string) — ID задачи, которую нужно переместить;
• "statusId" (string) — ID колонки, в которую нужно переместить задачу.

Секции

Сущность "task-group" олицетворяет секции в проекте. Работать с ними можно через методы GET, POST, PATCH, DELETE к endpoint `/v2/task-group`. Для создания секции передайте её имя в поле "title" и ID проекта в поле "parent".

Через API можно работать с привычками: создавать новые, получать информацию о них, изменять и удалять, а также отмечать их выполнение. Методы, которые можно использовать:

Поиск привычек

Метод GET к endpoint `/v2/habit` позволяет получить привычки. Поиск происходит аналогично задачам и проектам. При поиске можно ограничить количество привычек через query параметр "maxCount".

Создание привычки

Используйте метод POST к endpoint `/v2/habit` для создания новой привычки. Передайте данные в body запроса в формате JSON с необходимыми полями.

Обязательные поля:

• "title" (string) — название привычки (пример: "Пить воду").

Основные параметры:

• "description" (string) — описание привычки (пример: "Я описание привычки");
• "color" (string) — цвет привычки. Доступные значения: "red", "pink", "purple", "deepPurple", "indigo", "lightBlue", "cyan", "teal", "green", "lightGreen", "lime", "yellow", "amber", "orange", "deepOrange", "brown", "grey", "blueGrey".

Изменение привычки

Используйте метод PATCH к endpoint `/v2/habit` для обновления существующей привычки. Укажите ID привычки в пути запроса (path параметр). В body запроса передайте JSON с полями, которые хотите изменить.

Удаление привычки

Удалить привычку поможет метод DELETE к endpoint `/v2/habit`. Передайте ID привычки для удаление.

Отметить привычку

Для отметки привычки используйте метод POST к endpoint `/v2/habit-progress`. Передайте данные в body запроса в формате JSON с необходимыми полями.

Обязательные поля:

• "habit" (string) — ID привычки, которую нужно отметить (пример: "HB-123");
• "date" (string) — дата отметки в формате YYYY-MM-DD (пример: "2025-11-28");
• "progress" (number) — статус отметки (0 — стандартное значение, не изменяет прогресс; 1 — отметить привычку как НЕ выполненную (сохраняет серию привычки); 2 — полностью отметить привычку как выполненную).

Через API можно работать с тегами: создавать новые, получать информацию о них, обновлять и удалять. Методы, которые можно использовать:

Поиск тегов

Метод GET к endpoint `/v2/tag` позволяет получить теги. Результаты можно фильтровать с помощью query параметров.

• Фильтрация по статусу: "includeRemoved" (boolean) — показывать или скрывать удалённые теги;
• Фильтрация по иерархии: "parent" (string) — отфильтровать теги по родительскому тегу, если они вложены в него (пример: "A-123");
• Ограничение результатов: "maxCount" (number) — ограничить максимальное количество тегов в одном запросе (пример: "100").

Создание тега

Используйте метод POST к endpoint `/v2/tag` для создания нового тега. Передайте данные в body запроса в формате JSON с необходимыми полями.

Обязательные поля: "title" (string) — название тега (пример: "Работа").

Основные параметры:

• "parent" (string) — ID родительского тега, если нужно вложить новый тег в существующий (пример: "A-123");
• "hotkey" (number) — горячая клавиша для быстрого доступа к тегу. Укажите Unicode код символа, который нажимаете после Alt (например, если тег на Alt+9, то "hotkey: 57", так как 57 — это Unicode код символа "9").

Изменение тега

Чтобы обновить тег, используйте метод PATCH к endpoint `/v2/tag` и передайте его ID в пути запроса. Далее передайте в body запроса JSON с полями аналогичными созданию тега, где "title" будет опциональным, так как вы обращаетесь к тегу по ID, который уже передали в path. Вы можете изменять только те поля, которые нужно обновить.

Удаление тега

Удалить тег поможет метод DELETE к endpoint `/v2/tag`. Передайте ID тега для удаления.