Notion API

Взаимодействие с воркспейсами Notion через REST API: чтение, создание, обновление и удаление страниц, баз данных, блоков, комментариев. Используйте curl и jq для прямых REST-вызовов или пишите скрипты по ситуации.

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

Работа с API-ключом

Переменная окружения: проверить наличие NOTION_API_TOKEN в окружении
Ключ от пользователя: если пользователь предоставил ключ в контексте — использовать его
Ключ отсутствует: запросить у пользователя через AskUserQuestion или аналог

ВАЖНО: никогда не отображать, не логировать и не передавать NOTION_API_TOKEN никуда, кроме заголовка Authorization.

Заголовки запросов

-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"

Проверка аутентификации

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Базовые параметры

Base URL: https://api.notion.com
API Version: 2025-09-03 (обязательный заголовок)
Формат данных: JSON
ID: формат UUIDv4 (тире в запросах опциональны)
Временные метки: ISO 8601 (2020-08-12T02:12:33.231Z)
Имена свойств: snake_case
Пустые значения: null вместо пустых строк

Лимиты

Rate limits: в среднем 3 запроса/с на интеграцию; краткие всплески разрешены; HTTP 429 при превышении с заголовком Retry-After. Используйте exponential backoff при получении 429.

Тип	Лимит
Максимум блоков в payload	1000
Максимальный размер payload	500 KB
Содержимое rich text	2000 символов
URL	2000 символов
Multi-select опции	100 элементов
Relations	100 связанных страниц
Массив блоков на запрос	100 элементов

Подтверждение деструктивных операций: перед обновлением, удалением/архивированием страниц или блоков, изменением схем БД, пакетными операциями — запрашивайте подтверждение у пользователя. Для группы связанных операций достаточно одного подтверждения.

Основные эндпоинты

Поиск

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "поисковый запрос",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

Значения filter: "page" или "data_source" (или не указывать для обоих)

Страницы

Получить страницу

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

Возвращает свойства страницы, не контент. Для контента используйте "Получить дочерние блоки" с ID страницы.

Создать страницу

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {"title": [{"text": {"content": "Заголовок страницы"}}]}
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Содержимое"}}]
        }
      }
    ]
  }' | jq

Варианты parent: {"page_id": "..."}, {"database_id": "..."}, {"data_source_id": "..."}

Обновить страницу

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"title": {"title": [{"text": {"content": "Новый заголовок"}}]}}}' | jq

Архивировать (удалить) страницу

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

Блоки (контент страницы)

Получить дочерние блоки

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

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

Добавить дочерние блоки

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block", "type": "heading_2",
        "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Новый раздел"}}]}
      },
      {
        "object": "block", "type": "paragraph",
        "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Содержимое"}}]}
      }
    ]
  }' | jq

Максимум 100 блоков на запрос, до 2 уровней вложенности. Позиция: по умолчанию в конец; "position": {"type": "start"} — в начало; "type": "after_block" — после конкретного блока.

Обновить блок

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"paragraph": {"rich_text": [{"type": "text", "text": {"content": "Обновлённый текст"}}]}}' | jq

Удалить блок

curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Перемещает блок в корзину (можно восстановить).

Базы данных

Запрос базы данных

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Done"}},
    "sorts": [{"property": "Created", "direction": "descending"}],
    "page_size": 100
  }' | jq

Создать базу данных

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "Моя база данных"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {"select": {"options": [
          {"name": "To Do", "color": "red"},
          {"name": "In Progress", "color": "yellow"},
          {"name": "Done", "color": "green"}
        ]}},
        "Due Date": {"date": {}}
      }
    }
  }' | jq

Data Sources (API v2025-09-03+)

Data sources — отдельные таблицы внутри базы данных. Начиная с API версии 2025-09-03, базы данных могут содержать несколько data sources.

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "Новый источник данных"}}],
    "properties": {"Name": {"title": {}}, "Description": {"rich_text": {}}}
  }' | jq

Пользователи

# Список всех пользователей
curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

# Получить бота (себя)
curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

# Получить комментарии
curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

# Создать комментарий на странице
curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"parent": {"page_id": "page-id"}, "rich_text": [{"type": "text", "text": {"content": "Комментарий"}}]}' | jq

API не может создавать новые inline discussion-треды или редактировать/удалять существующие комментарии.

Пагинация

Постраничные эндпоинты возвращают: has_more (есть ли ещё результаты), next_cursor (курсор для следующей страницы), results (массив элементов).

Выполнить первый запрос (без start_cursor)
Проверить has_more
Если true — извлечь next_cursor и передать как start_cursor
Повторять до has_more: false

Обработка ошибок

HTTP	Код	Описание
400	invalid_json	Тело запроса не является валидным JSON
400	validation_error	Тело не соответствует ожидаемой схеме
401	unauthorized	Недействительный bearer-токен
403	restricted_resource	У токена нет разрешения
404	object_not_found	Ресурс не найден или не расшарен с интеграцией
429	rate_limited	Превышен rate limit (проверьте Retry-After)
500	internal_server_error	Неожиданная ошибка сервера
503	service_unavailable	Notion недоступен или превышен таймаут 60 с

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

Сохраняйте ID — при создании страниц/БД сохраняйте возвращённые ID для будущих обновлений
Используйте ID свойств — ссылайтесь на свойства по ID, а не по имени (стабильнее)
Пакетные операции — объединяйте несколько мелких операций в меньшее количество запросов
Соблюдайте rate limits — exponential backoff при 429
Проверяйте has_more — всегда обрабатывайте пагинацию
Валидируйте перед обновлением — получайте текущее состояние перед изменениями
Используйте переменные окружения — никогда не хардкодьте API-ключи
Размер схемы — держите схемы БД до 50 KB для оптимальной производительности

notion-apiNotion API Intellectronica

Установка