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

3
> Introduced in GitLab 8.12.
4

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

The broadcast message API is only accessible to administrators. All requests by:

- 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 22
Example request:

```sh
23
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
```

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,
        "active": false
    }
]
```

## Get a specific broadcast message

44 45 46
Get a specific broadcast message.

```text
47 48 49
GET /broadcast_messages/:id
```

50 51 52 53 54 55 56
Parameters:

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

Example request:
57

58
```sh
59
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
```

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,
    "active":false
}
```

## Create a broadcast message

78 79 80
Create a new broadcast message.

```text
81 82 83
POST /broadcast_messages
```

84
Parameters:
85

86 87 88 89 90 91 92 93 94 95 96
| 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.                            |

Example request:

```sh
97
curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
```

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,
    "active": true
}
```

## Update a broadcast message

116 117 118
Update an existing broadcast message.

```text
119 120 121
PUT /broadcast_messages/:id
```

122 123 124 125 126 127 128 129 130 131
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.                     |
| `ends_at`   | datetime | no       | Ending time.                       |
| `color`     | string   | no       | Background color hex code.         |
| `font`      | string   | no       | Foreground color hex code.         |
132

133 134 135
Example request:

```sh
136
curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
```

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,
    "active": true
}
```

## Delete a broadcast message

155 156 157
Delete a broadcast message.

```sh
158 159 160
DELETE /broadcast_messages/:id
```

161 162 163 164 165 166 167
Parameters:

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

Example request:
168

169
```sh
170
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
171
```