## Формат запроса {#query}
Перед выполнением запроса [получите доступ к API](https://yandex.ru/support/tracker/ru/api/access.md).
Чтобы обновить виджет, используйте HTTP-запрос с методом `PATCH`. В теле запроса укажите параметры в формате JSON.
```json translate=no
PATCH /v3/widgets/{id_виджета}?version=WIDGET_VERSION
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID или X-Cloud-Org-ID: ИДЕНТИФИКАТОР_ОРГАНИЗАЦИИ
{
"type": "filter",
"description": "WIDGET_NAME",
"perPage": 20,
"fields": ["summary"],
"filterParams": {
"filter": {
"author": "me()"
}
}
}
```
{% cut "Заголовки" %}
* `Host`: адрес узла, предоставляющего API.
*
`Authorization`: токен для авторизации в одном из форматов:
- `OAuth OAUTH_TOKEN` при авторизации по протоколу OAuth 2.0. [Читать подробнее](https://yandex.ru/support/tracker/ru/api/access.md#about_OAuth)
- `Bearer IAM_TOKEN` при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Identity Hub. [Читать подробнее](https://yandex.ru/support/tracker/ru/api/access.md#iam-token)
*
`Content-Type`: формат тела запроса. Должен иметь значение `application/json`.
*
`X-Org-ID` или `X-Cloud-Org-ID`: идентификатор организации.
- если к Трекеру привязана организация Яндекс 360 для бизнеса, используйте заголовок `X-Org-ID`,
- если к Трекеру привязана организация Yandex Identity Hub, используйте заголовок `X-Cloud-Org-ID`.
Чтобы узнать идентификатор организации, перейдите на страницу **Администрирование** → [**Организации**](https://tracker.yandex.ru/admin/orgs) и скопируйте значение поля **идентификатор**.
{% endcut %}
{% cut "Ресурс" %}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| id_виджета | Идентификатор виджета. | Число ||
|#
{% endcut %}
{% cut "Параметры запроса" %}
**Обязательные параметры**
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| version | Текущая версия виджета. Передайте версию, полученную в ответе на запрос [Получить виджет](https://yandex.ru/support/tracker/ru/api/dashboards/get-widget.md) или [Создать виджет](https://yandex.ru/support/tracker/ru/api/dashboards/create-dashboard-widget.md). Каждое изменение виджета увеличивает номер версии. | Число ||
|#
{% endcut %}
{% cut "Параметры тела запроса" %}
Передайте `type` и только изменяемые поля. Непереданные поля сохраняют текущие значения. Таблицы ниже описывают поля каждого типа; обязательность указана для создания виджета.
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| type | Тип виджета. Должен совпадать с типом изменяемого виджета, иначе API вернет `404`. Допустимые значения:
`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 | Отображаемые поля. Для виджетов задач см. [описание массива](#fields). ||
|| perPage | Число элементов на странице виджета. ||
|| queues | Очереди виджета безопасности. ||
|| filterParams | Параметры фильтрации задач. См. [описание объекта](#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}
Параметр `fields` определяет, какие поля задач будут отображаться в виджете. Каждый элемент массива — ключ поля задачи. Например, `["summary"]` — в виджете будет отображаться только колонка с названием задачи.
Примеры ключей стандартных полей задач:
#|
|| **Параметр** | **Описание** ||
|| key | Ключ задачи. ||
|| summary | Название задачи. ||
|| status | Статус задачи. ||
|| assignee | Исполнитель задачи. ||
|| priority | Приоритет задачи. ||
|| created | Дата создания задачи. ||
|| updated | Дата обновления задачи. ||
|#
Полный список полей задачи доступен в интерфейсе Трекера на странице **Администрирование** → **Поля** (`https://tracker.yandex.ru/admin/fields`). Список полей также можно получить через API — запрос [`GET /v3/fields`](https://yandex.ru/support/tracker/ru/api/issues/get-issue-fields.md).
**Поля объекта** `filterParams` {#filterParams}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| filter | Фильтр задач по параметрам в формате `{"ПОЛЕ": "ЗНАЧЕНИЕ"}`. | Объект ||
|| query | Фильтр задач на [языке запросов](https://yandex.ru/support/tracker/user/query-filter.html). | Строка ||
|#
{% note info "" %}
Если в теле запроса одновременно указаны параметры `filter` и `query`, приоритетным источником задач будет `query` (язык запросов).
{% endnote %}
{% endcut %}
## Формат ответа {#answer}
{% list tabs %}
- Запрос выполнен успешно
В случае успешного выполнения запроса API возвращает ответ с кодом `200 OK`.
Тело ответа содержит JSON-объект с обновленными параметрами виджета.
Набор полей зависит от типа виджета. Ниже приведен пример ответа для `filter`. Поля раскладки возвращает только запрос [Получить виджет](https://yandex.ru/support/tracker/ru/api/dashboards/get-widget.md).
```json translate=no
{
"id": 123456,
"version": 2,
"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/8000000000000007",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 1100000000000000
},
"description": "new desc-2",
"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": 20,
"filterParams": {
"filter": {
"author": "me()"
}
}
}
```
{% cut "Параметры ответа" %}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| id | Идентификатор виджета. | Число ||
|| version | Версия виджета. Каждое изменение виджета увеличивает номер версии. | Число ||
|| type | Тип виджета. | Строка ||
|| self | Адрес ресурса API, который содержит параметры виджета. | Строка ||
|| [dashboard](#dashboard) | Объект с информацией о дашборде, на котором размещен виджет. | Объект ||
|| [createdBy](#user) | Объект с информацией о создателе виджета. | Объект ||
|| description | Название виджета. | Строка ||
|| text | Текст заметки. Возвращается для виджета `note`. | Строка ||
|| color | Служебный параметр. | Число ||
|| createdAt | Дата и время создания виджета в формате ```YYYY-MM-DDThh:mm:ss.sss±hhmm```. | Строка ||
|| [fields](#fields-answer) | Массив объектов с информацией о полях задач, отображаемых в виджете. | Массив объектов ||
|| perPage | Количество задач на одной странице виджета. | Число ||
|| [filterParams](#filterParams-answer) | Параметры фильтрации задач для виджета. | Объект ||
|#
**Поля объектов массивов** `fromStatuses` и `toStatuses` {#statuses}
Параметр | Описание | Тип данных
----- | ----- | -----
self | Адрес ресурса API, который содержит информацию о статусе. | Строка
id | Идентификатор статуса. | Строка
key | Ключ статуса. | Строка
display | Отображаемое название статуса. | Строка
**Поля объекта** `dashboard` {#dashboard}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| self | Адрес ресурса API, который содержит параметры дашборда. | Строка ||
|| id | Идентификатор дашборда. | Строка ||
|| display | Название дашборда. | Строка ||
|#
**Поля объекта** `createdBy` {#user}
Параметр | Описание | Тип данных
----- | ----- | -----
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка
id | Идентификатор пользователя. | Строка
display | Отображаемое имя пользователя. | Строка
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число
cloudUid | Уникальный идентификатор пользователя в Yandex Identity Hub. | Строка
**Поля элементов массива** `fields` {#fields-answer}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| self | Адрес ресурса API, который содержит параметры поля. | Строка ||
|| id | Идентификатор поля. | Строка ||
|| name | Название поля. | Строка ||
|| key | Ключ поля. | Строка ||
|| version | Версия поля. | Число ||
|| [schema](#schema) | Схема поля. | Объект ||
|| readonly | Признак того, что поле доступно только для чтения. | Логический ||
|| options | Признак того, что поле имеет фиксированный набор значений. | Логический ||
|| suggest | Признак того, что для поля доступны подсказки. | Логический ||
|| [queryProvider](#queryProvider) | Провайдер запросов для поля. | Объект ||
|| order | Порядок отображения поля. | Число ||
|| [category](#category) | Категория поля. | Объект ||
|| type | Тип поля. | Строка ||
|#
**Поля объекта** `schema` {#schema}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| type | Тип данных поля. | Строка ||
|| required | Признак того, что поле обязательно для заполнения. | Логический ||
|#
**Поля объекта** `queryProvider` {#queryProvider}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| type | Тип провайдера запросов. | Строка ||
|#
**Поля объекта** `category` {#category}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| self | Адрес ресурса API, который содержит параметры категории. | Строка ||
|| id | Идентификатор категории. | Строка ||
|| display | Название категории. | Строка ||
|#
**Поля объекта** `filterParams` {#filterParams-answer}
#|
|| **Параметр** | **Описание** | **Тип данных** ||
|| filter | Фильтр задач по параметрам. | Объект ||
|| query | Фильтр задач на языке запросов, если он задан. | Строка ||
|#
{% endcut %}
- Запрос выполнен с ошибкой
Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:
400
: Один или несколько параметров запроса имеют недопустимое значение.
403
: У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
404
: Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.
409
: При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.
412
: При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.
422
: Ошибка валидации JSON, запрос отклонен.
500
: Внутренняя ошибка сервиса. Попробуйте повторно отправить запрос через некоторое время.
503
: Сервис API временно недоступен.
{% endlist %}