API Klepps

REST API и MCP-сервер для интеграций и ИИ-агентов: выгружайте задачи и учёт времени в 1С и BI, создавайте задачи из CRM и с сайта, подключайте Klepps к Cursor и Claude, читайте документацию и транскрипты встреч из своих систем.

  • Адрес: https://klepps.ru/api/v1, MCP — https://klepps.ru/api/mcp
  • Запросы и ответы — JSON в UTF-8, даты — миллисекунды Unix, дни — ГГГГ-ММ-ДД, время — в секундах
  • Ключ передаётся в заголовке Authorization: Bearer klp_…
  • Изменения через API сразу видны коллегам в Klepps, как будто их сделал пользователь ключа
  • REST API доступен на тарифах «Команда» и «Бизнес», MCP-сервер для ИИ-агентов — на «Бизнесе».
  • Для ИИ и генераторов клиентов: эта документация в Markdown, llms.txt, OpenAPI

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

  1. В Klepps откройте «API» в меню слева и нажмите «Новый ключ».
  2. Выберите права и скопируйте ключ — он показывается один раз.
  3. Проверьте подключение:
export KLEPPS_KEY=klp_…
curl https://klepps.ru/api/v1/me -H "Authorization: Bearer $KLEPPS_KEY"

ИИ-агенты (MCP)

Klepps подключается к ИИ-агентам (Cursor, Claude, VS Code и другие) как MCP-сервер: https://klepps.ru/api/mcp, транспорт Streamable HTTP, вход — тем же ключом API в заголовке Authorization. Агент видит только инструменты, на которые у ключа есть права, и действует от имени пользователя ключа — как через REST API. MCP доступен на тарифе «Бизнес».

Любая нейросеть — ваш агентKlepps не привязан к одной модели: Claude, GPT, Gemini, DeepSeek, Qwen, Kimi и другие работают с ним одинаково. Подойдёт любой клиент, который подключает MCP-сервер по адресу (Streamable HTTP) с заголовком: Cursor, Claude Code, VS Code, Cline и другие. Если клиент умеет запускать MCP только командой — через мост: npx mcp-remote https://klepps.ru/api/mcp --header "Authorization: Bearer klp_…".

Например, в Cursor: «возьми WEB-42 и сделай» — агент прочитает задачу вместе с ТЗ из документации и договорённостями со встреч, перенесёт её «В работу», напишет код, спишет время, опишет в комментарии, что сделал, и переведёт задачу в «Готово». Коллеги видят это сразу, как будто работал человек.

Подключение

  1. В Klepps откройте «API» и нажмите «Ключ для агента» — права подобраны для работы с задачами, временем и документами.
  2. В окне с ключом выберите вкладку «ИИ-агент (MCP)»: для Cursor есть кнопка «Добавить в Cursor», для остальных — готовая настройка.

Файл .cursor/mcp.json в проекте или ~/.cursor/mcp.json — для всех проектов. Проще всего — кнопка «Добавить в Cursor» после создания ключа в Klepps.

{
  "mcpServers": {
    "klepps": {
      "url": "https://klepps.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer klp_ВАШ_КЛЮЧ"
      }
    }
  }
}

Инструменты

ИнструментЧто делаетПраво
whoamiПользователь ключа, компания и права ключа. Вызовите первым, чтобы понять, от чьего имени вы работаете.любой ключ
list_projectsПроекты с досками и колонками (id и тип колонки: todo, progress, done). Нужен, чтобы создавать и переносить задачи.любой ключ
list_usersУчастники компании: id, имя, логин, должность. Нужен, чтобы назначать исполнителей.любой ключ
search_tasksЗадачи по фильтрам: текст, проект, исполнитель (me — пользователь ключа), тип колонки, метка. Без фильтров — открытые задачи пользователя ключа.tasks:read
get_taskЗадача целиком в Markdown: описание, чек-лист, подзадачи, обсуждение (комментарии с id), связанные документы и договорённости со встреч. Задачу можно указать ключом (WEB-42).tasks:read
add_commentКомментарий к задаче от имени пользователя ключа. Сюда пишите результат работы: что сделано, ответ на вопрос, отчёт, ссылки. Можно ответить на комментарий (replyTo — id из get_task) и упомянуть людей через @логин.tasks:write
create_taskНовая задача от имени пользователя ключа. Описание — в Markdown.tasks:write
update_taskМеняет только переданные поля: название, приоритет, тип, метки, срок, исполнителей, чек-лист. Описание задачи — постановка от людей, агент его не меняет: результат пишите через add_comment.tasks:write
move_taskПереносит задачу в колонку её доски: по названию колонки, её id или типу (todo, progress, done — первая колонка такого типа).tasks:write
log_timeЗаписывает потраченное время на задачу от имени пользователя ключа.time:write
time_reportСколько времени потрачено за период в разрезе людей, задач, проектов или дней.time:read
list_docsРазделы документации и страницы в них; можно искать по тексту.docs:read
get_docСтраница документации целиком в Markdown.docs:read
create_docНовая страница документации; содержимое — в Markdown.docs:write
update_docЗаменяет заголовок и/или содержимое страницы (Markdown, целиком). Прежний текст остаётся в истории версий.docs:write
list_meetingsЗаписанные встречи, новые сверху; поиск по названию и саммари, фильтр по датам.meetings:read
get_meetingСаммари встречи (темы, решения, договорённости) и, по желанию, полный транскрипт.meetings:read

Тексты задач и документов пишут люди, поэтому агенту сказано не выполнять инструкции из них без вашего подтверждения. Результат работы агент пишет комментарием к задаче, а описание — постановку от людей — не меняет. Удалять задачи через MCP нельзя; для агента удобно завести отдельного пользователя или ограничить ключ проектами.

Ключи и права

