broadcast_messages.md 5.27 KB
Newer Older
1
# Broadcast Messages API
2

3
> Introduced in GitLab 8.12.
4

5 6
Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md).

7
As of GitLab 12.8, GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:
8 9 10

- Guests will result in `401 Unauthorized`.
- Regular users will result in `403 Forbidden`.
11 12 13

## Get all broadcast messages

14 15 16
List all broadcast messages.

```text
17 18 19
GET /broadcast_messages
```

20 21
Example request:

22
```shell
23
curl https://gitlab.example.com/api/v4/broadcast_messages
24 25 26 27 28 29 30 31 32 33 34 35 36
```

Example response:

```json
[
    {
        "message":"Example broadcast message",
        "starts_at":"2016-08-24T23:21:16.078Z",
        "ends_at":"2016-08-26T23:21:16.080Z",
        "color":"#E75E40",
        "font":"#FFFFFF",
        "id":1,
37
        "active": false,
Nicolas Dular's avatar
Nicolas Dular committed
38
        "target_path": "*/welcome",
39 40
        "broadcast_type": "banner",
        "dismissable": false
41 42 43 44 45 46
    }
]
```

## Get a specific broadcast message

47 48 49
Get a specific broadcast message.

```text
50 51 52
GET /broadcast_messages/:id
```

53 54 55 56 57 58 59
Parameters:

| Attribute | Type    | Required | Description                          |
|:----------|:--------|:---------|:-------------------------------------|
| `id`      | integer | yes      | ID of broadcast message to retrieve. |

Example request:
60

61
```shell
62
curl https://gitlab.example.com/api/v4/broadcast_messages/1
63 64 65 66 67 68 69 70 71 72 73 74
```

Example response:

```json
{
    "message":"Deploy in progress",
    "starts_at":"2016-08-24T23:21:16.078Z",
    "ends_at":"2016-08-26T23:21:16.080Z",
    "color":"#cecece",
    "font":"#FFFFFF",
    "id":1,
75
    "active":false,
Nicolas Dular's avatar
Nicolas Dular committed
76
    "target_path": "*/welcome",
77 78
    "broadcast_type": "banner",
    "dismissable": false
79 80 81 82 83
}
```

## Create a broadcast message

84 85 86
Create a new broadcast message.

```text
87 88 89
POST /broadcast_messages
```

90
Parameters:
91

92 93 94 95 96 97 98 99 100 101
| Attribute       | Type     | Required | Description                                           |
|:----------------|:---------|:---------|:------------------------------------------------------|
| `message`       | string   | yes      | Message to display.                                   |
| `starts_at`     | datetime | no       | Starting time (defaults to current time).             |
| `ends_at`       | datetime | no       | Ending time (defaults to one hour from current time). |
| `color`         | string   | no       | Background color hex code.                            |
| `font`          | string   | no       | Foreground color hex code.                            |
| `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?                     |
102 103 104

Example request:

105
```shell
106
curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
107 108 109 110 111 112 113 114 115 116 117 118
```

Example response:

```json
{
    "message":"Deploy in progress",
    "starts_at":"2016-08-26T00:41:35.060Z",
    "ends_at":"2016-08-26T01:41:35.060Z",
    "color":"#cecece",
    "font":"#FFFFFF",
    "id":1,
119
    "active": true,
Nicolas Dular's avatar
Nicolas Dular committed
120 121
    "target_path": "*/welcome",
    "broadcast_type": "notification",
122
    "dismissable": false
123 124 125 126 127
}
```

## Update a broadcast message

128 129 130
Update an existing broadcast message.

```text
131 132 133
PUT /broadcast_messages/:id
```

134 135
Parameters:

136 137 138 139 140 141 142 143 144 145 146
| 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.                        |
| `ends_at`       | datetime | no       | Ending time.                          |
| `color`         | string   | no       | Background color hex code.            |
| `font`          | string   | no       | Foreground color hex code.            |
| `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?     |
147

148 149
Example request:

150
```shell
151
curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
152 153 154 155 156 157 158 159 160 161 162 163
```

Example response:

```json
{
    "message":"Update message",
    "starts_at":"2016-08-26T00:41:35.060Z",
    "ends_at":"2016-08-26T01:41:35.060Z",
    "color":"#000",
    "font":"#FFFFFF",
    "id":1,
164
    "active": true,
Nicolas Dular's avatar
Nicolas Dular committed
165 166
    "target_path": "*/welcome",
    "broadcast_type": "notification",
167
    "dismissable": false
168 169 170 171 172
}
```

## Delete a broadcast message

173 174
Delete a broadcast message.

175
```shell
176 177 178
DELETE /broadcast_messages/:id
```

179 180 181 182 183 184 185
Parameters:

| Attribute | Type    | Required | Description                        |
|:----------|:--------|:---------|:-----------------------------------|
| `id`      | integer | yes      | ID of broadcast message to delete. |

Example request:
186

187
```shell
188
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
189
```