update_dashboard - Qobra public API documentation

Rename a dashboard, add reports to it, arrange its tiles, any of the three in one call, and return tile_changes, layout_changes and the layout as it now stands. Pass at least one of name, description, reports or layout_rows. Removing a tile is done in the web app. reports adds each report as the tiles it can render: a chart and a pivot table make two tiles, a report with neither is skipped. visualization_types narrows that to one of them. layout_rows is applied after the reports are added, so one call can add and place them, naming new tiles by report_id; it is the whole arrangement, and a tile left out is kept, not removed. A report’s visualization_types narrows the tiles it adds to its chart or its pivot table; list_reports names what each report can render in its available_visualizations. A new tile has no visualization_id yet, so name it by its report_id in layout_rows. A tile you leave out of layout_rows goes after the others, one per row, and an empty list resets the page, one tile per row. Adding and arranging never fail over one bad entry: they do what they can and say so per row. Read the outcome of every tile_changes and layout_changes row before reporting success. A report can come back not_found, no_visualization when it has no chart or pivot table yet, already_added, or type_not_available for each type you asked for that it does not offer, even when its other tile was added. Read the returned layout rather than assuming your rows were kept as sent: a row holds at most three charts, or two tiles when one is a pivot table, 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. 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 from list_dashboards or create_dashboard. The dashboard names its environment: there is no sandbox_id.

string

New name. Omit to keep the current one.

string

New free-text note about what the dashboard is for. Omit to keep the current one; "" clears it.

object[]

Reports to add, each as every tile it can render (chart, pivot table or both) unless its visualization_types narrows it. Omit to leave the 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 whole arrangement, rows top to bottom, each row’s tiles left to right. An entry is a visualization_id from get_dashboard, or a report_id (every tile of that report: the only way to place tiles this same call adds). A row holds at most three charts, or two tiles when one is a pivot table; an overflowing row is split. A tile you leave out goes after the others, one per row. Omit to leave the arrangement alone; [] resets it, one tile per row.

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 goes after the others, one per row.

Response

Body

object

The dashboard as it now stands after the update.

Show object properties

string

Web app link to this dashboard.

string

string | null

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, so does each type you asked for that the report lacks, and one not found or with no tile at all 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

“added”: put on the dashboard. “already_added”: the dashboard already had it, so a re-sent call is a no-op. “not_found”: no report you can read, living where the dashboard does, has that id. “no_visualization”: the report has neither a chart nor a pivot table. “type_not_available”: a type asked for in visualization_types that the report lacks, whether or not its other tile landed. One of: added, already_added, not_found, no_visualization, type_not_available.

string

The id you passed, as you spelled it.

object

The report it resolved to; null when not found.

Show object properties

string

The tile this row is about: chart or pivot_table (for type_not_available, the type the report lacks). Null when the row is about the whole report: not_found or no_visualization. One of: chart, pivot_table.

string

Why, and what to do next. Null for a tile that landed.

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.

string

The tile’s own title: renamable in the web app, so not always its report’s name.

object

The report this tile renders.

Show object properties

string

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

“placed”: positioned by this call. “already_placed”: an earlier entry placed it, a tile sitting on one row only. “not_found”: neither a tile of this dashboard nor a report on it. One of: placed, already_placed, not_found.

string

The layout entry you passed.

string

Why, and what to do next. Null for an entry placed.

​Parameters

​Example

​Response

Parameters

Example

Response