Widgets API

Widgets define how a set of assets are displayed. All management endpoints require JWT authentication.

POST/api/projects/{projectId}/widgetsJWT

Request body

Name	Type	Default	Description
`name`*	string	—	Widget display name
`slug`*	string	—	URL-friendly identifier, unique within the project. Used for public delivery.
`assetIds`	UUID[]	—	Ordered list of asset IDs. The array index determines display order.
`layout`*	string	—	Layout type: CAROUSEL, GRID, MASONRY, SLIDER, LIST_VERTICAL, LIST_HORIZONTAL
`config`	object	—	Layout-specific configuration
`theme`	object	—	Visual theme settings

Request

{
"name": "Hero Carousel",
"slug": "hero-carousel",
"assetIds": [
  "550e8400-e29b-41d4-a716-446655440000",
  "660e8400-e29b-41d4-a716-446655440001"
],
"layout": "CAROUSEL",
"config": {
  "autoplay": true,
  "autoplaySpeed": 3000,
  "showDots": true,
  "infinite": true
},
"theme": {
  "borderRadius": 12,
  "padding": 8
}
}

Response `201`

Response

{
"id": "aa0e8400-e29b-41d4-a716-446655440000",
"projectId": "770e8400-e29b-41d4-a716-446655440000",
"assetIds": [
  "550e8400-e29b-41d4-a716-446655440000",
  "660e8400-e29b-41d4-a716-446655440001"
],
"name": "Hero Carousel",
"slug": "hero-carousel",
"layout": "CAROUSEL",
"config": "{"autoplay":true,"autoplaySpeed":3000,"showDots":true,"infinite":true}",
"theme": "{"borderRadius":12,"padding":8}",
"status": "DRAFT",
"createdAt": "2026-01-15T10:30:00",
"updatedAt": "2026-01-15T10:30:00"
}

List widgets

GET/api/projects/{projectId}/widgetsJWT

Response `200`

Returns an array of widget objects.

GET/api/projects/{projectId}/widgets/{widgetId}JWT

Response `200`

Returns the widget object.

PUT/api/projects/{projectId}/widgets/{widgetId}JWT

Request body

Name	Type	Default	Description
`name`*	string	—	Updated widget name
`assetIds`	UUID[]	—	Updated ordered list of asset IDs. Replaces the existing list.
`layout`*	string	—	Updated layout type
`config`	object	—	Updated layout configuration
`theme`	object	—	Updated theme settings