Skip to main content

Visit Later

N/a

General Notes

  • At least one of title or position must be provided in the request body
  • Request body uses additionalProperties: false — extra fields are rejected
  • position updates are restricted to SUPER_ADMIN via Cerbos policy condition: if position is present in the request body, Cerbos denies the request for AE/CIO roles
  • SUPER_ADMIN can update any widget (bypasses userId ownership check); regular users can only update their own widgets

Flow

Mermaid editor

Test cases

Method & URL

PATCH v1/widgets/:widgetId

Request

Headers

authorization
  - Required
  - Type : <string>
  - Bearer session token

Query


Body

title
  - Optional (at least one of title or position required)
  - Type : <string>
  - Max length: 200 characters
  - New display title for the widget

position
  - Optional (at least one of title or position required)
  - Type : <number>
  - SUPER_ADMIN only — Cerbos denies this field for AE/CIO roles
  - New display order within the canvas

Path parameter

widgetId
  - Required
  - Type : <string>
  - MongoDB ObjectId (24 hex characters)

Response

2xx

success
  - Type : true (boolean)
  - This indicates that request was executed successfully

message
  - Type : <string> | null
  - null on success

data
  - Type : <object>

data.widget
  - Type : <object>
  - The updated widget

data.widget.id
  - Type : <string>
  - Widget identifier

data.widget.title
  - Type : <string>
  - Widget display title

data.widget.type
  - Type : <string>
  - Enum : chart | table

data.widget.chartType
  - Type : <string> | null
  - Enum : line | bar | pie | donut | stackedBar | scatterPlot
  - null when type is "table"

data.widget.position
  - Type : <number>
  - Display order within the canvas

data.widget.conversationId
  - Type : <string> | null
  - Reference to the conversation that created this widget

data.widget.aiModel
  - Type : <string> | null
  - Which Claude model generated this widget

data.widget.createdAt
  - Type : <string>
  - ISO date of when the widget was created

data.widget.updatedAt
  - Type : <string>
  - ISO date of when the widget was last updated

400

success
  - Type : false (boolean)

message
  - Type : <string>
  - "Something went wrong. We're on it." (invalid widgetId format)
  - "Please provide a title or position to update" (empty body)
  - "Widget title cannot exceed 200 characters" (title too long)

401

success
  - Type : false (boolean)

message
  - Type : <string>
  - Unauthorized (position update attempted by non-SUPER_ADMIN)

404

success
  - Type : false (boolean)

message
  - Type : <string>
  - Widget not found