Notion Views API — программное управление представлениями баз данных

Что это такое

Views API позволяет программно создавать, читать, настраивать и удалять представления баз данных в Notion. Он доступен начиная с версии API 2025-09-03 и поддерживает таблицы, доски, календари, таймлайны, галереи, списки, формы, графики, карты и дашборды.

Как устроены database, data source и view

Начиная с API 2025-09-03, контейнер базы и её данные разделены:

• База данных (database) — контейнер, в котором находятся источники данных и представления.
• Источник данных (data source) — схема свойств и страницы-строки.
• Представление (view) — способ показать страницы конкретного источника данных с собственными фильтрами, сортировками и конфигурацией.

Обычное представление относится ровно к одному источнику данных. Его parent указывает на базу данных. Исключение — дашборд: у самого дашборда data_source_id равен null, поскольку данные принадлежат размещённым в нём представлениям-виджетам.

При создании базы через API Notion автоматически добавляет один источник данных и табличное представление Default view.

Основные возможности и подключение по API

GET /v1/views — список представлений

Запрос принимает один из параметров:

• database_id — представления, принадлежащие указанной базе;
• data_source_id — все представления, ссылающиеся на указанный источник данных, включая связанные представления на других страницах рабочей области.

curl 'https://api.notion.com/v1/views?database_id=DATABASE_ID' -H 'Authorization: Bearer $NOTION_TOKEN' -H 'Notion-Version: 2026-03-11'

Ответ пагинирован и содержит только минимальные объекты-ссылки вида { "object": "view", "id": "..." }. Фильтры и конфигурацию каждого найденного представления нужно получать отдельным запросом.

GET /v1/views/{view_id} — полное представление

curl 'https://api.notion.com/v1/views/VIEW_ID' -H 'Authorization: Bearer $NOTION_TOKEN' -H 'Notion-Version: 2026-03-11'

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

POST /v1/views — создание представления

Для представления верхнего уровня в существующей базе передайте:

• database_id — базу, где появится вкладка;
• data_source_id — источник данных;
• name;
• type;
• при необходимости filter, sorts, quick_filters, configuration и position.

curl -X POST 'https://api.notion.com/v1/views' -H 'Authorization: Bearer $NOTION_TOKEN' -H 'Content-Type: application/json' -H 'Notion-Version: 2026-03-11' --data '{
  "database_id": "DATABASE_ID",
  "data_source_id": "DATA_SOURCE_ID",
  "name": "Последние заказы",
  "type": "table",
  "filter": {
    "property": "Дата заказа",
    "date": { "past_week": {} }
  },
  "sorts": [
    { "property": "Дата заказа", "direction": "descending" }
  ],
  "configuration": {
    "type": "table",
    "properties": [
      { "property_id": "title", "visible": true, "width": 300 }
    ],
    "wrap_cells": true
  }
}'

database_id и data_source_id — разные идентификаторы. Список источников находится в поле data_sources ответа GET /v1/databases/{database_id}.

При создании нужно передать ровно один из трёх вариантов размещения:

• database_id — новая вкладка существующей базы;
• view_id — виджет внутри представления-дашборда;
• create_database — связанное представление базы на указанной странице.

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

PATCH /v1/views/{view_id} — изменение настроек

PATCH обновляет только переданные поля. Через него можно изменить имя, фильтр, сортировки, быстрые фильтры и совместимую с типом представления configuration.

Чтобы очистить фильтр, сортировки или допускающее очистку поле конфигурации, передайте null. Тип внутри configuration должен совпадать с типом самого представления.

DELETE /v1/views/{view_id} — удаление

Удаление необратимо через API. База должна сохранять хотя бы одно представление, поэтому попытка удалить последнее завершится ошибкой validation_error.

Поля объекта view

{
  "object": "view",
  "id": "VIEW_ID",
  "parent": {
    "type": "database_id",
    "database_id": "DATABASE_ID"
  },
  "data_source_id": "DATA_SOURCE_ID",
  "name": "Задачи с высоким приоритетом",
  "type": "table",
  "filter": {
    "property": "Приоритет",
    "select": { "equals": "Высокий" }
  },
  "sorts": [
    { "property": "Дата", "direction": "descending" }
  ],
  "quick_filters": {
    "Статус": {
      "status": { "equals": "В работе" }
    }
  },
  "configuration": {
    "type": "table",
    "properties": [
      { "property_id": "title", "visible": true, "width": 300 }
    ],
    "wrap_cells": false,
    "frozen_column_index": 1
  }
}

Основные поля:

• filter использует ту же форму, что фильтры запросов к источнику данных, включая вложенные and и or;
• sorts — упорядоченный массив сортировок;
• quick_filters — фильтры, отображаемые в панели быстрых фильтров;
• configuration — настройки отображения, зависящие от типа представления;
• dashboard_view_id присутствует у виджетов, размещённых внутри дашборда.