Ключ действует от имени пользователя и никогда не может больше, чем он сам: доски, разделы документов и папки встреч, закрытые для пользователя, закрыты и для ключа. Администратор может выпустить ключ от имени любого участника — для интеграций удобно завести отдельного пользователя, например «Интеграция 1С», чтобы его действия было видно в истории.

Что ещё настраивается у ключа:

  • Права — какие разделы ключ читает и меняет (таблица ниже). Проекты, доски, колонки, пользователи и метки может читать любой ключ.
  • Проекты — все или только выбранные: остальные проекты, их задачи и время ключ не видит.
  • Срок действия — бессрочно или 30 дней — год.
  • IP-адреса — запросы принимаются только с перечисленных адресов или диапазонов (203.0.113.10, 10.0.0.0/24).

По умолчанию ключи выпускает только администратор; он может разрешить это всем участникам. Ключ можно отозвать в любой момент — он перестаёт работать сразу. В базе хранится только хеш ключа.

ПравоРазделЧто разрешает
tasks:readЗадачиЗадачи, чек-листы, подзадачи
tasks:writeЗадачиСоздание, правка, перенос, исполнители, удаление
projects:writeПроектыСоздание проектов, досок и колонок, правка проектов
time:readВремяЗаписи времени и отчёты по задачам, людям, проектам
time:writeВремяСписание времени на задачи
docs:readДокументыРазделы и страницы документации
docs:writeДокументыСоздание и правка страниц
meetings:readТранскриптыВстречи, саммари и транскрипты

Формат и ошибки

Успешный ответ — 200 (или 201 при создании, 204 без тела при удалении); объект — в поле data. Ошибка — код HTTP и объект с машинным кодом и понятным описанием на русском:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Ключу не выдано право tasks:write"
  }
}
HTTPcodeКогда
400invalid_requestНеверные параметры или тело запроса; в message — какое поле и что не так
401unauthorizedКлюч не передан
401invalid_keyКлюч неверный, отозван или его пользователь удалён
401key_expiredСрок действия ключа истёк
403insufficient_scopeКлючу не выдано нужное право
403forbiddenУ пользователя ключа нет прав на это действие
403ip_not_allowedЗапрос пришёл не с разрешённого IP-адреса
403api_disabledАдминистратор отключил ключи участников
403plan_requiredAPI не входит в тариф компании: он доступен на «Команде» и «Бизнесе»
404not_foundОбъекта нет или он не виден ключу
409archivedЗадача в архиве — менять её можно после возврата из архива в Klepps
422rejectedДействие не выполнено по правилам Klepps (лимит тарифа, цикл подзадач и т. п.); причина — в message
429rate_limitedПревышен лимит запросов в минуту

Лимит запросов

До 120 запросов в минуту на ключ. Остаток видно в заголовках x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset; при превышении — 429 и заголовок retry-after (секунды).

Списки и синхронизация

Списки отдаются страницами: limit — сколько (до 500, по умолчанию 100), cursor — с какого места. В ответе nextCursor (null — это последняя страница) и total — сколько всего подходит под фильтры.

{
  "data": [
    "…"
  ],
  "nextCursor": "100",
  "total": 342
}

Чтобы держать копию данных у себя, запрашивайте задачи и документы с updatedSince — придут только изменённые после указанного момента (ISO 8601 или миллисекунды). Задачу можно найти по ключу: GET /tasks/WEB-42.

Ключ и компания

Проверить ключ

GET/me

Доступно любому ключу

От чьего имени работает ключ, в какой компании и с какими правами. Удобно для проверки подключения.

curl "https://klepps.ru/api/v1/me" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "user": {
      "id": "u-k3f9a2m1",
      "name": "Анна Смирнова",
      "login": "anna@romashka.ru",
      "role": "Руководитель проекта",
      "isAdmin": true,
      "teamIds": [
        "tm-frontend"
      ]
    },
    "workspace": {
      "id": "ws-5f2c…",
      "name": "Ромашка"
    },
    "key": {
      "id": "key-a1b2c3",
      "scopes": [
        "tasks:read",
        "tasks:write",
        "time:read"
      ],
      "projectIds": null
    },
    "rateLimitPerMinute": 120
  }
}

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

GET/users

Доступно любому ключу

Параметры запроса

qstringПоиск по имени, логину, должности
limit, cursorПостраничная выдача
curl "https://klepps.ru/api/v1/users" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "u-k3f9a2m1",
      "name": "Анна Смирнова",
      "login": "anna@romashka.ru",
      "role": "Руководитель проекта",
      "isAdmin": true,
      "teamIds": [
        "tm-frontend"
      ]
    },
    {
      "id": "u-p7d2x8q4",
      "name": "Иван Петров",
      "login": "ivan",
      "role": "Разработчик",
      "isAdmin": false,
      "teamIds": [
        "tm-frontend"
      ]
    }
  ],
  "nextCursor": null,
  "total": 2
}

Команды

GET/teams

Доступно любому ключу

curl "https://klepps.ru/api/v1/teams" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "tm-frontend",
      "name": "Фронтенд",
      "description": "",
      "memberIds": [
        "u-k3f9a2m1",
        "u-p7d2x8q4"
      ],
      "leadId": "u-k3f9a2m1"
    }
  ],
  "nextCursor": null,
  "total": 1
}

Метки

GET/labels

Доступно любому ключу

curl "https://klepps.ru/api/v1/labels" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    "frontend",
    "срочно"
  ]
}

Проекты и доски

Читать структуру может любой ключ. Ключ, ограниченный проектами, видит только их.

Список проектов

GET/projects

Доступно любому ключу

curl "https://klepps.ru/api/v1/projects" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "p-w1e8r5t2",
      "key": "WEB",
      "name": "Сайт",
      "description": "Новый сайт компании",
      "createdAt": 1759300000000
    }
  ],
  "nextCursor": null,
  "total": 1
}

