Updating a widget

Use this request to update widget parameters.

PATCH

https://api.tracker.yandex.net/v3/widgets/{widget_id}?version=WIDGET_VERSION

Query format

Before making a request, get permission to access the API.

To update a widget, use an HTTP PATCH request. In the request body, specify the parameters in JSON format.

PATCH /v3/widgets/{widget_id}?version=WIDGET_VERSION
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: ORGANIZATION_ID

{
    "type": "filter",
    "description": "WIDGET_NAME",
    "perPage": 20,
    "fields": ["summary"],
    "filterParams": {
        "filter": {
            "author": "me()"
        }
    }
}

Headers

Host: address of the node that provides the API.
Authorization: Authorization token about these formats:
- OAuth OAUTH_TOKEN: For authorization using the OAuth 2.0 protocol. Learn more
- Bearer IAM_TOKEN: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. Learn more
ID types

X-Org-ID or X-Cloud-Org-ID: Organization ID.
- Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.
- Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Identity Hub.
Finding the ID

To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

Resource

Parameter	Description	Data type
widget_id	Widget ID.	Number

Request parameters

Required parameters

Parameter	Description	Data type
version	Current widget version. Pass the version received in the response to the Getting a widget or Creating a widget request. Each change to the widget increases the version number.	Number

Request body parameters

Pass type and only the fields to update. Omitted fields retain their current values. The tables below describe fields for each type; required fields are indicated for widget creation.

Parameter	Description	Data type
type	Widget type. Must match the type of the widget being updated; otherwise, the API returns `404`. Possible values: `info`: the "Useful links" widget. `security`: a security widget. `filter`: the "Issues" widget. `created-vs-resolved`: the "Created/Resolved" chart. `issues`: the "Issue statistics" widget. `table-sum`: the "Summary table with totals" widget. `table`: the "Summary table" widget. `time-since`: the "Event chart" widget. `note`: a note widget. `invite-links`: an invitation links widget. `orgAdmin`: the "Information for employees" widget. `burndown-chart`: a burndown chart. `cycle-time`: a cycle time chart. `flow`: a flow chart. `velocity`: a velocity chart. `goalFilter`: the "Goals" widget. `projectPortfolioFilter`: the "Projects and portfolios" widget.	String
description	Widget name. Required for creation and import.	String
color	Widget color. Optional.	Number
refresh	Widget refresh interval. Optional.	Number

Widget type parameters

Use the fields for the selected type. The fields in the second column are required for creation and import.

Widget type	Required parameters	Optional parameters
`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`

Parameter	Description
subtype	Useful links subtype: `links`, `presets`, or `test_drive`.
fields	Fields to display. For issue widgets, see the array description.
perPage	Number of items per widget page.
queues	Queues for the security widget.
filterParams	Issue filtering parameters. See the object description.
field	Grouping field.
fieldX, fieldY	Table axis fields. `fieldY` must differ from `fieldX`.
rowField, columnField	Row and column fields. `columnField` must differ from `rowField`.
sumField	Field to sum.
initialRowsLimit	Initial row count: from 1 to 200.
showSum, showTotals	Display the sum and totals.
orderBySum, orderAsc	Sort by sum and in ascending order.
rowOrderAsc, columnOrderAsc	Sort rows and columns in ascending order.
groupBy	Grouping: `hour`, `day`, `week`, `month`, `quarter`, or `year`.
daysCount	Grouping period. Default: 30. The maximum depends on `groupBy`: `hour`: 10, `day`: 300, `week`: 1750, other values: 3500.
cumulative	Cumulative chart mode.
unresolvedIssuesTrend	Display the trend for unresolved issues.
versions	Versions for the Created/Resolved chart: `all`, `main`, or `none`.

Additional types for creation and update

These types are available in widget creation and update requests. Import does not support them.

Widget type	Required parameters	Optional parameters
`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`

The invite-links and orgAdmin widgets use only the common parameters description, color, and refresh.

For goalFilter, fields specifies goal fields; for projectPortfolioFilter, it specifies project and portfolio fields. perPage accepts values from 1 to 50.

For flow and velocity, pass only one issue source: filter, query, or filterId.

Parameter	Description
text, markupType	Note text and markup format: `md` or `plain`.
sprintId, withHolidays	Sprint ID and whether to account for non-working days.
filterFieldsOrder	Filter field order.
filter, query, filterId	Issue source: a filter, a query string, or a saved filter ID.
fromStatuses, toStatuses, excludedStatuses, includedStatuses, forStatus	Status parameters for the cycle time chart.
calendar	Calendar for chart calculations.
autoUpdatable	Automatic chart updates.
targetY	Target value for the cycle time chart.
fullView	Full flow chart view.
bucket	Grouping interval: `{"type": "days", "count": 1}`. Use `weeks` or `months` instead of `days` if needed. To group by sprint: `{"type": "sprints", "board": 123}`. Default: `{"type": "days", "count": 1}`.
start, end	Chart period boundaries: a date or an expression such as `now() - 3d`. `start` must not be later than `end`. Here, `start` is the chart period start; in import requests, `start` is the widget creation date.
lines	A `cycle-time` line settings object: Boolean `movingAverage` and `standardDeviation`, an array of numbers `percentile`, and a number `cakePercentile`.
statusColors	An array of status colors for `flow`, such as `[{"status": "open", "color": "#00AA00"}]`.
calculationSettings	Velocity calculation settings object. Supported `type` values are listed below.

