Move a widget

Moves one widget to another row, another column or another section of the same report, or several widgets at once.

Rows and columns are numbered from 1 and every read publishes the ones a widget has. Send to with widget_key for one widget: a row past the last one of the section opens a new row, and a call without a column puts the widget at the end of the row it lands in. Send layout to place several at once, which is what the previous_layout of an earlier move is for: the answer publishes it in this very shape, so sending that array back as layout returns the report to the arrangement it had, in one call and with nothing to reshape. Every widget of the touched sections that layout does not name keeps the place it has.

The rules of the layout are the application's: a row holds up to 4 KPIs or up to 2 other widgets and never both, a widget whose definition asked for full_width is alone in its row, and a row holding a page break takes nobody else -- a page break, for its part, opens a row of its own anywhere and joins none. A row that does not take the widget is refused with 409 ROW_RULE, naming the widget the call placed and the first free row of the section. Only the rows this call puts a widget into are judged: a row written before these rules existed is left exactly as it is.

A widget that ends up in another section is re-read against that section's date range and global filters: its cached results are dropped and the answer says so with section_changed. An AI summary crossing into another section answers to the same ceilings as one created there. A report built on a template is refused with 400 APPEND_NOT_ALLOWED, reason template_based: its layout belongs to its template.

Send if_position to be refused with 409 POSITION_CHANGED when the widget is not where it was read, and retry with the new position AND THE SAME idempotency_key.

Refusals: 400 for the framework and the body, 400 APPEND_NOT_ALLOWED, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 ROW_RULE, 409 POSITION_CHANGED, 409 AI_SUMMARY_NOT_ALLOWED, 409 SECTION_BUSY, 409 SECTION_CHANGED -- a section the call touches changed after the call read it, in which case nothing is written, so read the report again and send what is left -- and 409 REPORT_IN_TRASH.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.