Use this API to interact with banners and notifications displayed in the UI. For more information, see broadcast messages.
GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:
- Unauthenticated users result in
401 Unauthorized. - Authenticated non-administrators result in
403 Forbidden.
List all broadcast messages
GET /api/v4/broadcast_messages
Lists all broadcast messages for the instance.
Parameters
| Name | Type | Description |
|---|---|---|
pageQuery | Integer | Page number of results to retrieve Default: 1Example: 1 |
per_Query | Integer | Number of items to list per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
Create a broadcast message
POST /api/v4/broadcast_messages
Creates a broadcast message.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
broadcast_ | String | Appearance type of the broadcast message Allowed values: banner,notificationDefault: banner |
color | String | Background color hex code.theme instead |
dismissable | Boolean | If true, |
ends_ | String (date- | Ending time, |
font | String | Foreground color hex code.theme instead |
messageRequired | String | Message to display |
starts_ | String (date- | Starting time, |
target_ | Array of integers | Target access levels (roles) of the broadcast message |
target_ | String | Target path of the broadcast message |
theme | String | Color theme for the broadcast message. Allowed values: indigo,light-,blue,light-,green,light-,red,light-,dark,light |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
Retrieve a broadcast message
GET /api/v4/broadcast_messages/{id}
Retrieves a specified broadcast message.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | ID of the broadcast message |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Update a broadcast message
PUT /api/v4/broadcast_messages/{id}
Updates a specified broadcast message.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | ID of the broadcast message |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
broadcast_ | String | Appearance type of the broadcast message Allowed values: banner,notification |
color | String | Background color hex code.theme instead |
dismissable | Boolean | If true, |
ends_ | String (date- | Ending time, |
font | String | Foreground color hex code.theme instead |
message | String | Message to display |
starts_ | String (date- | Starting time, |
target_ | Array of integers | Target access levels (roles) of the broadcast message |
target_ | String | Target path of the broadcast message |
theme | String | Color theme for the broadcast message. Allowed values: indigo,light-,blue,light-,green,light-,red,light-,dark,light |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Delete a broadcast message
DELETE /api/v4/broadcast_messages/{id}
Deletes a specified broadcast message.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | ID of the broadcast message |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesSystemBroadcastMessage
| Property | Type | Description |
|---|---|---|
active | Boolean | — |
broadcast_ | String | Example:banner |
color | String | Example:#E75 |
dismissable | Boolean | — |
ends_ | String (date- | Example:2016- |
font | String | Example:#FFFFFF |
id | Integer (int64) | — |
message | String | Example:Example broadcast message |
starts_ | String (date- | Example:2016- |
target_ | Array | Example:[10, |
target_ | String | Example:*/ |
theme | String | Example:indigo |