Broadcast Messages API

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

History

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:

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

Broadcast Messages API

Get all broadcast messages

Get a specific broadcast message

Create a broadcast message

Update a broadcast message

Delete a broadcast message

Help & feedback

Docs

Product

Feature availability and product trials

Get help