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

Notion API 2026-03-11 — версия API, которую интеграция подключает явно через заголовок или настройку SDK. При переходе меняются способ позиционирования блоков, признак нахождения в корзине и тип блока с заметками о встречах. Проверьте код по всем трём изменениям.

Содержание

1. Подключение версии 2026-03-11 — заголовок REST-запроса и настройка SDK
2. Три изменения при миграции — поля и типы, которые нужно обновить
3. Чеклист обновления интеграции — порядок проверки
4. Полезные сценарии — миграция и чтение старых экспортов
5. Проверка результата — наблюдаемые признаки корректной работы
6. Неочевидные ловушки — сериализация и вебхуки
7. Изменения API после релиза — актуальные возможности и ограничения
8. Официальные источники

Подключение версии 2026-03-11

Версия включается явно заголовком в REST-запросе:

Notion-Version: 2026-03-11

В официальном JavaScript/TypeScript SDK версия задаётся при создании клиента:

import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_ACCESS_TOKEN,
  notionVersion: "2026-03-11",
});

Минимальная версия @notionhq/client с поддержкой API 2026-03-11 — 5.12.0. SDK сохраняет старые поля и типы с пометкой @deprecated, поэтому само обновление библиотеки не включает новую версию API. Переход происходит после явной установки notionVersion или заголовка Notion-Version.

Три изменения при миграции

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

Вставка блоков через position

Эндпоинт Append block children в версии 2026-03-11 не принимает плоский параметр after.

Было:

{
  "children": [],
  "after": "a1c2d3e4-..."
}

Стало:

{
  "children": [],
  "position": {
    "type": "after_block",
    "after_block": {
      "id": "a1c2d3e4-..."
    }
  }
}

Объект position поддерживает три режима:

• { "type": "start" } — вставить блоки в начало родителя;
• { "type": "end" } — вставить в конец;
• { "type": "after_block", "after_block": { "id": "<block_id>" } } — вставить после указанного блока.

Если position не передан, блоки добавляются в конец.

Замена archived на in_trash

В REST API 2026-03-11 поле archived заменено на in_trash в запросах и ответах для страниц, баз данных, блоков и источников данных (data sources).

Было:

{
  "archived": true
}

Стало:

{
  "in_trash": true
}

Обновить нужно обе стороны интеграции:

• тела запросов, меняющих статус корзины;
• типы и модели данных;
• проверки ответов вида obj.archived;
• сериализаторы, автоматически добавляющие archived: false.

Замена transcription на meeting_notes

Имя типа блока и вложенного поля изменилось одновременно.

Было:

{
  "type": "transcription",
  "transcription": {
    "rich_text": []
  }
}

Стало:

{
  "type": "meeting_notes",
  "meeting_notes": {
    "rich_text": []
  }
}

Проверьте обход блоков, фильтры по типу и выгрузку встреч во внешние системы. Утверждение, что meeting_notes доступен только для чтения, больше нельзя считать актуальным: в официальном changelog от 5 августа 2026 года указано, что @notionhq/client v5.24.0 добавляет метод client.blocks.meetingNotes.create() для создания заметки о встрече.

Для выборки заметок о встречах также доступен эндпоинт POST /v1/blocks/meeting_notes/query; его типизированная поддержка появилась в SDK v5.21.0.

Чеклист обновления интеграции

Полезные сценарии

Миграция контент-пайплайна

Исходное условие: интеграция добавляет блоки, читает ответы страниц и обрабатывает заметки о встречах.

Сначала обновите модели и запросы, затем прогоните один тестовый документ с тремя проверками: вставка после заданного блока, исключение объекта с in_trash: true и обнаружение блока meeting_notes. Ожидаемый результат — все три операции проходят без ошибки валидации и без потери сущностей при фильтрации.

Сценарий проверяет REST-код, но не подтверждает корректность обработчиков вебхуков: их нужно тестировать отдельно.