Проект с досками и колонками

GET/projects/{id}

Доступно любому ключу

Параметры пути

idобязательноstringid проекта
curl "https://klepps.ru/api/v1/projects/p-w1e8r5t2" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "id": "p-w1e8r5t2",
    "key": "WEB",
    "name": "Сайт",
    "description": "Новый сайт компании",
    "createdAt": 1759300000000,
    "boards": [
      {
        "id": "b-9h4j2k7l",
        "projectId": "p-w1e8r5t2",
        "name": "Разработка",
        "description": "",
        "statuses": [
          {
            "id": "s-todo1",
            "name": "К выполнению",
            "category": "todo"
          },
          {
            "id": "s-prog1",
            "name": "В работе",
            "category": "progress"
          },
          {
            "id": "s-done1",
            "name": "Готово",
            "category": "done"
          }
        ]
      }
    ]
  }
}

Создать проект

POST/projects

Право ключа: projects:write

Создаёт проект с первой доской по шаблону. Лимиты тарифа действуют как в интерфейсе. Ключу, ограниченному проектами, недоступно.

Тело запроса (JSON)

nameобязательноstringНазвание
keyобязательноstringКлюч задач, до 10 символов: WEB → WEB-1, WEB-2…
descriptionstringОписание
templatescrum | simple | bugs | nullШаблон первой доски, по умолчанию simple; null — без доски
curl -X POST "https://klepps.ru/api/v1/projects" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Мобильное приложение",
  "key": "APP",
  "template": "scrum"
}'
Ответ
{
  "data": {
    "id": "p-n3m4b5v6",
    "key": "APP",
    "name": "Мобильное приложение",
    "description": "",
    "createdAt": 1759300000000,
    "boards": [
      {
        "id": "b-c4v5b6n7",
        "projectId": "p-n3m4b5v6",
        "name": "Скрам",
        "description": "",
        "statuses": [
          {
            "id": "s-todo1",
            "name": "К выполнению",
            "category": "todo"
          },
          {
            "id": "s-prog1",
            "name": "В работе",
            "category": "progress"
          },
          {
            "id": "s-done1",
            "name": "Готово",
            "category": "done"
          }
        ]
      }
    ]
  }
}

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

PATCH/projects/{id}

Право ключа: projects:write

Тело запроса (JSON)

name, descriptionstringЛюбые из полей
curl -X PATCH "https://klepps.ru/api/v1/projects/p-w1e8r5t2" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Сайт и лендинги"
}'
Ответ
{
  "data": {
    "id": "p-w1e8r5t2",
    "key": "WEB",
    "name": "Сайт",
    "description": "Сайт и лендинги",
    "createdAt": 1759300000000
  }
}

Доски

GET/boards

Доступно любому ключу

Параметры запроса

projectIdstringТолько доски проекта
curl "https://klepps.ru/api/v1/boards?projectId=p-w1e8r5t2" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "b-9h4j2k7l",
      "projectId": "p-w1e8r5t2",
      "name": "Разработка",
      "description": "",
      "statuses": [
        {
          "id": "s-todo1",
          "name": "К выполнению",
          "category": "todo"
        },
        {
          "id": "s-prog1",
          "name": "В работе",
          "category": "progress"
        },
        {
          "id": "s-done1",
          "name": "Готово",
          "category": "done"
        }
      ]
    }
  ],
  "nextCursor": null,
  "total": 1
}

Доска

GET/boards/{id}

Доступно любому ключу

curl "https://klepps.ru/api/v1/boards/b-9h4j2k7l" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "id": "b-9h4j2k7l",
    "projectId": "p-w1e8r5t2",
    "name": "Разработка",
    "description": "",
    "statuses": [
      {
        "id": "s-todo1",
        "name": "К выполнению",
        "category": "todo"
      },
      {
        "id": "s-prog1",
        "name": "В работе",
        "category": "progress"
      },
      {
        "id": "s-done1",
        "name": "Готово",
        "category": "done"
      }
    ]
  }
}

Создать доску

POST/boards

Право ключа: projects:write

Тело запроса (JSON)

projectIdобязательноstringПроект
nameобязательноstringНазвание
descriptionstringОписание
templatescrum | simple | bugsНабор колонок, по умолчанию simple
curl -X POST "https://klepps.ru/api/v1/boards" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "p-w1e8r5t2",
  "name": "Баги",
  "template": "bugs"
}'
Ответ
{
  "data": {
    "id": "b-x1c2v3b4",
    "projectId": "p-w1e8r5t2",
    "name": "Баги",
    "description": "",
    "statuses": [
      {
        "id": "s-todo1",
        "name": "К выполнению",
        "category": "todo"
      },
      {
        "id": "s-prog1",
        "name": "В работе",
        "category": "progress"
      },
      {
        "id": "s-done1",
        "name": "Готово",
        "category": "done"
      }
    ]
  }
}

Добавить колонку

POST/boards/{id}/statuses

Право ключа: projects:write

Тело запроса (JSON)

nameобязательноstringНазвание колонки
curl -X POST "https://klepps.ru/api/v1/boards/b-9h4j2k7l/statuses" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "На проверке"
}'
Ответ
{
  "data": {
    "id": "b-9h4j2k7l",
    "projectId": "p-w1e8r5t2",
    "name": "Разработка",
    "description": "",
    "statuses": [
      {
        "id": "s-todo1",
        "name": "К выполнению",
        "category": "todo"
      },
      {
        "id": "s-prog1",
        "name": "В работе",
        "category": "progress"
      },
      {
        "id": "s-done1",
        "name": "Готово",
        "category": "done"
      },
      {
        "id": "s-k8l9z0",
        "name": "На проверке",
        "category": "progress"
      }
    ]
  }
}

