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

инфо

Ниже приведено полное определение навыка, которое Hermes загружает при его активации. Именно этот текст агент видит как инструкции, когда навык включён.

Notion

Два способа работы с Notion. Оба используют один и тот же токен интеграции — выбирай по тому, что доступно.

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

Настройка

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

Создай интеграцию на https://notion.so/my-integrations
Скопируй API-ключ (начинается с ntn_ или secret_)
Запиши в ~/.hermes/.env:
```
NOTION_API_KEY=ntn_your_key_here
```
Открой нужные страницы/базы данных для интеграции в Notion: меню страницы ... → Connect to → название интеграции. Без этого шага 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 — вместо него используй токен интеграции. Работает без браузера, в headless-режиме:

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN
export NOTION_KEYRING=0                       # don't try to use the OS keychain

Добавь эти экспорты в профиль оболочки (или в ~/.hermes/.env), чтобы они применялись в каждой сессии.

3. Выбор пути в рантайме

if command -v ntn >/dev/null 2>&1; then
  # use ntn
else
  # fall back to 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 with inline body
  properties[title][0][text][content]="Notes"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH; := is non-string (bool/num/null)

Синтаксис:

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

Поиск

ntn api v1/search query="page title"

Метаданные страницы

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]="Notes from meeting" \
  markdown="# Agenda

- Q3 roadmap
- Hiring"

Обновление страницы через Markdown

ntn api v1/pages/{page_id}/markdown -X PATCH \
  markdown="## Update

Shipped the prototype."

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

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

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

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

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

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

Переменная	Действие
`NOTION_API_TOKEN`	Токен аутентификации (перекрывает keychain) — задай токен интеграции
`NOTION_KEYRING=0`	Хранить учётные данные в `~/.config/notion/auth.json` вместо keychain ОС
`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": "page title"}'

Метаданные страницы

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": "Notes from meeting"}}]},
    "markdown": "# Agenda\n\n- Q3 roadmap\n- Hiring\n\n## Decisions\n- Ship MVP Friday"
  }'

Обновление страницы через 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": "## Update\n\nShipped the prototype."}'

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

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": "New Item"}}]},
      "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": "My Database"}}],
    "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": "Hello from Hermes!"}}]}}
    ]
  }'

Загрузка файлов (трёхшаговый процесс)

# 1. Создать upload
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 — Databases и 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 по состоянию на май 2026 года — только macOS/Linux. Пользователям Windows нужен WSL2 или ожидание нативной поддержки.
Бесплатно до 11 августа 2026 года; после — оплата в кредитах Notion.

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

ntn workers new my-worker      # создать заготовку
cd my-worker
# Edit 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: "Greet a User",
  description: "Returns a friendly greeting",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => `Hello, ${name}!`,
});

Тип capability: Webhook

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

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

Управление Workers

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # запустить sync прямо сейчас
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 и задеплой. Полный API описан в документации Notion: https://developers.notion.com/workers

Notion-Flavored Markdown (используется эндпоинтами `/markdown`)

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

Блоки сверх CommonMark:

<callout icon="🎯" color="blue_bg">
	Ship the MVP by **Friday**.
</callout>

<details color="gray">
<summary>Toggle title</summary>
	Children indented one tab
</details>

<columns>
	<column>Left side</column>
	<column>Right side</column>
</columns>

<table_of_contents color="gray"/>

Инлайн-элементы:

Упоминания: <mention-user url="..."/>, <mention-page url="...">Title</mention-page>, <mention-date start="2026-05-15"/>
Подчёркивание: text
Цвет: text или на уровне блока {color="blue"} в первой строке
Математика: инлайн $x^2$ , блочная $$ ... $$
Цитирование источников: [^https://example.com]

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

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

Выбор пути

Задача	mac / Linux	Windows
Чтение/запись страниц, поиск, запросы к базам данных	`ntn api ...`	curl
Прочитать страницу для обработки агентом	`ntn api v1/pages/{id}/markdown`	curl, эндпоинт `/markdown`
Загрузить файл	`ntn files create < file`	трёхшаговый HTTP-процесс
Разовое исследование API	`ntn api ...`	curl
Создать sync / webhook / инструмент агента на хостинге Notion	`ntn workers ...`	WSL2 + `ntn workers ...`

Примечания

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

Notion

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

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

Notion

Настройка

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

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

3. Выбор пути в рантайме

Основы API

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

Прямые вызовы API (сокращённый синтаксис вместо curl)

Поиск

Метаданные страницы

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

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

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

Обновление страницы через Markdown

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

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

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

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

Поиск

Метаданные страницы

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

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

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

Обновление страницы через Markdown

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

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

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

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

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

Загрузка файлов (трёхшаговый процесс)

Типы свойств

Версия API 2025-09-03 — Databases и Data Sources

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

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

Тип capability: Webhook

Управление Workers

Notion-Flavored Markdown (используется эндпоинтами /markdown)

Выбор пути

Примечания

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

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

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

Notion-Flavored Markdown (используется эндпоинтами `/markdown`)