> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/developer/integrate/openapi/widget.md).

# Widget

Widgets

## Add a Widget to a Playlist

> Add a new Widget to a Playlist

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{type}/{playlistId}":{"post":{"tags":["widget"],"summary":"Add a Widget to a Playlist","description":"Add a new Widget to a Playlist","operationId":"addWidget","parameters":[{"schema":{"type":"string"},"name":"type","in":"path","description":"The type of the Widget e.g. text. Media based Widgets like Image are added via POST /playlist/library/assign/{playlistId} call.","required":true},{"schema":{"type":"integer"},"name":"playlistId","in":"path","description":"The Playlist ID","required":true}],"responses":{"201":{"description":"successful operation","headers":{"Location":{"description":"Location of the new record","schema":{"type":"string"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"displayOrder":{"type":"integer","description":"Optional integer to say which position this assignment should occupy in the list. If more than one media item is being added, this will be the position of the first one."},"templateId":{"type":"string","description":"If the module type provided has a dataType then provide the templateId to use."}},"required":[]}}}}}}}}
```

## Edit a Widget

> Edit a widget providing new properties to set on it

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{id}":{"put":{"tags":["widget"],"summary":"Edit a Widget","description":"Edit a widget providing new properties to set on it","operationId":"editWidget","parameters":[{"schema":{"type":"string"},"name":"id","in":"path","description":"The ID of the Widget","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"useDuration":{"type":"integer","description":"Set a duration on this widget, if unchecked the default or library duration will be used."},"duration":{"type":"integer","description":"Duration to use on this widget"},"name":{"type":"string","description":"An optional name for this widget"},"enableStat":{"type":"string","description":"Should stats be enabled? On|Off|Inherit "},"isRepeatData":{"type":"integer","description":"If this widget requires data, should that data be repeated to meet the number of items requested?"},"showFallback":{"type":"string","description":"If this widget requires data and allows fallback data how should that data be returned? (never, always, empty, error)"},"properties":{"type":"integer","description":"Add an additional parameter for each of the properties required this module and its template. Use the moduleProperties and moduleTemplateProperties calls to get a list of properties needed"}},"required":[]}}}}}}}}
```

## Delete a Widget