Задачи

Задачу можно указывать по id или по ключу (WEB-42). Описание приходит в HTML (description) и простым текстом (descriptionText); при записи можно передать любое из двух. Время — в секундах.

Список задач

GET/tasks

Право ключа: tasks:read

Краткие карточки без описания, по дате создания. Для синхронизации используйте updatedSince.

Параметры запроса

projectId, boardId, statusIdstringГде лежит задача
categorytodo | progress | doneТип колонки
assigneeIdstringИсполнитель (любой из assigneeIds); none — без исполнителя
reporterIdstringАвтор
typetask,bug,story,epicТип, можно несколько через запятую
priorityhighest,high,medium,low,lowestПриоритет, можно несколько
labelstringМетки через запятую — задача должна иметь все
parentIdstringПодзадачи задачи; none — только верхнего уровня
dueBeforeГГГГ-ММ-ДДСрок не позже даты
updatedSinceISO 8601 | мсИзменённые после момента
qstringПоиск по названию, ключу, описанию
archivedfalse | true | allАрхив: по умолчанию только активные
limit, cursorПостраничная выдача
curl "https://klepps.ru/api/v1/tasks?projectId=p-w1e8r5t2&category=progress&assigneeId=u-p7d2x8q4" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "t-m4n8b2v6",
      "key": "WEB-42",
      "projectId": "p-w1e8r5t2",
      "boardId": "b-9h4j2k7l",
      "statusId": "s-prog1",
      "status": {
        "name": "В работе",
        "category": "progress"
      },
      "title": "Форма обратной связи",
      "type": "task",
      "priority": "high",
      "assigneeId": "u-p7d2x8q4",
      "assigneeIds": [
        "u-p7d2x8q4"
      ],
      "reporterId": "u-k3f9a2m1",
      "labels": [
        "frontend"
      ],
      "dueDate": "2026-10-20",
      "parentId": null,
      "timeEstimateSeconds": 28800,
      "timeSpentSeconds": 5400,
      "archived": false,
      "doneAt": null,
      "archivedAt": null,
      "createdAt": 1760000000000,
      "updatedAt": 1760090000000
    }
  ],
  "nextCursor": null,
  "total": 1
}

Задача целиком

GET/tasks/{ref}

Право ключа: tasks:read

С описанием, чек-листом, подзадачами, записями времени, вложениями и связанными документами.

Параметры пути

refобязательноstringid или ключ задачи
curl "https://klepps.ru/api/v1/tasks/WEB-42" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "id": "t-m4n8b2v6",
    "key": "WEB-42",
    "projectId": "p-w1e8r5t2",
    "boardId": "b-9h4j2k7l",
    "statusId": "s-prog1",
    "status": {
      "name": "В работе",
      "category": "progress"
    },
    "title": "Форма обратной связи",
    "type": "task",
    "priority": "high",
    "assigneeId": "u-p7d2x8q4",
    "assigneeIds": [
      "u-p7d2x8q4"
    ],
    "reporterId": "u-k3f9a2m1",
    "labels": [
      "frontend"
    ],
    "dueDate": "2026-10-20",
    "parentId": null,
    "timeEstimateSeconds": 28800,
    "timeSpentSeconds": 5400,
    "archived": false,
    "doneAt": null,
    "archivedAt": null,
    "createdAt": 1760000000000,
    "updatedAt": 1760090000000,
    "description": "<p>Поля: имя, контакт, сообщение. Отправка — на <b>/api/feedback</b>.</p>",
    "descriptionText": "Поля: имя, контакт, сообщение. Отправка — на /api/feedback.",
    "checklist": [
      {
        "id": "c-1",
        "text": "Вёрстка",
        "done": true
      },
      {
        "id": "c-2",
        "text": "Валидация",
        "done": false
      }
    ],
    "subtaskIds": [],
    "timeLogs": [
      {
        "id": "tl-a8s7d6f5",
        "taskId": "t-m4n8b2v6",
        "taskKey": "WEB-42",
        "projectId": "p-w1e8r5t2",
        "userId": "u-p7d2x8q4",
        "seconds": 5400,
        "date": "2026-10-09",
        "note": "Вёрстка и валидация"
      }
    ],
    "attachments": [
      {
        "id": "f-u8i9o0",
        "name": "макет.png",
        "size": 182340,
        "type": "image/png"
      }
    ],
    "docIds": [
      "d-feedback"
    ]
  }
}

Контекст для ИИ

GET/tasks/{ref}/context

Право ключа: tasks:read

Задача одним Markdown-текстом: свойства, описание, чек-лист, подзадачи, обсуждение (последние 50 комментариев с id), связанные документы (с правом docs:read) и договорённости со встреч (с правом meetings:read). Готовый контекст для ИИ-агента; то же копирует кнопка «Скопировать для ИИ» в карточке задачи.

Параметры пути

refобязательноstringid или ключ задачи

Параметры запроса

formatmarkdown | jsonПо умолчанию text/markdown; json — {data: {taskId, key, markdown}}
curl "https://klepps.ru/api/v1/tasks/WEB-42/context" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
# WEB-42: Форма обратной связи

- Проект: Сайт (WEB); доска: Разработка; колонка: В работе (в работе)
- Тип: задача; приоритет: высокий
- Исполнители: Иван Петров; автор: Анна Смирнова
- Срок: 2026-10-20; оценка: 1д; потрачено: 1ч 30м

## Описание

Поля: имя, контакт, сообщение. Отправка — на **/api/feedback**.

## Чек-лист

- [x] Вёрстка
- [ ] Валидация

## Связанные документы

### Форма обратной связи (раздел «Техническая документация», id d-feedback)

…

Создать задачу

POST/tasks

Право ключа: tasks:write

