Broadcast Messages API
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed, GitLab Dedicated
Broadcast messages API operates on broadcast messages.
GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:
- Guests result in
401 Unauthorized
. - Regular users result in
403 Forbidden
.
Get all broadcast messages
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
List all broadcast messages.
GET /broadcast_messages
Example request:
curl "https://gitlab.example.com/api/v4/broadcast_messages"
Example response:
[
{
"message":"Example broadcast message",
"starts_at":"2016-08-24T23:21:16.078Z",
"ends_at":"2016-08-26T23:21:16.080Z",
"font":"#FFFFFF",
"id":1,
"active": false,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "banner",
"dismissable": false,
"theme": "indigo"
}
]
Get a specific broadcast message
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Get a specific broadcast message.
GET /broadcast_messages/:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | yes | ID of broadcast message to retrieve. |
Example request:
curl "https://gitlab.example.com/api/v4/broadcast_messages/1"
Example response:
{
"message":"Deploy in progress",
"starts_at":"2016-08-24T23:21:16.078Z",
"ends_at":"2016-08-26T23:21:16.080Z",
"font":"#FFFFFF",
"id":1,
"active":false,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "banner",
"dismissable": false,
"theme": "indigo"
}
Create a broadcast message
Create a new broadcast message.
POST /broadcast_messages
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
message | string | yes | Message to display. |
starts_at | datetime | no | Starting time (defaults to current time in UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z ) |
ends_at | datetime | no | Ending time (defaults to one hour from current time in UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z ) |
font | string | no | Foreground color hex code. |
target_access_levels | array of integers | no | Target access levels (roles) of the broadcast message. |
target_path | string | no | Target path of the broadcast message. |
broadcast_type | string | no | Appearance type (defaults to banner) |
dismissable | boolean | no | Can the user dismiss the message? |
theme | string | no | Color theme for the broadcast message (banners only). |
The target_access_levels
are defined in the Gitlab::Access
module. The
following levels are valid:
- Guest (
10
) - Planner (
15
) - Reporter (
20
) - Developer (
30
) - Maintainer (
40
) - Owner (
50
)
The theme
options are defined in the System::BroadcastMessage
class. The following themes are valid:
- indigo (default)
- light-indigo
- blue
- light-blue
- green
- light-green
- red
- light-red
- dark
- light
Example request:
curl --data "message=Deploy in progress&target_access_levels[]=10&target_access_levels[]=30&theme=red" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/broadcast_messages"
Example response:
{
"message":"Deploy in progress",
"starts_at":"2016-08-26T00:41:35.060Z",
"ends_at":"2016-08-26T01:41:35.060Z",
"font":"#FFFFFF",
"id":1,
"active": true,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "notification",
"dismissable": false,
"theme": "red"
}
Update a broadcast message
Update an existing broadcast message.
PUT /broadcast_messages/:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | yes | ID of broadcast message to update. |
message | string | no | Message to display. |
starts_at | datetime | no | Starting time (UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z ) |
ends_at | datetime | no | Ending time (UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z ) |
font | string | no | Foreground color hex code. |
target_access_levels | array of integers | no | Target access levels (roles) of the broadcast message. |
target_path | string | no | Target path of the broadcast message. |
broadcast_type | string | no | Appearance type (defaults to banner) |
dismissable | boolean | no | Can the user dismiss the message? |
theme | string | no | Color theme for the broadcast message (banners only). |
The target_access_levels
are defined in the Gitlab::Access
module. The
following levels are valid:
- Guest (
10
) - Planner (
15
) - Reporter (
20
) - Developer (
30
) - Maintainer (
40
) - Owner (
50
)
The theme
options are defined in the System::BroadcastMessage
class. The following themes are valid:
- indigo (default)
- light-indigo
- blue
- light-blue
- green
- light-green
- red
- light-red
- dark
- light
Example request:
curl --request PUT --data "message=Update message" \
--header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"
Example response:
{
"message":"Update message",
"starts_at":"2016-08-26T00:41:35.060Z",
"ends_at":"2016-08-26T01:41:35.060Z",
"font":"#FFFFFF",
"id":1,
"active": true,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "notification",
"dismissable": false,
"theme": "indigo"
}
Delete a broadcast message
Delete a broadcast message.
DELETE /broadcast_messages/:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | yes | ID of broadcast message to delete. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support