Перейти к основному содержимому

Notion

Notion API + ntn CLI: страницы, базы данных, Markdown, Workers.

Метаданные навыка​

ИсточникВстроенный (устанавливается по умолчанию)
Путьskills/productivity/notion
Версия2.0.0
Авторcommunity
ЛицензияMIT
Платформыlinux, macos, windows
ТегиNotion, Productivity, Notes, Database, API, CLI, Workers

Справочник: полный SKILL.md​

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Агент видит эти инструкции, когда навык активен.

Notion

Взаимодействуйте с Notion двумя способами. Один и тот же токен интеграции подходит для обоих — выбирайте по доступности.

◆ ntn CLI — официальный CLI Notion. Более короткий синтаксис, загрузка файлов одной строкой, обязателен для Workers. Только macOS и Linux по состоянию на май 2026 года (поддержка Windows «скоро появится»). Используется по умолчанию, если установлен. ◆ HTTP + curl — работает везде, включая Windows. Запасной вариант по умолчанию, если ntn не установлен.

Настройка​

1. Получите токен интеграции (требуется для обоих путей)​

  1. Создайте интеграцию на https://notion.so/my-integrations
  2. Скопируйте ключ API (начинается с ntn_ или secret_)
  3. Сохраните в ${VIBEOS_HOME:-~/.vibeos}/.env: 
    NOTION_API_KEY=ntn_your_key_here
  4. Предоставьте интеграции доступ к целевым страницам/базам данных в Notion: меню страницы ... → Подключить → название вашей интеграции. Без этого API вернёт 404 для этой страницы, даже если она существует.

2. Установите ntn (предпочтительный путь на macOS / Linux)​

# Рекомендуемый способ
curl -fsSL https://ntn.dev | bash

# Или через npm (требуется Node 22+, npm 10+)
npm install --global ntn

ntn --version    # проверка

Пропустите ntn login — используйте токен интеграции. Это работает без графического интерфейса, браузер не нужен:

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn читает NOTION_API_TOKEN
export NOTION_KEYRING=0                       # не пытаться использовать системную связку ключей

Добавьте эти export в ваш профиль оболочки (или в ${VIBEOS_HOME:-~/.vibeos}/.env), чтобы каждая сессия их наследовала.

3. Выбор пути во время выполнения​

if command -v ntn >/dev/null 2>&1; then
  # используем ntn
else
  # используем curl как запасной вариант
fi

Пользователи Windows: полностью пропустите шаг 2, пока не появится нативная версия ntn — путь B работает отлично. Если вам нужен CLI прямо сейчас, установите ntn внутри WSL2.

Основы API​

Notion-Version: 2025-09-03 обязателен для всех HTTP-запросов. ntn обрабатывает это автоматически. В этой версии то, что пользователи называют «базами данных», в API называется data sources.

Путь A — ntn CLI (предпочтительный, macOS / Linux)​

Прямые вызовы API (сокращение для curl)​

ntn api v1/users                                  # GET
ntn api v1/pages parent[page_id]=abc123 \         # POST с встроенным телом
  properties[title][0][text][content]="Заметки"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH; := для нестроковых типов (bool/num/null)

Примечания по синтаксису:

  • key=value — строковые поля
  • key[nested]=value — вложенные поля объектов
  • key:=value — типизированное присваивание (логические значения, числа, null, массивы)

Поиск​

ntn api v1/search query="заголовок страницы"

Чтение метаданных страницы​

ntn api v1/pages/{page_id}

Чтение страницы в формате Markdown (удобно для агента)​

ntn api v1/pages/{page_id}/markdown

Чтение содержимого страницы в виде блоков​

ntn api v1/blocks/{page_id}/children

Создание страницы из Markdown​

ntn api v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="Заметки со встречи" \
  markdown="# Повестка

- Дорожная карта Q3
- Найм"

Обновление страницы с помощью Markdown​

ntn api v1/pages/{page_id}/markdown -X PATCH \
  markdown="## Обновление

Запустили прототип."

Запрос к базе данных (data source)​

ntn api v1/data_sources/{data_source_id}/query -X POST \
  filter[property]=Status filter[select][equals]=Active