Автором становится пользователь ключа. Исполнители получают уведомление, автоматизации доски срабатывают как обычно.

Тело запроса (JSON)

titleобязательноstringНазвание
boardIdstringДоска; или projectId — тогда первая доска проекта
statusIdstringКолонка, по умолчанию первая
description / descriptionTextstringОписание в HTML или простым текстом
typetask | bug | story | epicПо умолчанию task
priorityhighest | high | medium | low | lowestПо умолчанию medium
assigneeIdsstring[]Исполнители
assigneeIdstringУ кого задача сейчас (по умолчанию первый из assigneeIds)
labelsstring[]Метки (новые создаются)
dueDateГГГГ-ММ-ДД | nullСрок
timeEstimateSecondsnumberОценка времени
checklist{text, done}[]Чек-лист
parentIdstringРодительская задача (тот же проект)
curl -X POST "https://klepps.ru/api/v1/tasks" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "p-w1e8r5t2",
  "title": "Форма обратной связи",
  "descriptionText": "Поля: имя, контакт, сообщение.",
  "priority": "high",
  "assigneeIds": [
    "u-p7d2x8q4"
  ],
  "labels": [
    "frontend"
  ],
  "dueDate": "2026-10-20"
}'
Ответ
{
  "data": {
    "id": "t-m4n8b2v6",
    "key": "WEB-42",
    "projectId": "p-w1e8r5t2",
    "boardId": "b-9h4j2k7l",
    "statusId": "s-todo1",
    "status": {
      "name": "К выполнению",
      "category": "todo"
    },
    "title": "Форма обратной связи",
    "type": "task",
    "priority": "high",
    "assigneeId": "u-p7d2x8q4",
    "assigneeIds": [
      "u-p7d2x8q4"
    ],
    "reporterId": "u-k3f9a2m1",
    "labels": [
      "frontend"
    ],
    "dueDate": "2026-10-20",
    "parentId": null,
    "timeEstimateSeconds": 28800,
    "timeSpentSeconds": 0,
    "archived": false,
    "doneAt": null,
    "archivedAt": null,
    "createdAt": 1760000000000,
    "updatedAt": 1760090000000,
    "description": "<p>Поля: имя, контакт, сообщение. Отправка — на <b>/api/feedback</b>.</p>",
    "descriptionText": "Поля: имя, контакт, сообщение. Отправка — на /api/feedback.",
    "checklist": [
      {
        "id": "c-1",
        "text": "Вёрстка",
        "done": true
      },
      {
        "id": "c-2",
        "text": "Валидация",
        "done": false
      }
    ],
    "subtaskIds": [],
    "timeLogs": [],
    "attachments": [
      {
        "id": "f-u8i9o0",
        "name": "макет.png",
        "size": 182340,
        "type": "image/png"
      }
    ],
    "docIds": [
      "d-feedback"
    ]
  }
}

Изменить задачу

PATCH/tasks/{ref}

Право ключа: tasks:write

Передавайте только меняющиеся поля. statusId переносит задачу в колонку (наверх), boardId — на другую доску проекта, assigneeIds заменяет список исполнителей, assigneeId передаёт задачу.

Тело запроса (JSON)

title, description, descriptionText, type, priority, labels, dueDate, timeEstimateSeconds, checklistКак при создании
statusIdstringНовая колонка
boardIdstringДругая доска того же проекта
assigneeIdsstring[]Исполнители
assigneeIdstringПередать задачу
parentIdstring | nullСделать подзадачей / отвязать
curl -X PATCH "https://klepps.ru/api/v1/tasks/WEB-42" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "statusId": "s-done1",
  "priority": "medium"
}'
Ответ
{
  "data": {
    "id": "t-m4n8b2v6",
    "key": "WEB-42",
    "projectId": "p-w1e8r5t2",
    "boardId": "b-9h4j2k7l",
    "statusId": "s-done1",
    "status": {
      "name": "Готово",
      "category": "done"
    },
    "title": "Форма обратной связи",
    "type": "task",
    "priority": "medium",
    "assigneeId": "u-p7d2x8q4",
    "assigneeIds": [
      "u-p7d2x8q4"
    ],
    "reporterId": "u-k3f9a2m1",
    "labels": [
      "frontend"
    ],
    "dueDate": "2026-10-20",
    "parentId": null,
    "timeEstimateSeconds": 28800,
    "timeSpentSeconds": 5400,
    "archived": false,
    "doneAt": null,
    "archivedAt": null,
    "createdAt": 1760000000000,
    "updatedAt": 1760090000000,
    "description": "<p>Поля: имя, контакт, сообщение. Отправка — на <b>/api/feedback</b>.</p>",
    "descriptionText": "Поля: имя, контакт, сообщение. Отправка — на /api/feedback.",
    "checklist": [
      {
        "id": "c-1",
        "text": "Вёрстка",
        "done": true
      },
      {
        "id": "c-2",
        "text": "Валидация",
        "done": false
      }
    ],
    "subtaskIds": [],
    "timeLogs": [
      {
        "id": "tl-a8s7d6f5",
        "taskId": "t-m4n8b2v6",
        "taskKey": "WEB-42",
        "projectId": "p-w1e8r5t2",
        "userId": "u-p7d2x8q4",
        "seconds": 5400,
        "date": "2026-10-09",
        "note": "Вёрстка и валидация"
      }
    ],
    "attachments": [
      {
        "id": "f-u8i9o0",
        "name": "макет.png",
        "size": 182340,
        "type": "image/png"
      }
    ],
    "docIds": [
      "d-feedback"
    ]
  }
}

Перенести в колонку

POST/tasks/{ref}/move

Право ключа: tasks:write

Тело запроса (JSON)

