Notion API 2026-03-11 — что изменилось и как обновить интеграции

Notion выпустил версию API 2026-03-11 — это первый major релиз после разделения баз данных на databases и data sources. Он приносит три breaking changes, которые ломают интеграции без обновления, но в 90% случаев миграция — это find-and-replace в клиентском коде.

Кратко о версии

2026-03-11 — текущая актуальная версия Notion API. Чтобы её включить, нужно явно указать заголовок Notion-Version: 2026-03-11 в каждом запросе либо передать параметр notionVersion: "2026-03-11" в SDK.

Официальный SDK @notionhq/client поддерживает версию начиная с v5.12.0.

Что сломается без обновления

Все три изменения — orthoгональные: починить одно не обязательно значит тронуть другое. Смотрите на свой код по каждому пункту отдельно.

1. after → объект position

Эндпоинт Append block children больше не принимает плоский after. Вместо этого передаётся объект position, который описывает, куда вставить блоки.

// 2025-09-03 (было)
{
  "children": [...],
  "after": "a1c2d3e4-..."
}

// 2026-03-11 (стало)
{
  "children": [...],
  "position": { "type": "after", "after": "a1c2d3e4-..." }
}

Новый position поддерживает три режима:

• { "type": "start" } — вставить в начало родителя. Раньше для этого приходилось выгружать всех детей, удалять и пересобирать вручную.
• { "type": "end" } — в конец (поведение по умолчанию).
• { "type": "after", "after": "<block_id>" } — строго после конкретного блока.

2. archived → in_trash

Поле archived в запросах и ответах полностью удалено. Всюду используется in_trash — флаг, который был добавлен ещё в апреле 2024 года как синоним, а теперь стал единственным.

// 2025-09-03 (было)
{ "page_id": "...", "archived": true }

// 2026-03-11 (стало)
{ "page_id": "...", "in_trash": true }

Это касается и страниц, и баз данных, и блоков, и data sources. Если вы парсите ответы и проверяете obj.archived — поле больше не будет. Условие всегда будет ложным, и удалённые сущности попадут в пайплайн бесшумно.

3. transcription → meeting_notes

Блок, который раньше хранил расшифровки AI Meeting Notes, переименован из transcription в meeting_notes. Имя типа и вложенного поля меняется одновременно.

// 2025-09-03 (было)
{
  "type": "transcription",
  "transcription": { "rich_text": [...] }
}

// 2026-03-11 (стало)
{
  "type": "meeting_notes",
  "meeting_notes": { "rich_text": [...] }
}

Обновить нужно везде, где вы фильтруете блоки по типу: обход страницы, выборка расшифровок для Notion CMS, выгрузка митингов в внешнюю базу.

Чеклист миграции

Неочевидные ловушки

Обёртки с дефолтными полями

Если вы используете обёртки вроде ultimate-notion или собственные dataclass со значениями по умолчанию (archived: bool = False), при сериализации model_dump(exclude_none=True) сохранит это поле — и валидатор Notion ругается.

Решение: используйте Optional/None или sentinel-значение Unset для полей, которые не должны уходить в запрос по умолчанию.

Выгруженные исторические данные

Если у вас есть сохранённые JSON-ответы API (логи, бэкапы баз знаний, синхронизация с ClickHouse) в формате до обновления — эти данные останутся со старыми именами полей. Решение — либо разовый миграционный скрипт, либо слой совместимости, который понимает оба формата при чтении.

Webhook payloads

События выбирают версию по настройке интеграции. Если вы переключили интеграцию на 2026-03-11, в webhook-пейлоадах уже будет in_trash и meeting_notes. Проверьте обработчики событий отдельно от основного клиента.

MCP-серверы и сторонние библиотеки

Не все сторонние обёртки (питонские SDK, R-пакеты, MCP-серверы) успевают за Notion. Перед обновлением проверьте в changelog вашей библиотеки, что она реально поддерживает 2026-03-11, а не просто пропускает версию в заголовок.

Контекст: почему это важно

2026-03-11 — это второй большой релиз после 2025-09-03, который вывел data sources как самостоятельный эндпоинт и разделил /v1/databases и /v1/data_sources. Если вы ещё не прошли этот этап — логичнее сначала обновиться до 2025-09-03, а потом уже идти на 2026-03-11.

Направление развития API очевидно: следующая версия 2026-04-01 уже вышла и принесла Views API, smart-фильтры и улучшения webhooks. Чем дольше вы сидите на старой версии — тем больше легаси накопится.

Антипаттерны

• ❌ Обновлять SDK без явной фиксации версии в коде — получите сюрпризы в проде.
• ❌ Делать миграцию на яблоке февраля в пятницу вечером. Чеклист короткий, но тесты всё равно нужны.
• ❌ Оставлять archived: false в дефолтных сериализаторах «на всякий случай» — API вернёт 400.
• ❌ Проверять наличие блока расшифровки только по строке transcription — новые встречи появятся как meeting_notes и окажутся невидимыми.
• ❌ Смешивать Notion-Version между разными вызовами внутри одного пайплайна. Держите одну версию на всю интеграцию.

Ссылки

• Upgrade guide от Notion: developers.notion.com/guides/get-started/upgrade-guide-2026-03-11
• Changes by version: developers.notion.com/reference/changes-by-version
• Changelog Notion API: developers.notion.com/page/changelog
• Append block children (с новым position): developers.notion.com/reference/patch-block-children
• Блок meeting_notes: developers.notion.com/reference/block
• Versioning: developers.notion.com/reference/versioning
• SDK @notionhq/client v5.12.0: github.com/makenotion/notion-sdk-js/releases/tag/v5.12.0

По теме

• Статья: Plaud × Notion: как мы построили устойчивый конвейер транскриптов через «серый» API
• Блог: Notion MCP теперь умеет работать с записями встреч
• База знаний: Notion как Headless CMS: контент-движок для сайта

Если у вас собственный контур на Notion API — контент-пайплайн, выгрузки в CMS или интеграция с ИИ-агентами, эти три breaking changes легко уронят прод, если пропустить обновление. Если интересно разобрать миграцию на вашей инфраструктуре или подумать над архитектурой под следующие версии API — напишите, обсудим.

📢 Telegram-канал: t.me/pimenov_ru · ✉️ Личка: t.me/pimenov