Интеграции и API

Публичный программный интерфейс

Base URL:

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

OpenAPI:

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 привязан к источнику. Он подходит для интеграций, которые отправляют один URL, ждут завершения и затем забирают фрагменты или экспорт.

Шаг	Endpoint
Список проектов	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 сохраняет существующее публичное написание.

Поставить экспорт в 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 endpoint:

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

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

Authorization: Bearer kn_...

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

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

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

Вебхуки для экспорта

Пользователь настраивает Integration Webhook в настройках приложения.

Webhook payload отправляется после успешного Markdown-экспорта. Он включает:

• имя события;
• export id;
• metadata источника;
• Markdown выбранных фрагментов;
• file URL, если включена файловая доставка;
• prefix metadata API-ключа.

Webhook — это не callback URL для отправки источников. Это пользовательская настройка доставки экспортов.

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

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

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

Читайте Retry-After на retryable-ответах.

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

Держите внешние клиенты source-scoped, пока им не нужна project-wide query model.

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