statusIdобязательноstringКолонка
positionnumberМесто в колонке, 0 — сверху (по умолчанию)
boardIdstringДругая доска того же проекта
curl -X POST "https://klepps.ru/api/v1/tasks/WEB-42/move" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "statusId": "s-prog1",
  "position": 2
}'
Ответ
{
  "data": {
    "id": "t-m4n8b2v6",
    "key": "WEB-42",
    "projectId": "p-w1e8r5t2",
    "boardId": "b-9h4j2k7l",
    "statusId": "s-prog1",
    "status": {
      "name": "В работе",
      "category": "progress"
    },
    "title": "Форма обратной связи",
    "type": "task",
    "priority": "high",
    "assigneeId": "u-p7d2x8q4",
    "assigneeIds": [
      "u-p7d2x8q4"
    ],
    "reporterId": "u-k3f9a2m1",
    "labels": [
      "frontend"
    ],
    "dueDate": "2026-10-20",
    "parentId": null,
    "timeEstimateSeconds": 28800,
    "timeSpentSeconds": 5400,
    "archived": false,
    "doneAt": null,
    "archivedAt": null,
    "createdAt": 1760000000000,
    "updatedAt": 1760090000000,
    "description": "<p>Поля: имя, контакт, сообщение. Отправка — на <b>/api/feedback</b>.</p>",
    "descriptionText": "Поля: имя, контакт, сообщение. Отправка — на /api/feedback.",
    "checklist": [
      {
        "id": "c-1",
        "text": "Вёрстка",
        "done": true
      },
      {
        "id": "c-2",
        "text": "Валидация",
        "done": false
      }
    ],
    "subtaskIds": [],
    "timeLogs": [
      {
        "id": "tl-a8s7d6f5",
        "taskId": "t-m4n8b2v6",
        "taskKey": "WEB-42",
        "projectId": "p-w1e8r5t2",
        "userId": "u-p7d2x8q4",
        "seconds": 5400,
        "date": "2026-10-09",
        "note": "Вёрстка и валидация"
      }
    ],
    "attachments": [
      {
        "id": "f-u8i9o0",
        "name": "макет.png",
        "size": 182340,
        "type": "image/png"
      }
    ],
    "docIds": [
      "d-feedback"
    ]
  }
}

Удалить задачу

DELETE/tasks/{ref}

Право ключа: tasks:write

Безвозвратно, вместе со списанным временем.

curl -X DELETE "https://klepps.ru/api/v1/tasks/WEB-42" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
204 No Content

Комментарии

GET/tasks/{ref}/comments

Право ключа: tasks:read

Обсуждение задачи, старые сверху. Текст — простой, с переносами строк; упоминания — @логин.

Параметры пути

refобязательноstringid или ключ задачи

Параметры запроса

limit, cursorПостраничная выдача
curl "https://klepps.ru/api/v1/tasks/WEB-42/comments" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "m-z7x6c5v4",
      "authorId": "u-p7d2x8q4",
      "text": "Готово: форма отправляет заявку, валидация полей на клиенте и сервере.",
      "replyTo": null,
      "createdAt": 1760090000000
    },
    {
      "id": "m-q2w3e4r5",
      "authorId": "u-k3f9a2m1",
      "text": "Спасибо, проверю на стенде.",
      "replyTo": "m-z7x6c5v4",
      "createdAt": 1760091200000
    }
  ],
  "nextCursor": null,
  "total": 2
}

Написать комментарий

POST/tasks/{ref}/comments

Право ключа: tasks:write

От имени пользователя ключа. Автор и исполнители задачи, упомянутые и автор комментария, на который отвечают, получают уведомление во «Входящих». Сюда ИИ-агенту стоит писать результат работы, не меняя описание задачи.

Тело запроса (JSON)

textобязательноstringТекст, до 20 000 символов
replyTostring | nullid комментария, на который это ответ
curl -X POST "https://klepps.ru/api/v1/tasks/WEB-42/comments" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Готово: форма отправляет заявку, валидация полей на клиенте и сервере. @anna@romashka.ru посмотрите, пожалуйста."
}'
Ответ
{
  "data": {
    "id": "m-z7x6c5v4",
    "authorId": "u-p7d2x8q4",
    "text": "Готово: форма отправляет заявку, валидация полей на клиенте и сервере.",
    "replyTo": null,
    "createdAt": 1760090000000
  }
}

Учёт времени

Записи времени привязаны к дню (ГГГГ-ММ-ДД). В отчёты попадают и задачи из архива.

Отчёт по времени

GET/time/report

Право ключа: time:read

Суммы за период в разрезе людей, задач, проектов или дней — до трёх разрезов сразу (например, user,task — кто сколько потратил на каждую задачу).

Параметры запроса

from, toГГГГ-ММ-ДДПериод включительно, не больше года; по умолчанию с 1-го числа по сегодня
groupByuser, task, project, dayРазрезы через запятую, по умолчанию user
userId, projectId, taskIdstringФильтры, можно несколько через запятую
curl "https://klepps.ru/api/v1/time/report?from=2026-10-01&to=2026-10-31&groupBy=user,project" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "groupBy": [
    "user",
    "project"
  ],
  "totalSeconds": 129600,
  "totalHours": 36,
  "data": [
    {
      "user": {
        "id": "u-p7d2x8q4",
        "name": "Иван Петров"
      },
      "project": {
        "id": "p-w1e8r5t2",
        "key": "WEB",
        "name": "Сайт"
      },
      "seconds": 86400,
      "entries": 14,
      "hours": 24
    },
    {
      "user": {
        "id": "u-k3f9a2m1",
        "name": "Анна Смирнова"
      },
      "project": {
        "id": "p-w1e8r5t2",
        "key": "WEB",
        "name": "Сайт"
      },
      "seconds": 43200,
      "entries": 9,
      "hours": 12
    }
  ]
}

Записи времени