Чтение старых экспортов после перехода

Если в логах, резервных копиях или хранилище аналитики остались ответы старой версии, добавьте слой совместимости на чтение:

const inTrash = object.in_trash ?? object.archived ?? false;
const meetingNotes = object.meeting_notes ?? object.transcription;

Новые запросы при этом должны отправлять только поля версии 2026-03-11. Результат можно проверить на двух фикстурах: сохранённом ответе 2025-09-03 и новом ответе 2026-03-11.

Проверка результата

Минимальная проверка миграции должна подтвердить:

1. Запрос с position.type = "after_block" вставляет блок в ожидаемое место.
2. Ответы содержат in_trash, а код не зависит от archived.
3. Блок meeting_notes распознаётся и не пропускается фильтром типов.
4. В исходящих REST-запросах нет устаревших полей.
5. Все запросы пайплайна используют одну версию API.

Проверяйте не только код ответа HTTP. Сравните порядок блоков, состав обработанных сущностей и результат синхронизации во внешнем хранилище.

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

Поля по умолчанию в обёртках

Если локальная модель по умолчанию добавляет archived: false, запрос на 2026-03-11 может содержать устаревшее поле и завершиться ошибкой валидации. Проверяйте фактическое тело запроса и исключите это поле из сериализации.

Сохранённые исторические данные

Старые JSON-ответы не изменятся после переключения API. Для них нужен миграционный скрипт или совместимый читатель, понимающий оба формата.

Вебхуки

Для вебхуков подключения (connection webhooks) переход подписки с 2025-09-03 на 2026-03-11 ничего не меняет: официальный upgrade guide указывает, что события вебхуков этих версий идентичны. Замена archived на in_trash относится к телам запросов и ответов REST API, а не к событиям вебхуков.

Вебхуки автоматизаций баз данных (database automation webhooks) версионируются отдельно. Старые действия можно оставить на 2025-09-03 или обновить в редакторе автоматизации; новые действия по умолчанию используют 2026-03-11.

Сторонние библиотеки

Способность библиотеки передать новый заголовок не гарантирует поддержку новых типов. До переключения проверьте её changelog, модели запросов и сериализацию ответов.

Изменения API после релиза

Номер версии после 2026-03-11 не менялся, но Notion добавлял обратно совместимые возможности и ограничения. На 8 сентября 2026 года для интеграций особенно заметны:

• API представлений (Views API), работающий с API 2025-09-03 и новее;
• максимальная глубина пагинации в эндпоинтах Query a data source, Create a view query и Get view query results — 10 000 результатов на один запрос. При достижении лимита ответ содержит request_status;
• фильтры с несколькими значениями для select, status и multi_select;
• запрос и создание заметок о встречах;
• HTML-блоки через File Upload API и embed-блок;
• дополнительное ограничение частоты на уровне рабочего пространства, действующее вместе с лимитом на подключение;
• URL страниц, баз данных и источников данных в ответах API на домене app.notion.com. Это ссылки для открытия, а не стабильные идентификаторы;
• применение лимита блоков бесплатного рабочего пространства к REST API с 1 сентября 2026 года для internal connections и OAuth connections, ограниченных выбранными рабочими пространствами.

При больших выборках проверяйте request_status, сужайте запрос фильтрами, разделяйте обработку на окна или используйте вебхуки для инкрементальной синхронизации. Обычная пагинация сама по себе может не охватить строки после лимита 10 000.

Официальные источники

• Upgrade guide для API 2026-03-11
• Работа с Views API
• Changelog Notion API
• Append block children

Следующий шаг

Если Notion используется как источник контента для сайта, продолжите с руководства Notion как Headless CMS: контент-движок для сайта.

Связанные материалы

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

Если вы обновляете собственный контент-пайплайн или интеграцию с ИИ-агентами, отдельно проверьте совместимость моделей, сериализаторов и тестовых данных.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov