Создать виджет

Запрос позволяет добавить виджет на уже существующем дашборде.

Чтобы разместить виджет на дашборде, добавьте его через параметр widgets.add запроса Обновить дашборд. До этого виджет не виден на дашборде и не возвращается в поле widgets запроса Получить дашборд.

POST

https://api.tracker.yandex.net/v3/dashboards/{id_дашборда}/widgets

Формат запроса

Перед выполнением запроса получите доступ к API.

Чтобы создать виджет, используйте HTTP-запрос с методом POST. В теле запроса укажите параметры в формате JSON.

POST /v3/dashboards/{id_дашборда}/widgets
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID или X-Cloud-Org-ID: ИДЕНТИФИКАТОР_ОРГАНИЗАЦИИ

{
    "type": "filter",
    "description": "НАЗВАНИЕ_ВИДЖЕТА",
    "perPage": 10,
    "fields": ["summary"],
    "filterParams": {
        "filter": {
            "author": "me()"
        }
    }
}

Заголовки

Host: адрес узла, предоставляющего API.
Authorization: токен для авторизации в одном из форматов:
- OAuth OAUTH_TOKEN при авторизации по протоколу OAuth 2.0. Читать подробнее
- Bearer IAM_TOKEN при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Identity Hub. Читать подробнее
Content-Type: формат тела запроса. Должен иметь значение application/json.
X-Org-ID или X-Cloud-Org-ID: идентификатор организации.
- если к Трекеру привязана организация Яндекс 360 для бизнеса, используйте заголовок X-Org-ID,
- если к Трекеру привязана организация Yandex Identity Hub, используйте заголовок X-Cloud-Org-ID.
Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.

Ресурс

Параметр	Описание	Тип данных
id_дашборда	Идентификатор дашборда.	Число

Параметры тела запроса

Укажите type и параметры выбранного типа виджета.

Параметр	Описание	Тип данных
type	Тип виджета. Допустимые значения: `info` — виджет «Полезные ссылки»; `security` — виджет безопасности; `filter` — виджет «Задачи»; `created-vs-resolved` — график «Создано/Решено»; `issues` — виджет «Статистика по задачам»; `table-sum` — виджет «Сводная таблица с суммой»; `table` — виджет «Сводная таблица»; `time-since` — виджет «График событий»; `note` — заметка; `invite-links` — ссылки-приглашения; `orgAdmin` — виджет «Информация для сотрудников»; `burndown-chart` — диаграмма сгорания; `cycle-time` — диаграмма времени цикла; `flow` — диаграмма потока; `velocity` — диаграмма скорости; `goalFilter` — виджет «Цели»; `projectPortfolioFilter` — виджет «Проекты и портфели».	Строка
description	Название виджета. Обязателен при создании и импорте.	Строка
color	Цвет виджета. Необязательный параметр.	Число
refresh	Период обновления виджета. Необязательный параметр.	Число

Параметры типов виджетов

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

Тип виджета	Обязательные параметры	Необязательные параметры
`info`	`subtype`: `links`, `presets`, `test_drive`	—
`security`	`fields`, `perPage`	`queues`
`filter`	`fields`, `perPage`, `filterParams`	—
`created-vs-resolved`	`filterParams`	`groupBy`, `daysCount`, `cumulative`, `unresolvedIssuesTrend`, `versions`: `all`, `main`, `none`
`issues`	`filterParams`, `field`, `perPage`	`orderBySum`, `orderAsc`
`table`	`filterParams`, `fieldX`, `fieldY`, `perPage`	`showSum`, `orderBySum`, `orderAsc`
`table-sum`	`filterParams`, `rowField`, `columnField`, `sumField`, `initialRowsLimit`	`showTotals`, `rowOrderAsc`, `columnOrderAsc`
`time-since`	`filterParams`, `field`	`groupBy`, `daysCount`, `cumulative`

Параметр	Описание
subtype	Подтип полезных ссылок: `links`, `presets` или `test_drive`.
fields	Отображаемые поля. Для виджетов задач см. описание массива.
perPage	Число элементов на странице виджета.
queues	Очереди виджета безопасности.
filterParams	Параметры фильтрации задач. См. описание объекта.
field	Поле группировки.
fieldX, fieldY	Поля осей таблицы. `fieldY` должно отличаться от `fieldX`.
rowField, columnField	Поля строк и столбцов. `columnField` должно отличаться от `rowField`.
sumField	Поле для расчета суммы.
initialRowsLimit	Начальное число строк: от 1 до 200.
showSum, showTotals	Отображение суммы и итогов.
orderBySum, orderAsc	Сортировка по сумме и по возрастанию.
rowOrderAsc, columnOrderAsc	Сортировка строк и столбцов по возрастанию.
groupBy	Группировка: `hour`, `day`, `week`, `month`, `quarter`, `year`.
daysCount	Период группировки. По умолчанию — 30. Максимум зависит от `groupBy`: `hour` — 10, `day` — 300, `week` — 1750, остальные — 3500.
cumulative	Накопительный режим графика.
unresolvedIssuesTrend	Отображение динамики нерешенных задач.
versions	Версии для графика «Создано/Решено»: `all`, `main`, `none`.

Дополнительные типы для создания и изменения

Эти типы доступны в запросах создания и изменения виджета. Импорт их не поддерживает.

Тип виджета	Обязательные параметры	Необязательные параметры
`note`	`text`, `markupType`: `md`, `plain`	—
`burndown-chart`	`sprintId`, `withHolidays`	—
`goalFilter`	—	`filter`, `filterFieldsOrder`, `fields`, `perPage`
`projectPortfolioFilter`	—	`filter`, `filterFieldsOrder`, `fields`, `perPage`
`cycle-time`	—	`filter`, `query`, `filterId`, `fromStatuses`, `toStatuses`, `excludedStatuses`, `includedStatuses`, `forStatus`, `bucket`, `calendar`, `lines`, `mode`: `common-lines`, `common-lines-and-points`, `status-lines`, `autoUpdatable`, `start`, `end`, `targetY`
`flow`	—	`filter`, `query`, `filterId`, `bucket`, `showIssues`: `SHOW_ALL`, `HIDE`, `fullView`, `mode`: `precise`, `smooth`, `statusColors`, `autoUpdatable`, `start`, `end`
`velocity`	`calculationSettings`	`filter`, `query`, `filterId`, `bucket`, `autoUpdatable`, `start`, `end`

Виджеты invite-links и orgAdmin используют только общие параметры description, color и refresh.

Для goalFilter параметр fields задает поля целей, для projectPortfolioFilter — поля проектов и портфелей. perPage принимает значения от 1 до 50.

Для flow и velocity передайте только один источник задач: filter, query или filterId.

Параметр	Описание
text, markupType	Текст заметки и формат разметки: `md` или `plain`.
sprintId, withHolidays	Идентификатор спринта и признак учета нерабочих дней.
filterFieldsOrder	Порядок полей фильтра.
filter, query, filterId	Источник задач: фильтр, строка запроса или идентификатор сохраненного фильтра.
fromStatuses, toStatuses, excludedStatuses, includedStatuses, forStatus	Параметры статусов диаграммы времени цикла.
calendar	Календарь для расчета диаграммы.
autoUpdatable	Автоматическое обновление диаграммы.
targetY	Целевое значение диаграммы времени цикла.
fullView	Полный вид диаграммы потока.
bucket	Шаг группировки: `{"type": "days", "count": 1}`. Вместо `days` можно передать `weeks` или `months`. Для группировки по спринтам: `{"type": "sprints", "board": 123}`. По умолчанию: `{"type": "days", "count": 1}`.
start, end	Границы периода диаграммы: дата или выражение, например `now() - 3d`. `start` не может быть позже `end`. Здесь `start` задает начало периода диаграммы; в запросе импорта `start` задает дату создания виджета.
lines	Объект настроек линий `cycle-time`: логические `movingAverage` и `standardDeviation`, массив чисел `percentile` и число `cakePercentile`.
statusColors	Массив цветов статусов для `flow`, например `[{"status": "open", "color": "#00AA00"}]`.
calculationSettings	Объект настроек расчета скорости. Допустимые значения `type` перечислены ниже.

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

Значение type	Параметры
`byCompletedTasks`	`toStatuses`
`byWorklog`	`toStatuses`
`byStatuses`	`statuses`, `calendar`
`byNumericField`	`valueField`, `toStatuses`, `strategy`

Для byStatuses параметр calendar обязателен. Для byNumericField обязателен valueField: поле типа integer, long, float или длительность учета времени. strategy — объект с type: byValueChangingSmooth или byValueChangingPrecise, и логическим byValueIncreasing.

planCalculationSettings со значением {"type": "byOriginalValue"} внутри calculationSettings допустим только для byCompletedTasks и byNumericField с bucket типа sprints. Для byNumericField этот параметр несовместим с "byValueIncreasing": true.

Элементы массива fields

Параметр fields определяет, какие поля задач будут отображаться в виджете. Каждый элемент массива — ключ поля задачи. Например, ["summary"] — в виджете будет отображаться только колонка с названием задачи.

Примеры ключей стандартных полей задач:

Параметр	Описание
key	Ключ задачи.
summary	Название задачи.
status	Статус задачи.
assignee	Исполнитель задачи.
priority	Приоритет задачи.
created	Дата создания задачи.
updated	Дата обновления задачи.

Полный список полей задачи доступен в интерфейсе Трекера на странице Администрирование → Поля (https://tracker.yandex.ru/admin/fields). Список полей также можно получить через API — запрос GET /v3/fields.

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

Параметр	Описание	Тип данных
filter	Фильтр задач по параметрам в формате `{"ПОЛЕ": "ЗНАЧЕНИЕ"}`.	Объект
query	Фильтр задач на языке запросов.	Строка

Если в теле запроса одновременно указаны параметры filter и query, приоритетным источником задач будет query (язык запросов).

Формат ответа

Запрос выполнен успешно

Запрос выполнен с ошибкой

В случае успешного выполнения запроса API возвращает ответ с кодом 200 OK.

Тело ответа содержит JSON-объект с параметрами нового виджета.

Набор полей зависит от типа виджета. Ниже приведен пример ответа для filter. Поля раскладки возвращает только запрос Получить виджет.

{
    "id": 123456,
    "version": 1,
    "type": "filter",
    "self": "https://api.tracker.yandex.net/v3/widgets/123456",
    "dashboard": {
        "self": "https://api.tracker.yandex.net/v3/dashboards/18",
        "id": "18",
        "display": "Новый дашборд"
    },
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "Имя Фамилия",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 1100000000000000
    },
    "description": "new desc",
    "color": 0,
    "createdAt": "2026-08-27T10:34:30.363+0000",
    "fields": [
        {
            "self": "https://api.tracker.yandex.net/v3/fields/summary",
            "id": "summary",
            "name": "Задача",
            "key": "summary",
            "version": 0,
            "schema": {
                "type": "string",
                "required": true
            },
            "readonly": false,
            "options": false,
            "suggest": false,
            "queryProvider": {
                "type": "SummaryQueryProvider"
            },
            "order": 6,
            "category": {
                "self": "https://api.tracker.yandex.net/v3/fields/categories/000000000000000000000001",
                "id": "000000000000000000000001",
                "display": "Системные"
            },
            "type": "standard"
        }
    ],
    "perPage": 10,
    "filterParams": {
        "filter": {
            "author": "me()"
        }
    }
}

Параметры ответа

Параметр	Описание	Тип данных
id	Идентификатор виджета.	Число
version	Версия виджета.	Число
type	Тип виджета.	Строка
self	Адрес ресурса API, который содержит параметры виджета.	Строка
dashboard	Объект с информацией о дашборде, на котором размещен виджет.	Объект
createdBy	Объект с информацией о создателе виджета.	Объект
description	Название виджета.	Строка
text	Текст заметки. Возвращается для виджета `note`.	Строка
color	Служебный параметр.	Число
createdAt	Дата и время создания виджета в формате `YYYY-MM-DDThh:mm:ss.sss±hhmm`.	Строка
fields	Массив объектов с информацией о полях задач, отображаемых в виджете.	Массив объектов
perPage	Количество задач на одной странице виджета.	Число
filterParams	Параметры фильтрации задач для виджета.	Объект

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит параметры дашборда.	Строка
id	Идентификатор дашборда.	Строка
display	Название дашборда.	Строка

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о пользователе.	Строка
id	Идентификатор пользователя.	Строка
display	Отображаемое имя пользователя.	Строка
passportUid	Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID.	Число
cloudUid	Уникальный идентификатор пользователя в Yandex Identity Hub.	Строка

Поля элементов массива fields

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит параметры поля.	Строка
id	Идентификатор поля.	Строка
name	Название поля.	Строка
key	Ключ поля.	Строка
version	Версия поля.	Число
schema	Схема поля.	Объект
readonly	Признак того, что поле доступно только для чтения.	Логический
options	Признак того, что поле имеет фиксированный набор значений.	Логический
suggest	Признак того, что для поля доступны подсказки.	Логический
queryProvider	Провайдер запросов для поля.	Объект
order	Порядок отображения поля.	Число
category	Категория поля.	Объект
type	Тип поля.	Строка

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

Параметр	Описание	Тип данных
type	Тип данных поля.	Строка
required	Признак того, что поле обязательно для заполнения.	Логический

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

Параметр	Описание	Тип данных
type	Тип провайдера запросов.	Строка

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит параметры категории.	Строка
id	Идентификатор категории.	Строка
display	Название категории.	Строка

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

Параметр	Описание	Тип данных
filter	Фильтр задач по параметрам.	Объект
query	Фильтр задач на языке запросов, если он задан.	Строка

Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:

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

403: У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.

404: Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.

422: Ошибка валидации JSON, запрос отклонен.

500: Внутренняя ошибка сервиса. Попробуйте повторно отправить запрос через некоторое время.

503: Сервис API временно недоступен.

Была ли статья полезна?

Изменить права доступа к дашборду

Получить виджет