> Deleted a specified widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{widgetId}":{"delete":{"tags":["widget"],"summary":"Delete a Widget","description":"Deleted a specified widget","operationId":"WidgetDelete","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"The widget ID to delete","required":true}],"responses":{"200":{"description":"successful operation"}}}}}}
```

## Adds In/Out transition

> Adds In/Out transition to a specified widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Widget":{"properties":{"widgetId":{"description":"The Widget ID","type":"integer"},"playlistId":{"description":"The ID of the Playlist this Widget belongs to","type":"integer"},"ownerId":{"description":"The ID of the User that owns this Widget","type":"integer"},"type":{"description":"The Module Type Code","type":"string"},"duration":{"description":"The duration in seconds this widget should be shown","type":"integer"},"displayOrder":{"description":"The display order of this widget","type":"integer"},"useDuration":{"description":"Flag indicating if this widget has a duration that should be used","type":"integer"},"calculatedDuration":{"description":"Calculated Duration of this widget after taking into account the useDuration flag","type":"integer"},"createdDt":{"description":"The datetime the Layout was created","type":"string"},"modifiedDt":{"description":"The datetime the Layout was last modified","type":"string"},"fromDt":{"description":"Widget From Date","type":"integer"},"toDt":{"description":"Widget To Date","type":"integer"},"schemaVersion":{"description":"Widget Schema Version","type":"integer"},"transitionIn":{"description":"Transition Type In","type":"integer"},"transitionOut":{"description":"Transition Type out","type":"integer"},"transitionDurationIn":{"description":"Transition duration in","type":"integer"},"transitionDurationOut":{"description":"Transition duration out","type":"integer"},"widgetOptions":{"description":"An array of Widget Options","type":"array","items":{"$ref":"#/components/schemas/WidgetOption"}},"mediaIds":{"description":"An array of MediaIds this widget is linked to","type":"array","items":{"type":"integer"}},"audio":{"description":"An array of Audio MediaIds this widget is linked to","type":"array","items":{"$ref":"#/components/schemas/WidgetAudio"}},"permissions":{"description":"An array of permissions for this widget","type":"array","items":{"$ref":"#/components/schemas/Permission"}},"playlist":{"description":"The name of the Playlist this Widget is on","type":"string"}}},"WidgetOption":{"properties":{"widgetId":{"description":"The Widget ID that this Option belongs to","type":"integer"},"type":{"description":"The option type, either attrib or raw","type":"string"},"option":{"description":"The option name","type":"string"},"value":{"description":"The option value","type":"string"}}},"WidgetAudio":{"properties":{"widgetId":{"description":"The Widget Id","type":"integer"},"mediaId":{"description":"The Media Id","type":"integer"},"volume":{"description":"The percentage volume","type":"integer"},"loop":{"description":"Flag indicating whether to loop","type":"integer"}}},"Permission":{"properties":{"permissionId":{"description":"The ID of this Permission Record","type":"integer"},"entityId":{"description":"The Entity ID that this Permission refers to","type":"integer"},"groupId":{"description":"The User Group ID that this permission refers to","type":"integer"},"objectId":{"description":"The object ID that this permission refers to","type":"integer"},"isUser":{"description":"A flag indicating whether the groupId refers to a user specific group","type":"integer"},"entity":{"description":"The entity name that this refers to","type":"string"},"objectIdString":{"description":"Legacy for when the Object ID is a string","type":"string"},"group":{"description":"The group name that this refers to","type":"string"},"view":{"description":"A flag indicating whether view permission is granted","type":"integer"},"edit":{"description":"A flag indicating whether edit permission is granted","type":"integer"},"delete":{"description":"A flag indicating whether delete permission is granted","type":"integer"},"modifyPermissions":{"description":"A flag indicating whether modify permission permission is granted.","type":"integer"}}}}},"paths":{"/playlist/widget/transition/{type}/{widgetId}":{"put":{"tags":["widget"],"summary":"Adds In/Out transition","description":"Adds In/Out transition to a specified widget","operationId":"WidgetEditTransition","parameters":[{"schema":{"type":"string"},"name":"type","in":"path","description":"Transition type, available options: in, out","required":true},{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"The widget ID to add the transition to","required":true}],"responses":{"201":{"description":"successful operation","headers":{"Location":{"description":"Location of the new widget","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"transitionType":{"type":"string","description":"Type of a transition, available Options: fly, fadeIn, fadeOut"},"transitionDuration":{"type":"integer","description":"Duration of this transition in milliseconds"},"transitionDirection":{"type":"integer","description":"The direction for this transition, only appropriate for transitions that move, such as fly. Available options: N, NE, E, SE, S, SW, W, NW"}},"required":["transitionType"]}}}}}}}}
```

## Parameters for edting/adding audio file to a specific widget