GET/time/entries

Право ключа: time:read

Отдельные записи, новые сверху — для выгрузки в 1С, BI или табель.

Параметры запроса

from, toГГГГ-ММ-ДДПериод, как в отчёте
userId, projectId, taskIdstringФильтры через запятую
limit, cursorПостраничная выдача
curl "https://klepps.ru/api/v1/time/entries?from=2026-10-01&to=2026-10-31&userId=u-p7d2x8q4" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "tl-a8s7d6f5",
      "taskId": "t-m4n8b2v6",
      "taskKey": "WEB-42",
      "projectId": "p-w1e8r5t2",
      "userId": "u-p7d2x8q4",
      "seconds": 5400,
      "date": "2026-10-09",
      "note": "Вёрстка и валидация"
    }
  ],
  "nextCursor": null,
  "total": 1
}

Списать время

POST/tasks/{ref}/time

Право ключа: time:write

Время записывается на пользователя ключа.

Тело запроса (JSON)

minutes / secondsобязательноnumberСколько (от 1 минуты до 7 суток)
dateГГГГ-ММ-ДДДень, по умолчанию сегодня (МСК)
notestringЧто делали
curl -X POST "https://klepps.ru/api/v1/tasks/WEB-42/time" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "minutes": 90,
  "date": "2026-10-09",
  "note": "Вёрстка и валидация"
}'
Ответ
{
  "data": {
    "id": "tl-a8s7d6f5",
    "taskId": "t-m4n8b2v6",
    "taskKey": "WEB-42",
    "projectId": "p-w1e8r5t2",
    "userId": "u-p7d2x8q4",
    "seconds": 5400,
    "date": "2026-10-09",
    "note": "Вёрстка и валидация"
  }
}

Документы

Видны только разделы, которые может читать пользователь ключа. Содержимое — HTML (content) и простой текст (text). При записи HTML очищается: скрипты, стили и чужие теги удаляются.

Разделы

GET/doc-spaces

Право ключа: docs:read

curl "https://klepps.ru/api/v1/doc-spaces" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "ds-tech",
      "name": "Техническая документация",
      "description": "Архитектура, API, инфраструктура"
    }
  ]
}

Список страниц

GET/docs

Право ключа: docs:read

Без содержимого, в порядке дерева.

Параметры запроса

spaceIdstringРаздел
parentIdstringДочерние страницы; none — верхнего уровня
taskIdstringСтраницы, связанные с задачей
qstringПоиск по названию и тексту
updatedSinceISO 8601 | мсИзменённые после момента
limit, cursorПостраничная выдача
curl "https://klepps.ru/api/v1/docs?spaceId=ds-tech" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "d-feedback",
      "spaceId": "ds-tech",
      "parentId": null,
      "title": "Форма обратной связи",
      "taskIds": [
        "t-m4n8b2v6"
      ],
      "authorId": "u-k3f9a2m1",
      "createdAt": 1759900000000,
      "updatedAt": 1760080000000
    }
  ],
  "nextCursor": null,
  "total": 1
}

Страница целиком

GET/docs/{id}

Право ключа: docs:read

Параметры запроса

formatjson | markdownmarkdown — страница простым Markdown-текстом (удобно для ИИ)
curl "https://klepps.ru/api/v1/docs/d-feedback" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "id": "d-feedback",
    "spaceId": "ds-tech",
    "parentId": null,
    "title": "Форма обратной связи",
    "taskIds": [
      "t-m4n8b2v6"
    ],
    "authorId": "u-k3f9a2m1",
    "createdAt": 1759900000000,
    "updatedAt": 1760080000000,
    "content": "<h2>Поля</h2><ul><li>Имя</li><li>Контакт</li></ul>",
    "text": "Поля\nИмя\nКонтакт",
    "attachments": []
  }
}

Создать страницу

POST/docs

Право ключа: docs:write

Тело запроса (JSON)

spaceIdобязательноstringРаздел
titleобязательноstringЗаголовок
parentIdstringРодительская страница
content / textstringСодержимое в HTML или простым текстом
curl -X POST "https://klepps.ru/api/v1/docs" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "spaceId": "ds-tech",
  "title": "Релиз 1.4.2",
  "text": "Что вошло:\n— форма обратной связи\n— тёмная тема"
}'
Ответ
{
  "data": {
    "id": "d-r3l3as",
    "spaceId": "ds-tech",
    "parentId": null,
    "title": "Релиз 1.4.2",
    "taskIds": [],
    "authorId": "u-k3f9a2m1",
    "createdAt": 1759900000000,
    "updatedAt": 1760080000000,
    "content": "<p>Что вошло:<br>— форма обратной связи<br>— тёмная тема</p>",
    "text": "Что вошло:\n— форма обратной связи\n— тёмная тема",
    "attachments": []
  }
}

Изменить страницу

PATCH/docs/{id}

Право ключа: docs:write

Прежний текст сохраняется в истории версий (не чаще раза в час), изменение попадает в журнал документа.

Тело запроса (JSON)

titlestringЗаголовок
content / textstringНовое содержимое целиком
curl -X PATCH "https://klepps.ru/api/v1/docs/d-feedback" \
  -H "Authorization: Bearer $KLEPPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "<h2>Поля</h2><ul><li>Имя</li><li>Контакт</li><li>Сообщение</li></ul>"
}'
Ответ
{
  "data": {
    "id": "d-feedback",
    "spaceId": "ds-tech",
    "parentId": null,
    "title": "Форма обратной связи",
    "taskIds": [
      "t-m4n8b2v6"
    ],
    "authorId": "u-k3f9a2m1",
    "createdAt": 1759900000000,
    "updatedAt": 1760080000000,
    "content": "<h2>Поля</h2><ul><li>Имя</li><li>Контакт</li><li>Сообщение</li></ul>",
    "text": "Поля\nИмя\nКонтакт\nСообщение",
    "attachments": []
  }
}

