Broadcast Messages API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated
History

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:

AttributeTypeRequiredDescription
idintegeryesID 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:

AttributeTypeRequiredDescription
messagestringyesMessage to display.
starts_atdatetimenoStarting time (defaults to current time in UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
ends_atdatetimenoEnding time (defaults to one hour from current time in UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
fontstringnoForeground color hex code.
target_access_levelsarray of integersnoTarget access levels (roles) of the broadcast message.
target_pathstringnoTarget path of the broadcast message.
broadcast_typestringnoAppearance type (defaults to banner)
dismissablebooleannoCan the user dismiss the message?
themestringnoColor 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:

AttributeTypeRequiredDescription
idintegeryesID of broadcast message to update.
messagestringnoMessage to display.
starts_atdatetimenoStarting time (UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
ends_atdatetimenoEnding time (UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
fontstringnoForeground color hex code.
target_access_levelsarray of integersnoTarget access levels (roles) of the broadcast message.
target_pathstringnoTarget path of the broadcast message.
broadcast_typestringnoAppearance type (defaults to banner)
dismissablebooleannoCan the user dismiss the message?
themestringnoColor 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:

AttributeTypeRequiredDescription
idintegeryesID 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"