update_dashboard - Qobra public API documentation

Rename a dashboard, add reports to it, arrange its tiles — any of the three, or all of them in one call. Pass name and/or description to change how the dashboard reads. Pass reports to add reports to it as the tiles each one can render — a report carrying both a chart and a pivot table becomes two tiles, one carrying only a chart becomes one, and one carrying neither is skipped, there being nothing to show. A report’s visualization_types narrows that to its chart or its pivot table when you want only one of them; list_reports names what each report can render in its available_visualizations. Removing a tile is still a job for the Qobra web app. Pass layout_rows to say how the tiles sit on the page. It describes the whole arrangement, top to bottom, and it is applied after the reports are added — so one call can add reports and place them, naming each by its report_id since a new tile has no visualization_id yet. A tile you leave out is not removed: it keeps its place, appended on a row of its own. An empty list resets the page, every tile on a row of its own. Pass at least one of name, description, reports or layout_rows — a call with none of them has nothing to update. Read the outcome on every tile_changes row before reporting success. Adding never fails over one bad report: it adds what it can and says so per row. A report can come back not_found, no_visualization when it has no chart or pivot table yet, type_not_available when it has none of the types you asked for, or already_added. Read the outcome on every layout_changes row too. Arranging never fails over one bad entry either: it places what it can and says so per entry. layout is the page as it now stands, read back from the dashboard: where every tile sits, the ones this call added included. Read it rather than assuming your rows were taken verbatim: a row holds at most three charts or two pivot tables, and one that overflows is split. You need write access on the dashboard itself. A dashboard shared with you read-only is refused with a message saying the share is read-only; pick one you can edit from list_dashboards, or create a new one with create_dashboard. A dashboard you cannot read at all is refused as not found. Available only where the Qobra write tools beta is enabled. Every write to the live environment is recorded in the audit trail as the Qobra MCP agent; writes to a sandbox are not audited.

Parameters

Body

string

required

Id of the dashboard to update — the id list_dashboards returns, or the one create_dashboard just returned. The dashboard names the environment this writes to, so there is no sandbox argument.

string

New display name for the dashboard. Omit to leave the current name as it is.

string

New free-text note about what the dashboard is for. Omit to leave the current description as it is.

object[]

Reports to add, each as every tile it can render — its chart, its pivot table, or both, unless its visualization_types narrows it. Omit to leave the dashboard’s tiles untouched.

Show object properties

string

required

Id of the report to add, as list_reports returns it.

string[]

Which of its tiles to add: chart, pivot_table, or both. Omit to add every tile the report offers, which is what you want unless the caller asked for one of the two; list_reports names what each report offers in its available_visualizations.

string[][]

The dashboard’s rows, top to bottom; each row lists one or more tiles left to right. An entry is a visualization_id from get_dashboard, or a report_id — the report form is how you arrange tiles this same call is adding, since they have no visualization_id until they exist, and it places every tile of that report. A row holds at most three charts or two pivot tables and is split when it overflows; a tile you leave out keeps its place, appended on a row of its own. Omit to leave the arrangement alone; pass an empty list to reset it, every tile on a row of its own.

Example

Add a report’s pivot table to an existing dashboard and put it on the first row, next to a tile already on the page:

{
  "dashboard_id": "665f1c2e8a4b3d0012a7ec10",
  "reports": [
    { "report_id": "665f1c2e8a4b3d0012a7eb03", "visualization_types": ["pivot_table"] }
  ],
  "layout_rows": [
    ["665f1c2e8a4b3d0012a7ed20", "665f1c2e8a4b3d0012a7eb03"]
  ]
}

665f1c2e8a4b3d0012a7ed20 is the visualization_id of a tile already on the dashboard, as get_dashboard lists it. Every tile left out of layout_rows keeps its place on a row of its own.

Response

Body

object

The dashboard as it now stands after the update.

Show object properties

string

Deep link to open this dashboard in the Qobra web app.

string

object[]

What became of each report you passed, one row per tile: a report added as both a chart and a pivot table gets a row for each, and one that adds nothing gets a single row, with visualization_type null. Read outcome on each before reporting success, since a call can succeed having added nothing you asked for. Empty when no reports were passed.

Show object properties

string

What became of this report. “added” for a tile this call put on the dashboard; “already_added” for one the dashboard already carried, which is how a re-sent call reads as the no-op it was; “not_found” when no report of yours has that id; “no_visualization” when the report has neither a chart nor a pivot table to show; “type_not_available” when it has tiles but none of the visualization_types you asked for. One of: added, already_added, not_found, no_visualization, type_not_available.

string

The report id you passed, echoed back as you spelled it, so the row matches your request even when report is null.

object

The report it resolved to, named — null when it is not one you can read, since naming it would say a report you cannot see exists.

Show object properties

string

The tile this row is about: chart or pivot_table. Null when no single tile can be named — nothing was added at all. One of: chart, pivot_table.

string

Why, as a sentence saying what to do next. Null for a tile that landed, there being nothing to act on.

object[]

The dashboard’s rows as they now stand, top to bottom, each tile left to right — read back from the dashboard, so it shows where every tile actually sits. A tile this call added lands on a row of its own at the end. Empty when the dashboard has no tile yet. Rows passed in layout_rows are applied after the reports are added and come back as the store took them: a row holds at most three charts or two pivot tables and is split when it overflows, and a tile you left out keeps its place on a row of its own.

Show object properties

object[]

The tiles on this row, left to right. Rows read top to bottom.

Show object properties

string

Id of the tile, as get_dashboard lists it.

object

The report this tile renders.

Show object properties

string

What the tile renders the report as: chart or pivot_table. One of: chart, pivot_table.

object[]

One row per layout entry you passed, saying what became of it. Empty when no layout_rows were passed.

Show object properties

string

What became of this layout entry. “placed” for a tile this call positioned; “already_placed” when an earlier entry of the same layout already placed it, a tile sitting on one row only; “not_found” when the entry names neither a tile of this dashboard nor a report on it. One of: placed, already_placed, not_found.

string

The layout entry you passed, echoed back.

string

Why, as a sentence saying what to do next. Null for an entry that placed its tile.

​Parameters

​Example

​Response

Parameters

Example

Response