notion-api (generic)

notion-api (generic)

Этот skill предоставляет небольшой CLI-инструмент на Node.js для работы с Notion API. Он спроектирован как универсальный и легко переносимый: без жёстко прописанных идентификаторов баз данных и без хранения секретов в репозитории.

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

Для работы необходимо указать токен интеграции Notion одним из способов:

• через переменную окружения NOTION_KEY
• или через файл ~/.config/notion/api_key (токен в первой строке)

Также убедитесь, что нужные страницы или базы данных в Notion предоставлены доступу вашей интеграции.

Команды CLI

Все команды выполняются через:

node scripts/notion-api.mjs  ...

Поиск

node scripts/notion-api.mjs search "query" --page-size 10

Запрос к источнику данных (database)

node scripts/notion-api.mjs query --data-source-id  --page-size 10

# с передачей raw JSON
node scripts/notion-api.mjs query --data-source-id  --body '{"filter": {...}, "sorts": [...], "page_size": 10}'

Создание страницы в базе данных

node scripts/notion-api.mjs create-page \
 --database-id  \
 --title "My item" \
 --title-prop Name

Вывод данных

Все команды возвращают результат в формате JSON в стандартный вывод (stdout), что удобно для пайплайнов, логирования или дальнейшей обработки.

Примечания

• По умолчанию используется версия Notion API: 2025-09-03 (можно переопределить через NOTION_VERSION)
• Следует учитывать ограничения по rate limit — рекомендуется использовать page_size и минимизировать количество запросов

Обзор

Этот инструмент представляет собой лёгкий CLI для взаимодействия с Notion API: поиск, запросы к базам данных и создание страниц. Он не требует хранения секретов в коде и использует конфигурацию через окружение.

Все ответы возвращаются в JSON, что позволяет легко интегрировать его в скрипты, CI/CD-процессы или автоматизации.

Как работает

Аутентификация осуществляется через переменную NOTION_KEY или локальный файл с API-ключом. CLI предоставляет команды для поиска, выполнения запросов к базам данных и создания страниц.

Каждый запрос автоматически включает заголовок версии API и учитывает ограничения скорости. Результаты выводятся в stdout.

Когда использовать

• быстрый поиск по рабочему пространству Notion
• автоматизация отчётов и экспорт данных
• создание элементов в базе данных из внешних сервисов
• резервное копирование или синхронизация данных
• прототипирование интеграций без хранения секретов

Лучшие практики

• используйте NOTION_KEY или локальный файл — не храните ключи в репозитории
• предоставляйте доступ интеграции только к нужным страницам
• ограничивайте размер выборки через page_size
• для сложных запросов используйте raw JSON через --body
• меняйте версию API только при необходимости

Примеры использования

• поиск страниц и баз данных из командной строки
• ночной экспорт данных базы в JSON
• создание записи после успешного деплоя
• формирование отчётов через связку с другими инструментами
• миграция или синхронизация данных

FAQ

Как выполнить аутентификацию?
Установите NOTION_KEY или сохраните ключ в ~/.config/notion/api_key.

Можно ли использовать сложные фильтры?
Да, передавайте JSON через параметр --body.

Куда выводятся результаты?
Все данные выводятся в stdout в формате JSON.