Updating a dashboard

Use this request to update dashboard parameters and widget positions.

PATCH

https://api.tracker.yandex.net/v3/dashboards/{dashboard_ID}?version=DASHBOARD_VERSION

Request format

Before making a request, get permission to access the API. Get the version from the Getting a dashboard response.

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

{
  "name": "Team plans",
  "widgets": {
    "set": [
      {
        "id": 456,
        "column": 1,
        "row": 1,
        "collapsed": false,
        "coords": {"x": 0, "y": 0, "w": 6, "h": 8},
        "order": 1
      }
    ]
  }
}
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

dashboard_ID

Dashboard ID.

Number
Request parameters

Required parameters

Parameter

Description

Data type

version

Current dashboard version from the Getting a dashboard response.

Number
Request body parameters

Pass the dashboard parameters you want to change.

Parameter

Description

Data type

name

New dashboard name.

String

widgets

Operation on the widget collection.

Object

Fields of the widgets object

Parameter

Description

Data type

add

Adds existing widgets of this dashboard to the layout.

Array of objects

set

Replaces the entire widget set. Widgets omitted from the new set are deleted.

Array of objects

remove

Deletes the specified widgets from the dashboard. Deleted widgets are no longer accessible through the API.

Array of objects

replace

Replaces widget parameters. Each element contains target and replacement objects.

Array of objects

A dashboard can contain up to 100 widgets. Pass column and row together, and coords and order together. Column and row numbering starts at 1. The maximum column value depends on the layout: one-column: 1, two-columns: 2, three-columns: 3, narrow-left-wide-right: 2, one-top-two-bottom: 3. The coords grid is 36 units wide.

Fields of the widgets.add array elements

The id, column, and row fields are required.

Parameter

Description

Data type

id

Widget ID.

Number

column

Column number.

Number

row

Row number.

Number

collapsed

Indicates a collapsed widget.

Boolean

coords

Widget coordinates and size.

Object

order

Widget order.

Number

Fields of the widgets.remove array elements

Parameter

Description

Data type

id

Widget ID.

Number

Fields of the widgets.replace array elements

Parameter

Description

Data type

target

Widget whose parameters should be replaced. Pass an object with the id field.

Object

replacement

New widget layout parameters. The fields are the same as in widgets.set elements.

Object

Fields of the widgets.set array elements

Parameter

Description

Data type

id

Widget ID.

Number

column

Column number.

Number

row

Row number.

Number

collapsed

Indicates a collapsed widget.

Boolean

coords

Widget coordinates and size.

Object

order

Widget order.

Number

Fields of the coords object

Parameter

Description

Data type

x

Horizontal coordinate.

Number

y

Vertical coordinate.

Number

w

Width.

Number

h

Height.

Number

Response format

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

On success, the API returns the updated dashboard object.

{
  "id": 123,
  "self": "https://api.tracker.yandex.net/v3/dashboards/123",
  "version": 4,
  "name": "Team plans",
  "layout": "one-column",
  "widgets": [
    {"id": "456", "self": "https://api.tracker.yandex.net/v3/widgets/456"}
  ]
}
Response parameters

Parameter

Description

Data type

id

Dashboard ID.

Number

self

URL of the API resource with dashboard parameters.

String

version

Dashboard version. Get it from the getting a dashboard response.

Number

name

Dashboard name.

String

createdBy

Dashboard creator. User object fields.

Object

createdAt

Dashboard creation date and time.

String

layout

Widget display mode.

String

widgets

Dashboard widget references.

Array of objects

temp

Indicates a temporary dashboard.

Boolean

owner

Dashboard owner. User object fields.

Object

Fields of the widgets array elements

Parameter

Description

Data type

id

Widget ID.

String

self

URL of the API resource with widget parameters.

String

display

Widget name.

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.

Required version parameter is missing.

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.

No WRITE permission for the dashboard.

404
The requested object was not found. You may have specified an invalid object ID or key.
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.

The widgets parameter references a widget that does not exist.

Previous
Get a dashboard
Next
Get dashboard permissions