Конфигурация разных типов представлений

Точный набор обязательных и допускающих null полей различается по типам. Перед формированием тела запроса сверяйте его с актуальной схемой в официальном руководстве.

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

Развёртывание стандартной рабочей базы

Задача: создать для новой команды вкладки «Мои задачи», «Текущий спринт», «Просрочено» и «На ревью».

Условие: известны идентификаторы базы и источника данных, а нужные свойства уже есть в его схеме.

Действие: отправьте несколько запросов POST /v1/views с нужными фильтрами, сортировками и конфигурацией.

Результат: созданные идентификаторы находятся в списке GET /v1/views?database_id=..., а полные настройки подтверждаются отдельным GET /v1/views/{view_id}.

Ограничение: фильтры и конфигурация должны ссылаться на свойства целевого источника данных.

Перенос рабочих представлений из другого сервиса

Задача: перенести из Asana, Linear или ClickUp не только строки, но и сохранённые выборки.

Действие: сопоставьте свойства исходной системы со свойствами Notion, затем создайте представления с соответствующими фильтрами, сортировками и типами отображения.

Результат: в Notion появляются представления, повторяющие рабочую логику исходного сервиса.

Ограничение: полного соответствия интерфейсов разных продуктов может не быть, поэтому результат нужно проверять для каждого типа представления.

Связанные представления и дашборды

Задача: собрать на одной странице отфильтрованные представления задач, проектов и ошибок из разных источников.

Действие: создайте связанное представление через create_database, а виджеты дашборда добавляйте отдельными запросами с view_id.

Результат: представления используют данные исходных источников, а дашборд объединяет виджеты в одном размещении.

Ограничение: интеграции нужен доступ к странице размещения и к базе, которой принадлежит источник данных.

Персональные представления

Задача: автоматически создавать сотруднику представление только с его задачами.

Действие: при добавлении сотрудника создайте представление с фильтром по свойству типа Person.

Результат: новое представление возвращается API, а запрос к нему содержит только страницы, соответствующие фильтру.

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

Аудит представлений

Задача: найти дублирующие и заброшенные представления.

Действие: получите список представлений по источнику данных, загрузите полные настройки и сравните фильтры, сортировки и конфигурацию.

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

Ограничение: удаление выполняется отдельным этапом после подтверждения, поскольку DELETE необратим через API.

Как проверить результат

После создания или обновления:

1. Выполните GET /v1/views/{view_id}.
2. Проверьте name, type, data_source_id, filter, sorts и configuration.
3. Для вкладки базы убедитесь, что её ID присутствует в GET /v1/views?database_id=....
4. Для связанного представления проверьте результат в списке по data_source_id с учётом прав интеграции.

Успешный HTTP-ответ сам по себе не подтверждает, что фильтр решает пользовательскую задачу. Для критичных представлений дополнительно проверьте набор отображаемых страниц в интерфейсе или через предусмотренный Views API механизм запросов к представлению.

Доступ и лимиты

• Views API требует Notion-Version: 2025-09-03 или новее. В примерах используется актуальная версия 2026-03-11.
• Для GET /v1/views/{view_id} подключению требуется возможность чтения содержимого (read content capability). Ответ 404 может означать как отсутствие представления, так и отсутствие доступа к нему.
• Интеграция получает только доступные ей представления. Связанные представления на недоступных страницах исключаются из списка.
• Лимит одного подключения задаётся на 60-секундное окно и зависит от тарифа: Business и Enterprise — 600 запросов в минуту, в среднем 10 в секунду; остальные тарифы — 180 запросов в минуту, в среднем 3 в секунду.
• Бюджет 60-секундного окна можно расходовать неравномерно, но после его исчерпания нужно ждать сброса окна. Для лимита подключения значение Retry-After не превышает 60 секунд.
• Дополнительно действует общий лимит рабочего пространства, разделяемый всеми подключениями и зависящий от тарифа. Его Retry-After может превышать минуту.
• При ответах 429 и 529 соблюдайте Retry-After, используйте ограниченное число повторов, экспоненциальную задержку и случайный разброс.
• Ошибки 500, 502, 503 и 504 безопасно повторять автоматически только для идемпотентных запросов, например GET и DELETE, либо при собственной защите от повторного выполнения.
• Очередь запросов помогает не исчерпать бюджет подключения одним пакетным заданием.

Данные о версиях и лимитах сверены 9 сентября 2026 года. Notion предупреждает, что лимиты могут меняться.

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

• Working with views
• Retrieve a view
• Upgrade guide на 2025-09-03
• Request limits
• Views, filters, sorts & groups в интерфейсе Notion

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

Если нужно объединить несколько представлений в одном рабочем экране, продолжите с руководством Notion Dashboards — комбинированные представления баз данных.

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

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