Для сложных запросов с sorts, несколькими условиями фильтрации или составной логикой передавайте JSON через конвейер:

echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \
  ntn api v1/data_sources/{data_source_id}/query -X POST --json -

Загрузка файлов (одна строка — главное преимущество CLI)​

ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

Сравните с 3-шаговым HTTP-процессом (создание загрузки → PUT байтов → ссылка).

Полезные переменные окружения​

ПеременнаяЭффект
NOTION_API_TOKENТокен аутентификации (переопределяет связку ключей) — установите в ваш токен интеграции
NOTION_KEYRING=0Хранение учётных данных в файле ~/.config/notion/auth.json вместо системной связки ключей
NOTION_WORKSPACE_IDПропустить запрос выбора рабочего пространства

Путь B — HTTP + curl (кроссплатформенный, по умолчанию на Windows)​

Все запросы следуют этому шаблону:

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

На Windows curl, входящий в состав Windows 10+, работает как есть. Пользователи PowerShell также могут использовать Invoke-RestMethod.

Поиск​

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "заголовок страницы"}'

Чтение метаданных страницы​

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Чтение страницы в формате Markdown (удобно для агента)​

Проще передать модели, чем блоки JSON.

curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Чтение содержимого страницы в виде блоков (когда нужна структура)​

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Создание страницы из Markdown​

POST /v1/pages принимает параметр тела markdown.

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "properties": {"title": [{"text": {"content": "Заметки со встречи"}}]},
    "markdown": "# Повестка\n\n- Дорожная карта Q3\n- Найм\n\n## Решения\n- Запустить MVP в пятницу"
  }'

Обновление страницы с помощью Markdown​

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "## Обновление\n\nЗапустили прототип."}'

Создание страницы в базе данных (типизированные свойства)​

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "Новый элемент"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

Запрос к базе данных (data source)​

curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

Создание базы данных​

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "Моя база данных"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

Обновление свойств страницы​

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Добавление блоков на страницу​

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Привет от VibeOS!"}}]}}
    ]
  }'

Загрузка файлов (3-шаговый процесс)​

# 1. Создание загрузки
curl -s -X POST "https://api.notion.com/v1/file_uploads" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.png", "content_type": "image/png"}'

# 2. PUT байтов в upload_url, полученный выше
curl -s -X PUT "{upload_url}" --data-binary @photo.png

# 3. Ссылка на {file_upload_id} в полезной нагрузке страницы/блока

Типы свойств​

Распространённые форматы свойств для элементов базы данных:

  • Title: {"title": [{"text": {"content": "..."}}]}
  • Rich text: {"rich_text": [{"text": {"content": "..."}}]}
  • Select: {"select": {"name": "Option"}}
  • Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
  • Date: {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
  • Checkbox: {"checkbox": true}
  • Number: {"number": 42}
  • URL: {"url": "https://..."}
  • Email: {"email": "user@example.com"}
  • Relation: {"relation": [{"id": "page_id"}]}

Версия API 2025-09-03 — Базы данных vs Data Sources​

  • Базы данных стали data sources. Используйте конечные точки /data_sources/ для запросов и получения данных.
  • Два ID на базу данных: database_id и data_source_id.
    • database_id при создании страниц: parent: {"database_id": "..."}
    • data_source_id при выполнении запросов: POST /v1/data_sources/{id}/query
  • Поиск возвращает базы данных как "object": "data_source" с полем data_source_id.

Notion Workers (продвинутый уровень, требуется ntn)​

Workers — это программы на TypeScript, которые Notion размещает за вас. Один worker может предоставлять любую комбинацию:

  • Syncs — извлекают данные из внешних API в базу данных Notion по расписанию (по умолчанию 30 мин).
  • Tools — отображаются как вызываемые инструменты внутри Custom Agents Notion.
  • Webhooks — получают HTTP-события от внешних сервисов (GitHub, Stripe и т.д.) и выполняют действия в Notion.

План / ограничения платформы:

  • CLI работает на всех тарифных планах. Развёртывание Workers требует тарифа Business или Enterprise.
  • ntn доступен только на macOS/Linux по состоянию на май 2026 года. Пользователям Windows нужен WSL2 или ожидание нативной поддержки.
  • Бесплатно до 11 августа 2026 года; далее оплата через Notion credits.

Минимальный Worker​

ntn workers new my-worker      # создание каркаса
cd my-worker
# Редактируем src/index.ts
ntn workers deploy --name my-worker

src/index.ts:

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("greet", {
  title: "Поприветствовать пользователя",
  description: "Возвращает дружеское приветствие",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => `Привет, ${name}!`,
});

Возможность вебхука​

worker.webhook("onGithubPush", {
  title: "Обработчик Push GitHub",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody (для проверки подписи), event.headers
      console.log("получена доставка", event.deliveryId);
    }
  },
});