> Parameters for edting/adding audio file to a specific widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Widget":{"properties":{"widgetId":{"description":"The Widget ID","type":"integer"},"playlistId":{"description":"The ID of the Playlist this Widget belongs to","type":"integer"},"ownerId":{"description":"The ID of the User that owns this Widget","type":"integer"},"type":{"description":"The Module Type Code","type":"string"},"duration":{"description":"The duration in seconds this widget should be shown","type":"integer"},"displayOrder":{"description":"The display order of this widget","type":"integer"},"useDuration":{"description":"Flag indicating if this widget has a duration that should be used","type":"integer"},"calculatedDuration":{"description":"Calculated Duration of this widget after taking into account the useDuration flag","type":"integer"},"createdDt":{"description":"The datetime the Layout was created","type":"string"},"modifiedDt":{"description":"The datetime the Layout was last modified","type":"string"},"fromDt":{"description":"Widget From Date","type":"integer"},"toDt":{"description":"Widget To Date","type":"integer"},"schemaVersion":{"description":"Widget Schema Version","type":"integer"},"transitionIn":{"description":"Transition Type In","type":"integer"},"transitionOut":{"description":"Transition Type out","type":"integer"},"transitionDurationIn":{"description":"Transition duration in","type":"integer"},"transitionDurationOut":{"description":"Transition duration out","type":"integer"},"widgetOptions":{"description":"An array of Widget Options","type":"array","items":{"$ref":"#/components/schemas/WidgetOption"}},"mediaIds":{"description":"An array of MediaIds this widget is linked to","type":"array","items":{"type":"integer"}},"audio":{"description":"An array of Audio MediaIds this widget is linked to","type":"array","items":{"$ref":"#/components/schemas/WidgetAudio"}},"permissions":{"description":"An array of permissions for this widget","type":"array","items":{"$ref":"#/components/schemas/Permission"}},"playlist":{"description":"The name of the Playlist this Widget is on","type":"string"}}},"WidgetOption":{"properties":{"widgetId":{"description":"The Widget ID that this Option belongs to","type":"integer"},"type":{"description":"The option type, either attrib or raw","type":"string"},"option":{"description":"The option name","type":"string"},"value":{"description":"The option value","type":"string"}}},"WidgetAudio":{"properties":{"widgetId":{"description":"The Widget Id","type":"integer"},"mediaId":{"description":"The Media Id","type":"integer"},"volume":{"description":"The percentage volume","type":"integer"},"loop":{"description":"Flag indicating whether to loop","type":"integer"}}},"Permission":{"properties":{"permissionId":{"description":"The ID of this Permission Record","type":"integer"},"entityId":{"description":"The Entity ID that this Permission refers to","type":"integer"},"groupId":{"description":"The User Group ID that this permission refers to","type":"integer"},"objectId":{"description":"The object ID that this permission refers to","type":"integer"},"isUser":{"description":"A flag indicating whether the groupId refers to a user specific group","type":"integer"},"entity":{"description":"The entity name that this refers to","type":"string"},"objectIdString":{"description":"Legacy for when the Object ID is a string","type":"string"},"group":{"description":"The group name that this refers to","type":"string"},"view":{"description":"A flag indicating whether view permission is granted","type":"integer"},"edit":{"description":"A flag indicating whether edit permission is granted","type":"integer"},"delete":{"description":"A flag indicating whether delete permission is granted","type":"integer"},"modifyPermissions":{"description":"A flag indicating whether modify permission permission is granted.","type":"integer"}}}}},"paths":{"/playlist/widget/{widgetId}/audio":{"put":{"tags":["widget"],"summary":"Parameters for edting/adding audio file to a specific widget","description":"Parameters for edting/adding audio file to a specific widget","operationId":"WidgetAssignedAudioEdit","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"Id of a widget to which you want to add audio or edit existing audio","required":true}],"responses":{"200":{"description":"successful operation","headers":{"Location":{"description":"Location of the new widget","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"mediaId":{"type":"integer","description":"Id of a audio file in CMS library you wish to add to a widget"},"volume":{"type":"integer","description":"Volume percentage(0-100) for this audio to play at"},"loop":{"type":"integer","description":"Flag (0, 1) Should the audio loop if it finishes before the widget has finished?"}},"required":[]}}}}}}}}
```

## Delete assigned audio widget

> Delete assigned audio widget from specified widget ID

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{widgetId}/audio":{"delete":{"tags":["widget"],"summary":"Delete assigned audio widget","description":"Delete assigned audio widget from specified widget ID","operationId":"WidgetAudioDelete","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"Id of a widget from which you want to delete the audio from","required":true}],"responses":{"200":{"description":"successful operation"}}}}}}
```

## Set Widget From/To Dates

