Интеграции и автоматизация

Что выбрать

Задача	Что использовать
Скачать выбранные фрагменты вручную	Обычный экспорт в Markdown
Автоматически отправлять готовый экспорт в другой сервис	Интеграционный вебхук
Отправлять источники и забирать фрагменты из скрипта	Публичный API
Подключить Knowlume к Claude, Cursor или другому MCP-клиенту	MCP-сервер

Если вы не разработчик

Вам не нужно писать curl-запросы, чтобы пользоваться Knowlume.

Для большинства сценариев достаточно:

1. создать проект;
2. добавить источники;
3. выбрать фрагменты;
4. экспортировать Markdown;
5. при необходимости указать адрес вебхука в настройках.

API-ключ создавайте только тогда, когда внешний инструмент явно просит ключ доступа к Knowlume. Храните его как пароль. Если ключ попал в чужие руки, удалите его и создайте новый.

Вебхук нужен только для доставки уже готового экспорта. Он не добавляет источники в Knowlume.

Публичный API

Публичный API подходит для сценария "отправить один источник, дождаться обработки, забрать фрагменты или экспорт".

Базовый адрес:

https://app.knowlu.me/api/public/v1

Интерактивная справка:

https://app.knowlu.me/api/public/v1/docs
https://app.knowlu.me/api/public/v1/redoc
https://app.knowlu.me/api/public/v1/openapi.json

Аутентификация:

Authorization: Bearer kn_...

При отправке источника также нужен ключ идемпотентности: уникальная строка для одной попытки отправки. Она защищает от случайных дублей при повторе запроса.

Idempotency-Key: <unique-key-per-submit-attempt>

Порядок работы с API

Шаг	Запрос
Список проектов	GET /projects
Отправить один URL-источник	POST /sources
Опросить статус источника	GET /sources/{source_id}
Прочитать фрагменты	GET /sources/{source_id}/fragments
Поставить Markdown-экспорт в очередь	POST /sources/{source_id}/export
Опросить экспорт	GET /exports/{export_id}

Отправить источник

Технический пример для разработчиков:

curl -i https://app.knowlu.me/api/public/v1/sources \
  -H "Authorization: Bearer $KNOWLUME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/article",
    "title": "Optional title",
    "project_slug": "inbox"
  }'

Успешный запрос возвращает 202 Accepted и source_id.

Опросить статус

curl -sS https://app.knowlu.me/api/public/v1/sources/$SOURCE_ID \
  -H "Authorization: Bearer $KNOWLUME_API_KEY"

Завершающие статусы: succeeded и failed.

Получить отфильтрованные фрагменты

curl -sS "https://app.knowlu.me/api/public/v1/sources/$SOURCE_ID/fragments?reproducibility_min=7&originality_min=6&sourcesness_min=5&limit=50" \
  -H "Authorization: Bearer $KNOWLUME_API_KEY"

Фильтры оценок включительные. sourcesness сохраняет существующее публичное написание для совместимости с API.

Поставить экспорт в Markdown в очередь

curl -sS -X POST "https://app.knowlu.me/api/public/v1/sources/$SOURCE_ID/export" \
  -H "Authorization: Bearer $KNOWLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "markdown",
    "reproducibility_min": 7,
    "originality_min": 6,
    "sourcesness_min": 5
  }'

Затем опросите экспорт:

curl -sS "https://app.knowlu.me/api/public/v1/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $KNOWLUME_API_KEY"

MCP-сервер

MCP нужен, если внешний клиент умеет подключать MCP-серверы и должен работать с источниками, фрагментами или экспортами Knowlume.

Адрес сервера:

https://app.knowlu.me/mcp/

Аутентификация:

Authorization: Bearer kn_...

Пошагово:

1. Откройте Knowlume.
2. Создайте API-ключ в настройках.
3. В MCP-клиенте добавьте HTTP-сервер.
4. Укажите адрес https://app.knowlu.me/mcp/.
5. Добавьте заголовок авторизации Authorization: Bearer <ваш API-ключ>.
6. Сохраните подключение и выполните тестовый запрос к Knowlume.

Если открыть адрес MCP в браузере без ключа, можно увидеть ошибку авторизации. Это нормально: сервер не работает без ключа.

Пример для Claude Code:

claude mcp add --transport http knowlume https://app.knowlu.me/mcp/ \
  --header "Authorization: Bearer kn_..."

MCP предназначен для клиентов с агентами, которым нужен прямой доступ к источникам, фрагментам и экспортам Knowlume.

Доставка экспорта через вебхук

Пользователь настраивает интеграционный вебхук в настройках приложения.

Данные вебхука отправляются после успешного Markdown-экспорта. Они включают:

• имя события;
• идентификатор экспорта;
• служебные данные источника;
• Markdown выбранных фрагментов;
• ссылку на файл, если включена файловая доставка;
• префикс API-ключа для диагностики.

Вебхук — это не адрес для отправки источников в Knowlume. Это настройка доставки экспортов наружу.

Правила проектирования интеграций

Используйте ключи идемпотентности при повторных попытках отправки источника.

Опросите статус источника перед чтением фрагментов.

Учитывайте Retry-After, если сервер просит повторить запрос позже.

Не логируйте токены доступа, исходный текст, данные вебхука или полный экспортированный контент.

Держите внешние клиенты вокруг одного источника, пока им не нужен поиск по всему проекту.

Пользовательское поведение экспорта описано в Фрагменты, оценки и экспорт. Типовые ошибки запросов разобраны в Решение проблем.