Widgets

Rename a widget

Changes the title of one widget and nothing else. Every kind of widget has one -- a KPI, a chart, a table, a text block, an image, a page break and an AI summary all carry a name, and every read publishes it -- although the application only shows a name field on the ones that read data.

It takes no backup: the inverse of a rename is another rename with the name the read published. Nothing the widget shows is touched and no cached result is dropped.

The name is between 1 and 80 characters, the range the application uses; longer names already stored are left alone.

Refusals: 400 for the framework and the body, 400 APPEND_NOT_ALLOWED with reason template_based for a report built on a template -- where only the text widget the report keeps of its own can be renamed -- 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 WIDGET_CHANGED when if_widget_hash is stale, and 409 REPORT_IN_TRASH.

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

post/widgets/rename

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/widgets/rename
  • Auth: HTTP bearer

Request body

report_keystring required

The report the widget belongs to.

section_keystring required

The section the widget is in.

widget_keystring required

The widget to rename.

namestring required

The new title, between 1 and 80 characters, plain text. A character the datastore cannot hold -- an emoji -- is refused with INVALID_VALUE, the same way the application refuses it.

dry_runboolean

Validate and answer what WOULD happen, without writing anything. Default false.

idempotency_keystring

Makes a retry safe: the answer of the first call is replayed for 24 hours to any later call with the same key and the same body.

if_widget_hashstring

The widget_hash /v1/widgets/get published for this widget. A stale one is HTTP 409 WIDGET_CHANGED; read the widget again and retry with the new hash AND THE SAME idempotency_key.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.