---
title: "Change one of your dashboards"
method: PATCH
path: "/api/v1/rest/bi/dashboards/{id}"
tags: ["Business Intelligence"]
---

# Change one of your dashboards

`PATCH /api/v1/rest/bi/dashboards/{id}`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/bi/dashboards/{id}`
- Auth: HTTP bearer

Changes one of YOUR OWN dashboards (mine: true in bi_list_dashboards), and only the change the person asked for. Send only what changes: `name`; `add_widgets` to append charts; or `widgets` for the COMPLETE new list — read the board with bi_get_dashboard first, keep each widget that stays with { keep_widget: "<its id>" } (plus any field to change on it, such as viz or range), and leave out the ones to remove; and the board-wide `range` and `filters`. New and changed widgets are checked exactly as bi_create_dashboard checks them. A colleague’s board that you can read stays theirs: offer to build the person their own with bi_create_dashboard. Never changes who can see a board. A widget the board already shows is not appended twice, so a retry is safe.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object
  - `name` string: A new name.
  - `widgets` object[]: The COMPLETE new list, in order: { keep_widget } for each widget that stays, a new widget for each one to add. A widget left out is removed.
    - `keep_widget` string: The id of a widget on this board (bi_get_dashboard): it stays, with any field sent beside it changed.
    - `dataset` string: A dataset key exactly as custodo_query_analytics lists it.
    - `title` string: The card’s caption. Omit to show the dataset’s own name, in the reader’s language.
    - `viz` 'stat' | 'bar' | 'column' | 'line' | 'area' | 'donut' | 'table': The chart shape. Omit for the axis’ default.
    - `dimension` string: One of the dataset’s dimensions to group by. Omit for its first.
    - `split_by` string, nullable: One of the dataset’s splits: a second axis that breaks every bucket down.
    - `grain` 'day' | 'week' | 'month' | 'quarter' | 'year', nullable: Bucket width on a time axis. Omit to fit the window.
    - `range` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'last_12_months' | 'this_month' | 'this_year' | 'all_time' | 'custom': The window measured. Omit for the organisation’s default.
    - `from` string, nullable: With range "custom" only.
    - `to` string, nullable: With range "custom" only.
    - `filters` object: Filters the dataset declares, by key. A data filter takes an id from its own module — a document type from documents_list_types.
    - `sort` 'default' | 'value_desc' | 'value_asc' | 'label_asc' | 'label_desc'
    - `compare` 'none' | 'previous_period' | 'previous_year': Also measure the previous period or year, as a delta.
    - `row_limit` integer: Bars, slices or rows to draw, 1–200. Default 12.
    - `width` integer: Columns of 12: 3, 4, 6 (default) or 12.
  - `add_widgets` object[]: New widgets appended after the ones the board has.
    - `dataset` string, required: A dataset key exactly as custodo_query_analytics lists it.
    - `title` string: The card’s caption. Omit to show the dataset’s own name, in the reader’s language.
    - `viz` 'stat' | 'bar' | 'column' | 'line' | 'area' | 'donut' | 'table': The chart shape. Omit for the axis’ default.
    - `dimension` string: One of the dataset’s dimensions to group by. Omit for its first.
    - `split_by` string, nullable: One of the dataset’s splits: a second axis that breaks every bucket down.
    - `grain` 'day' | 'week' | 'month' | 'quarter' | 'year', nullable: Bucket width on a time axis. Omit to fit the window.
    - `range` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'last_12_months' | 'this_month' | 'this_year' | 'all_time' | 'custom': The window measured. Omit for the organisation’s default.
    - `from` string, nullable: With range "custom" only.
    - `to` string, nullable: With range "custom" only.
    - `filters` object: Filters the dataset declares, by key. A data filter takes an id from its own module — a document type from documents_list_types.
    - `sort` 'default' | 'value_desc' | 'value_asc' | 'label_asc' | 'label_desc'
    - `compare` 'none' | 'previous_period' | 'previous_year': Also measure the previous period or year, as a delta.
    - `row_limit` integer: Bars, slices or rows to draw, 1–200. Default 12.
    - `width` integer: Columns of 12: 3, 4, 6 (default) or 12.
  - `range` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'last_12_months' | 'this_month' | 'this_year' | 'all_time' | 'custom', nullable: One window for the whole board; null gives each widget its own again.
  - `from` string, nullable: With range "custom" only.
  - `to` string, nullable: With range "custom" only.
  - `filters` object: Board-wide filters: each narrows every widget whose dataset declares that key.

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `404`: Nothing with that id in this organisation.
- `409`: The record is in a state that does not allow it — under legal hold, already sent, already closed. `error.code` says which.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)