Broadcast Messages API

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated
History
  • target_access_levels introduced in GitLab 14.8 with a flag named role_targeted_broadcast_messages. Disabled by default.
  • color parameter removed in GitLab 15.6.
  • theme introduced in GitLab 17.6.

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, 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, 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"