Fields of the calculationSettings object

type value	Parameters
`byCompletedTasks`	`toStatuses`
`byWorklog`	`toStatuses`
`byStatuses`	`statuses`, `calendar`
`byNumericField`	`valueField`, `toStatuses`, `strategy`

For byStatuses, calendar is required. For byNumericField, valueField is required: an integer, long, float, or worklog duration field. strategy is an object with type set to byValueChangingSmooth or byValueChangingPrecise, and a Boolean byValueIncreasing.

planCalculationSettings set to {"type": "byOriginalValue"} inside calculationSettings is supported only for byCompletedTasks and byNumericField with a sprints bucket. For byNumericField, it is incompatible with "byValueIncreasing": true.

Elements of the fields array

The fields parameter specifies the issue fields displayed in the widget. Each array element is an issue field key. For example, ["summary"] displays only the issue summary column in the widget.

Examples of standard issue field keys:

Parameter	Description
key	Issue key.
summary	Issue summary.
status	Issue status.
assignee	Assignee.
priority	Priority.
created	Issue creation date.
updated	Issue update date.

The full list of issue fields is available in the Tracker interface under Administration → Fields (https://tracker.yandex.com/admin/fields). You can also get the list using the API: GET /v3/fields.

Object fields filterParams

Parameter	Description	Data type
filter	Filter issues by parameters in the `{"FIELD": "VALUE"}` format.	Object
query	Issue filter in the query language.	String

If both filter and query are specified in the request body, query (the query language) takes precedence as the issue source.

Response format

Request executed successfully

Request failed

If the request is successful, the API returns a response with code 200 OK.

The response body contains a JSON object with the updated widget parameters.

The fields depend on the widget type. The example below shows a filter widget. Layout fields are returned only by the Getting a widget request.

{
    "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": "New dashboard"
    },
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/8000000000000007",
        "id": "11********",
        "display": "User Name",
        "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": "Issue",
            "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": "System"
            },
            "type": "standard"
        }
    ],
    "perPage": 20,
    "filterParams": {
        "filter": {
            "author": "me()"
        }
    }
}

Response parameters

Parameter	Description	Data type
id	Widget ID.	Number
version	Widget version. Each change to the widget increases the version number.	Number
type	Widget type.	String
self	URL of the API resource containing widget parameters.	String
dashboard	Object with information about the dashboard containing the widget.	Object
createdBy	Object with information about the widget creator.	Object
description	Widget name.	String
text	Note text. Returned for `note` widgets.	String
color	Service parameter.	Number
createdAt	Date and time when the widget was created, in the `YYYY-MM-DDThh:mm:ss.sss±hhmm` format.	String
fields	Array of objects with information about the issue fields displayed in the widget.	Array of objects
perPage	Number of issues per widget page.	Number
filterParams	Issue filtering parameters for the widget.	Object

Fields of objects in the fromStatuses and toStatuses arrays

Parameter	Description	Data type
self	Address of the API resource with information about the status.	String
id	Status ID.	String
key	Status key.	String
display	Status name displayed.	String

Object fields dashboard

Parameter	Description	Data type
self	URL of the API resource containing dashboard parameters.	String
id	Dashboard ID.	String
display	Dashboard name.	String

Object fields createdBy

Parameter	Description	Data type
self	Address of the API resource with information about the user	String
id	User ID.	String
display	Displayed user name	String
passportUid	Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID.	Number
cloudUid	Unique user ID in Yandex Identity Hub	String

Fields of elements in the fields array

Parameter	Description	Data type
self	URL of the API resource containing field parameters.	String
id	Field ID.	String
name	Field name.	String
key	Field key.	String
version	Field version.	Number
schema	Field schema.	Object
readonly	Indicates that the field is read-only.	Boolean
options	Indicates that the field has a fixed set of values.	Boolean
suggest	Indicates that suggestions are available for the field.	Boolean
queryProvider	Field query provider.	Object
order	Field display order.	Number
category	Field category.	Object
type	Field type.	String

Object fields schema

Parameter	Description	Data type
type	Field data type.	String
required	Indicates that the field is required.	Boolean

Object fields queryProvider

Parameter	Description	Data type
type	Query provider type.	String

Object fields category

Parameter	Description	Data type
self	URL of the API resource containing category parameters.	String
id	Category ID.	String
display	Category name.	String

Object fields filterParams

Parameter	Description	Data type
filter	Issue filter by parameters.	Object
query	Issue query, if specified.	String

If the request is processed incorrectly, the API returns a response with an error code:

400: One or more request parameters have an invalid value.

403: You are not authorized to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.

404: The requested object was not found. You may have specified an invalid object ID or key.

409: There was a conflict when editing the object. The error may be due to an invalid update version.

412: A conflict occurred while editing the object. The error may be due to an invalid update version.

422: JSON validation error, the request is rejected.

500: Internal service error. Try again later.

503: The API service is temporarily unavailable.

Was the article helpful?

Get a widget

Import a widget

Updating a widget

Query format

ID types

Finding the ID

Response format

Was the article helpful?