Skip to main content

​
Get Widget by ID

​
widgetId
string
required
The ID of the widget to retrieve

​
Request

GET /api/widgets/{widgetId}

​
Authentication

Requires an active session. Users can only access widgets from their own projects.

​
Response

​
success
boolean
Indicates if the operation was successful
​
widget
object
The widget object containing all configuration and data
​
id
string
Unique widget identifier
​
projectId
string
ID of the project this widget belongs to
​
type
string
Widget type (e.g., “DataTable”, “Chart”, “TextBlock”)
​
subtype
string | null
Widget subtype for specialized configurations
​
title
string
Widget title
​
description
string | null
Optional widget description
​
configs
object
Widget-specific configuration object (varies by widget type)
​
query
string | null
SQL query for data-driven widgets
​
connectionId
string | null
ID of the database connection used by this widget
​
createdAt
string
ISO timestamp of widget creation
​
updatedAt
string
ISO timestamp of last widget update

​
Example

const response = await fetch('/api/widgets/widget_abc123', {
  method: 'GET',
  credentials: 'include'
});

const data = await response.json();

{
  "success": true,
  "widget": {
    "id": "widget_abc123",
    "projectId": "proj_xyz789",
    "type": "DataTable",
    "subtype": null,
    "title": "Sales Report",
    "description": "Monthly sales data",
    "configs": {
      "columns": [
        { "field": "product", "header": "Product" },
        { "field": "sales", "header": "Sales" }
      ],
      "pagination": true,
      "pageSize": 10
    },
    "query": "SELECT product, sales FROM monthly_sales WHERE year = 2026",
    "connectionId": "conn_def456",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-05T14:30:00.000Z"
  }
}
Users can only access widgets that belong to projects they own. The API checks project ownership through the session user ID.

​
Widget Management via Server Actions

While the HTTP API only provides read access to widgets, widget creation, updates, and deletion are handled through Next.js Server Actions:

​
Available Server Actions

upsertWidgetAction

Create a new widget or update an existing one

deleteWidgetAction

Delete a widget by ID

​
Why Server Actions?

VizBoard uses Next.js Server Actions for write operations (create, update, delete) because they provide:
  • Built-in CSRF protection
  • Seamless integration with React Server Components
  • Automatic revalidation of cached data
  • Type-safe function calls from the client
For more information on widget CRUD operations, see the Widget Server Actions documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us