Транскрипты встреч

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

Папки встреч

GET/meeting-folders

Право ключа: meetings:read

curl "https://klepps.ru/api/v1/meeting-folders" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "mf-dev",
      "name": "Разработка",
      "parentId": null,
      "teamIds": [
        "tm-frontend"
      ]
    }
  ]
}

Список встреч

GET/meetings

Право ключа: meetings:read

Новые сверху.

Параметры запроса

folderIdstringПапка; personal — личные
projectIdstringПроект встречи
statusstringrecording, transcribing, done, failed…
from, toГГГГ-ММ-ДДДата встречи
qstringПоиск по названию и саммари
limit, cursorПостраничная выдача
curl "https://klepps.ru/api/v1/meetings?from=2026-10-01" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": [
    {
      "id": "mt-h5j6k7",
      "title": "Планирование спринта",
      "url": "https://telemost.yandex.ru/j/12345678901234",
      "folderId": "mf-dev",
      "projectId": "p-w1e8r5t2",
      "createdBy": "u-k3f9a2m1",
      "startedAt": 1760010060000,
      "endedAt": 1760012700000,
      "status": "done",
      "participants": [
        "Анна Смирнова",
        "Иван Петров"
      ],
      "transcriptReady": true,
      "hasSummary": true
    }
  ],
  "nextCursor": null,
  "total": 1
}

Встреча с саммари

GET/meetings/{id}

Право ключа: meetings:read

curl "https://klepps.ru/api/v1/meetings/mt-h5j6k7" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "id": "mt-h5j6k7",
    "title": "Планирование спринта",
    "url": "https://telemost.yandex.ru/j/12345678901234",
    "folderId": "mf-dev",
    "projectId": "p-w1e8r5t2",
    "createdBy": "u-k3f9a2m1",
    "startedAt": 1760010060000,
    "endedAt": 1760012700000,
    "status": "done",
    "participants": [
      "Анна Смирнова",
      "Иван Петров"
    ],
    "transcriptReady": true,
    "hasSummary": true,
    "summary": {
      "overview": "Спланировали спринт 14: форма обратной связи, тёмная тема, исправление оплаты.",
      "topics": [
        {
          "title": "Форма обратной связи",
          "points": [
            "Нужна капча",
            "Ответ — на e-mail или телефон"
          ]
        }
      ],
      "decisions": [
        "Релиз 1.4.2 — 20 октября"
      ],
      "actionItems": [
        {
          "text": "Сверстать форму",
          "owner": "Иван Петров",
          "due": "2026-10-15",
          "taskId": "t-m4n8b2v6"
        }
      ],
      "generatedAt": 1760013000000
    }
  }
}

Транскрипт

GET/meetings/{id}/transcript

Право ключа: meetings:read

Реплики по порядку. С format=text — простой текст «[чч:мм:сс] Имя: реплика» построчно.

Параметры запроса

formatjson | textПо умолчанию json
curl "https://klepps.ru/api/v1/meetings/mt-h5j6k7/transcript" \
  -H "Authorization: Bearer $KLEPPS_KEY"
Ответ
{
  "data": {
    "meetingId": "mt-h5j6k7",
    "replicas": [
      {
        "speaker": "Анна Смирнова",
        "start": "00:00:04",
        "end": "00:00:11",
        "text": "Коллеги, начнём. Сегодня планируем четырнадцатый спринт."
      },
      {
        "speaker": "Иван Петров",
        "start": "00:00:12",
        "end": "00:00:20",
        "text": "Предлагаю начать с формы обратной связи, макет уже готов."
      }
    ]
  }
}

Примеры интеграций

Табель за месяц в Excel (CSV)

# Отчёт по времени за прошлый месяц: кто сколько часов потратил на какую задачу
import csv, datetime, os, requests

today = datetime.date.today()
last = today.replace(day=1) - datetime.timedelta(days=1)
res = requests.get(
    "https://klepps.ru/api/v1/time/report",
    params={"from": last.replace(day=1).isoformat(), "to": last.isoformat(), "groupBy": "user,task"},
    headers={"Authorization": f"Bearer {os.environ['KLEPPS_KEY']}"},
)
res.raise_for_status()
with open("time.csv", "w", newline="", encoding="utf-8-sig") as f:
    w = csv.writer(f, delimiter=";")
    w.writerow(["Сотрудник", "Задача", "Название", "Часы"])
    for row in res.json()["data"]:
        w.writerow([row["user"]["name"], row["task"]["key"], row["task"]["title"], str(row["hours"]).replace(".", ",")])

Заявка с сайта или из CRM — задача

// Заявка с сайта или из CRM → задача в Klepps
await fetch("https://klepps.ru/api/v1/tasks", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.KLEPPS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    projectId: "p-w1e8r5t2",
    title: `Заявка: ${lead.company}`,
    descriptionText: `${lead.name}, ${lead.phone}\n\n${lead.message}`,
    labels: ["заявка"],
    priority: "high",
    dueDate: new Date(Date.now() + 86400000).toISOString().slice(0, 10),
  }),
});

Синхронизация изменений

// Забираем всё, что изменилось с прошлого запуска (постранично)
let since = loadCheckpoint();            // ISO-время прошлого запуска
const started = new Date().toISOString();
let cursor = null;
do {
  const url = new URL("https://klepps.ru/api/v1/tasks");
  url.searchParams.set("updatedSince", since);
  url.searchParams.set("archived", "all");
  url.searchParams.set("limit", "500");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.KLEPPS_KEY}` } });
  const page = await res.json();
  for (const task of page.data) await upsert(task);
  cursor = page.nextCursor;
} while (cursor);
saveCheckpoint(started);

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