После развёртывания: ntn workers webhooks list показывает URL, сгенерированный Notion. Относитесь к этому URL как к секрету — любой, у кого он есть, может отправлять события, если вы не добавите проверку подписи.

Команды жизненного цикла Worker​

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # запустить синхронизацию сейчас
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list                     # недавние вызовы
ntn workers runs logs <run-id>
ntn workers webhooks list

Когда требуется создать Worker, создайте каркас с помощью ntn workers new, напишите код в src/index.ts, установите секреты через ntn workers env set и разверните. Документация Notion на https://developers.notion.com/workers охватывает полную поверхность API.

Notion-Flavored Markdown (используется конечными точками /markdown)​

Стандартный CommonMark плюс XML-подобные теги для специфических блоков Notion. Используйте табуляцию для отступов.

Блоки за пределами CommonMark:

<callout icon="🎯" color="blue_bg">
	Запустите MVP к **пятнице**.
</callout>

<details color="gray">
<summary>Заголовок переключателя</summary>
	Дочерние элементы с отступом в одну табуляцию
</details>

<columns>
	<column>Левая сторона</column>
	<column>Правая сторона</column>
</columns>

<table_of_contents color="gray"/>

Встроенные элементы:

  • Упоминания: &lt;mention-user url="..."/&gt;, &lt;mention-page url="..."&gt;Название&lt;/mention-page&gt;, &lt;mention-date start="2026-05-15"/&gt;
  • Подчёркивание: <span underline="true">текст</span>
  • Цвет: <span color="blue">текст</span> или на уровне блока {color="blue"} на первой строке
  • Математика: встроенная $x^2$, блочная $$ ... $$`
  • Цитаты: [^https://example.com]

Цвета: gray brown orange yellow green blue purple pink red, плюс варианты *_bg для фонов.

Заголовки 5/6 сворачиваются до H4. Несколько строк > отображаются как отдельные блоки цитат — используйте <br> внутри одной > для многострочных цитат.

Выбор правильного пути​

Задачаmac / LinuxWindows
Чтение/запись страниц, поиск, запросы к базам данныхntn api ...curl
Чтение страницы для обобщения агентомntn api v1/pages/{id}/markdowncurl /markdown endpoint
Загрузка файлаntn files create < file3-шаговый HTTP-процесс
Разовое исследование APIntn api ...curl
Создание синхронизации / вебхука / инструмента агента, размещённого Notionntn workers ...WSL2 + ntn workers ...

Примечания​

  • ID страниц/баз данных — это UUID (с дефисами или без — принимаются оба варианта).
  • Лимит запросов: ~3 запроса/секунду в среднем. CLI не обходит это ограничение.
  • API не может устанавливать фильтры представления базы данных — это только через интерфейс.
  • Используйте "is_inline": true при создании data sources для встраивания их на страницу.
  • Всегда передавайте -s в curl для подавления индикаторов прогресса (более чистый вывод для агента).
  • Передавайте JSON через jq при чтении: ... | jq '.results[0].properties'.
  • Notion также предоставляет MCP-сервер (Notion MCP, ~91% эффективнее по токенам для операций с БД, чем предыдущая версия) — подключите его через поддержку MCP в VibeOS, если хотите потоковый доступ к Notion из сессии, но описанных выше путей достаточно для большинства одноразовых задач.