> Control when this Widget is active on this Playlist

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"Widget":{"properties":{"widgetId":{"description":"The Widget ID","type":"integer"},"playlistId":{"description":"The ID of the Playlist this Widget belongs to","type":"integer"},"ownerId":{"description":"The ID of the User that owns this Widget","type":"integer"},"type":{"description":"The Module Type Code","type":"string"},"duration":{"description":"The duration in seconds this widget should be shown","type":"integer"},"displayOrder":{"description":"The display order of this widget","type":"integer"},"useDuration":{"description":"Flag indicating if this widget has a duration that should be used","type":"integer"},"calculatedDuration":{"description":"Calculated Duration of this widget after taking into account the useDuration flag","type":"integer"},"createdDt":{"description":"The datetime the Layout was created","type":"string"},"modifiedDt":{"description":"The datetime the Layout was last modified","type":"string"},"fromDt":{"description":"Widget From Date","type":"integer"},"toDt":{"description":"Widget To Date","type":"integer"},"schemaVersion":{"description":"Widget Schema Version","type":"integer"},"transitionIn":{"description":"Transition Type In","type":"integer"},"transitionOut":{"description":"Transition Type out","type":"integer"},"transitionDurationIn":{"description":"Transition duration in","type":"integer"},"transitionDurationOut":{"description":"Transition duration out","type":"integer"},"widgetOptions":{"description":"An array of Widget Options","type":"array","items":{"$ref":"#/components/schemas/WidgetOption"}},"mediaIds":{"description":"An array of MediaIds this widget is linked to","type":"array","items":{"type":"integer"}},"audio":{"description":"An array of Audio MediaIds this widget is linked to","type":"array","items":{"$ref":"#/components/schemas/WidgetAudio"}},"permissions":{"description":"An array of permissions for this widget","type":"array","items":{"$ref":"#/components/schemas/Permission"}},"playlist":{"description":"The name of the Playlist this Widget is on","type":"string"}}},"WidgetOption":{"properties":{"widgetId":{"description":"The Widget ID that this Option belongs to","type":"integer"},"type":{"description":"The option type, either attrib or raw","type":"string"},"option":{"description":"The option name","type":"string"},"value":{"description":"The option value","type":"string"}}},"WidgetAudio":{"properties":{"widgetId":{"description":"The Widget Id","type":"integer"},"mediaId":{"description":"The Media Id","type":"integer"},"volume":{"description":"The percentage volume","type":"integer"},"loop":{"description":"Flag indicating whether to loop","type":"integer"}}},"Permission":{"properties":{"permissionId":{"description":"The ID of this Permission Record","type":"integer"},"entityId":{"description":"The Entity ID that this Permission refers to","type":"integer"},"groupId":{"description":"The User Group ID that this permission refers to","type":"integer"},"objectId":{"description":"The object ID that this permission refers to","type":"integer"},"isUser":{"description":"A flag indicating whether the groupId refers to a user specific group","type":"integer"},"entity":{"description":"The entity name that this refers to","type":"string"},"objectIdString":{"description":"Legacy for when the Object ID is a string","type":"string"},"group":{"description":"The group name that this refers to","type":"string"},"view":{"description":"A flag indicating whether view permission is granted","type":"integer"},"edit":{"description":"A flag indicating whether edit permission is granted","type":"integer"},"delete":{"description":"A flag indicating whether delete permission is granted","type":"integer"},"modifyPermissions":{"description":"A flag indicating whether modify permission permission is granted.","type":"integer"}}}}},"paths":{"/playlist/widget/{widgetId}/expiry":{"put":{"tags":["widget"],"summary":"Set Widget From/To Dates","description":"Control when this Widget is active on this Playlist","operationId":"WidgetAssignedExpiryEdit","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"Id of a widget to which you want to add audio or edit existing audio","required":true}],"responses":{"200":{"description":"successful operation","headers":{"Location":{"description":"Location of the new widget","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"fromDt":{"type":"string","description":"The From Date in Y-m-d H::i:s format"},"toDt":{"type":"string","description":"The To Date in Y-m-d H::i:s format"},"deleteOnExpiry":{"type":"integer","description":"Delete this Widget when it expires?"}},"required":[]}}}}}}}}
```

## Set Widget Region

> Set the Region this Widget is intended for - only suitable for Drawer Widgets

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{widgetId}/region":{"put":{"tags":["widget"],"summary":"Set Widget Region","description":"Set the Region this Widget is intended for - only suitable for Drawer Widgets","operationId":"WidgetAssignedRegionSet","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"Id of the Widget to set region on","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"targetRegionId":{"type":"string","description":"The target regionId"}},"required":["targetRegionId"]}}}}}}}}
```

## Save elements to a widget

> Update a widget with elements associated with it

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{widgetId}/elements":{"put":{"tags":["widget"],"summary":"Save elements to a widget","description":"Update a widget with elements associated with it","operationId":"widgetSaveElements","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"Id of the Widget to set region on","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"JSON representing the elements assigned to this widget","required":true}}}}}
```

## Widget DataType

> Get DataType for a Widget according to the widgets module definition

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/{widgetId}/dataType":{"put":{"tags":["widget"],"summary":"Widget DataType","description":"Get DataType for a Widget according to the widgets module definition","operationId":"widgetGetDataType","parameters":[{"schema":{"type":"integer"},"name":"widgetId","in":"path","description":"Id of the Widget","required":true}],"responses":{"200":{"description":"successful operation"}},"requestBody":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"A JSON representation of your dataType","required":true}}}}}
```

