Kooly API documentation
REST API · v1

Встраивайте работу в Kooly

Создавайте задачи, синхронизируйте контакты и подключайте свои сервисы. Один предсказуемый JSON API работает с теми же правами, что и ваш аккаунт.

Первый запрос Все методы
Ваш первый запрос 
curl https://api.kooly.ru/api/v1/private/me \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $KOOLY_TOKEN"
JSON запросы и ответы
Bearer персональный токен
v1 стабильный контракт

Быстрый старт

От токена до первого ответа — три шага. Отдельный токен для каждой интеграции упрощает отзыв доступа.

01

Создайте токен

Откройте Профиль, найдите «API-токены» и сохраните значение: повторно оно не показывается.

02

Добавьте заголовки

Передавайте токен как Bearer и явно запрашивайте application/json.

03

Проверьте доступ

Вызовите GET /me. Ответ покажет пользователя и рабочее пространство, в котором выполняются запросы.

Авторизация

Токен действует от имени пользователя. Все ограничения ролей, членства в проектах и доступа к доскам продолжают работать.

# Храните токен в секретах окружения
export KOOLY_TOKEN="1|..."

curl https://api.kooly.ru/api/v1/private/projects \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $KOOLY_TOKEN"

Формат данных

API использует JSON, ISO 8601 и обычные HTTP-коды. Эти соглашения одинаковы для всех ресурсов.

{ }

Обёртка ответа

Большинство ресурсов возвращается в поле data. У некоторых операций рядом находятся permissions, links или другая метаинформация.

#

Идентификаторы

Контакты, проекты и доски используют числовой ID. В URL задач поле {deal} — это UUID, а не числовой id.

↕

Пагинация

Коллекции с пагинацией принимают page и per_page, а в ответе содержат links и meta.

T

Дата и время

Даты имеют вид YYYY-MM-DD, время — HH:MM, отметки времени передаются в ISO 8601 с часовым поясом.

Ошибки

При ошибке API возвращает JSON с полем message. Ошибки валидации дополнительно содержат объект errors.

Код Что означает Что проверить
401 Токен не принят Заголовок Authorization, срок действия и отзыв токена
403 Недостаточно прав Текущее рабочее пространство, роль и членство в ресурсе
404 Ресурс не найден или недоступен ID, UUID и принадлежность ресурса рабочему пространству
422 Данные не прошли проверку Поля из объекта errors в ответе
429 Слишком много запросов Уменьшите частоту и повторите запрос с задержкой

Справочник методов

Ниже перечислен поддерживаемый публичный контракт v1. Полные схемы полей доступны в OpenAPI-файле.

OpenAPI 3.1

Пользователь

Проверка токена и справочник участников.

GET /me Текущий пользователь и рабочее пространство

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

GET /members Участники рабочего пространства

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

Контакты

Люди, связанные с клиентами и задачами.

GET /contacts Список и поиск контактов

Параметры: search, client, sort, dir, page, per_page

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /contacts Создать контакт 
{
  "first_name": "Анна",
  "last_name": "Петрова",
  "email": "anna@example.com",
  "phone": "+79990000000"
}
GET /contacts/{contact} Получить контакт

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

PATCH /contacts/{contact} Изменить контакт

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

DELETE /contacts/{contact} Удалить контакт

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

Проекты

Проекты, их участники и дерево задач.

GET /projects Список проектов

Параметры: archived, status, overdue

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /projects Создать проект 
{
  "name": "Запуск нового сайта",
  "status": "active",
  "start_date": "2026-08-01",
  "due_date": "2026-09-15"
}
GET /projects/{project} Получить проект

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

PATCH /projects/{project} Изменить проект

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

DELETE /projects/{project} Удалить проект

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

GET /projects/{project}/tasks Задачи проекта

Список плоский; иерархия задаётся полем parent_id

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /projects/{project}/tasks Создать задачу проекта 
{
  "name": "Подготовить структуру лендинга",
  "priority": "high",
  "expected_close_date": "2026-08-07",
  "participant_ids": [12, 18]
}

Доски

Доски, стадии и текущее состояние канбана.

GET /boards Доступные доски

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /boards Создать доску

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

PATCH /boards/{board} Изменить доску

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

DELETE /boards/{board} Удалить доску

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

GET /boards/{board}/stages Стадии доски

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /boards/{board}/stages Создать стадию 
{
  "name": "На проверке",
  "color": "#4ECBA0"
}
GET /boards/{board}/kanban Стадии вместе с активными задачами

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

Задачи

Личные задачи, карточки досок и операции над ними.

GET /my-tasks Личные или назначенные задачи

Параметры: tab=my|assigned, completed_page, per_page

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /my-tasks Создать личную задачу 
{
  "name": "Позвонить поставщику",
  "priority": "medium",
  "expected_close_date": "2026-08-03",
  "expected_end_time": "14:30"
}
GET /my-tasks/search Найти доступные задачи

Обязательный параметр q; scope=accessible расширяет область поиска

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /deals Создать автономную задачу

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

GET /deals/{deal} Получить задачу по UUID

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

PUT /deals/{deal} Изменить задачу

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

DELETE /deals/{deal} Удалить задачу

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /deals/{deal}/toggle Переключить выполнение

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

PUT /deals/{deal}/participants Заменить участников

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

PATCH /boards/{board}/deals/{deal}/move Переместить задачу на стадию 
{
  "stage_id": 42,
  "position": 65536
}

Комментарии

Обсуждение задач и ответы на комментарии.

GET /deals/{deal}/comments Комментарии задачи

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

POST /deals/{deal}/comments Добавить комментарий 
{
  "body": "Макет готов к проверке"
}
PUT /deals/{deal}/comments/{comment} Изменить свой комментарий

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.

DELETE /deals/{deal}/comments/{comment} Удалить свой комментарий

Параметры, схемы ответа и коды ошибок описаны в OpenAPI-контракте.