## Get data for Widget

> Return all of the fallback data currently assigned to this Widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}},"schemas":{"WidgetData":{"properties":{"id":{"description":"The ID","type":"integer"},"widgetId":{"description":"The Widget ID","type":"integer"},"data":{"description":"Array of data properties depending on the widget data type this data is for","type":"array","items":{"type":"string"}},"displayOrder":{"description":"The Display Order","type":"integer"},"createdDt":{"description":"The datetime this entity was created"},"modifiedDt":{"description":"The datetime this entity was last modified"}}}}},"paths":{"/playlist/widget/data/{id}":{"get":{"tags":["widget"],"summary":"Get data for Widget","description":"Return all of the fallback data currently assigned to this Widget","operationId":"getWidgetData","parameters":[{"schema":{"type":"integer"},"name":"id","in":"path","description":"The Widget ID that this data should be added to","required":true}],"responses":{"201":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WidgetData"}}}}}}}}}}
```

## Add a data to a Widget

> Add fallback data to a data Widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/data/{id}":{"post":{"tags":["widget"],"summary":"Add a data to a Widget","description":"Add fallback data to a data Widget","operationId":"addWidgetData","parameters":[{"schema":{"type":"integer"},"name":"id","in":"path","description":"The Widget ID that this data should be added to","required":true},{"schema":{"type":"string"},"name":"data","in":"path","description":"A JSON formatted string containing a single data item for this widget's data type","required":true}],"responses":{"201":{"description":"successful operation","headers":{"Location":{"description":"Location of the new record","schema":{"type":"string"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"displayOrder":{"type":"integer","description":"Optional integer to say which position this data should appear if there is more than one data item"}},"required":[]}}}}}}}}
```

## Edit data on a Widget

> Edit fallback data on a data Widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/data/{id}/{dataId}":{"put":{"tags":["widget"],"summary":"Edit data on a Widget","description":"Edit fallback data on a data Widget","operationId":"editWidgetData","parameters":[{"schema":{"type":"integer"},"name":"id","in":"path","description":"The Widget ID that this data is attached to","required":true},{"schema":{"type":"integer"},"name":"dataId","in":"path","description":"The ID of the data to be edited","required":true},{"schema":{"type":"string"},"name":"data","in":"path","description":"A JSON formatted string containing a single data item for this widget's data type","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"displayOrder":{"type":"integer","description":"Optional integer to say which position this data should appear if there is more than one data item"}},"required":[]}}}}}}}}
```

## Delete data on a Widget

> Delete fallback data on a data Widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/data/{id}/{dataId}":{"delete":{"tags":["widget"],"summary":"Delete data on a Widget","description":"Delete fallback data on a data Widget","operationId":"deleteWidgetData","parameters":[{"schema":{"type":"integer"},"name":"id","in":"path","description":"The Widget ID that this data is attached to","required":true},{"schema":{"type":"integer"},"name":"dataId","in":"path","description":"The ID of the data to be deleted","required":true}],"responses":{"204":{"description":"successful operation"}}}}}}
```

## Update the order of data on a Widget

> Provide all data to be ordered on a widget

```json
{"openapi":"3.1.1","info":{"title":"Xibo API","version":"4.0"},"tags":[{"name":"widget","description":"Widgets"}],"servers":[{"url":"/api"}],"security":[{"auth":["write:all","read:all"]}],"components":{"securitySchemes":{"auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/api/authorize","tokenUrl":"/api/authorize/access_token","scopes":{"read:all":"read access","write:all":"write access"}}}}}},"paths":{"/playlist/widget/data/{id}/order":{"post":{"tags":["widget"],"summary":"Update the order of data on a Widget","description":"Provide all data to be ordered on a widget","operationId":"orderWidgetData","parameters":[{"schema":{"type":"integer"},"name":"id","in":"path","description":"The Widget ID that this data is attached to","required":true},{"schema":{"type":"integer"},"name":"dataId","in":"path","description":"The ID of the data to be deleted","required":true}],"responses":{"204":{"description":"successful operation"}},"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"WidgetDataOrder"}}}},"description":"An array of any widget data records that should be re-ordered","required":true}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xibosignage.com/developer/integrate/openapi/widget.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.