broadcast_messages.md 3.8 KB
Newer Older
1
# Broadcast Messages API
2 3 4 5 6 7 8 9 10 11 12 13 14 15

> **Note:** This feature was introduced in GitLab 8.12.

The broadcast message API is only accessible to administrators. All requests by
guests will respond with `401 Unauthorized`, and all requests by normal users
will respond with `403 Forbidden`.

## Get all broadcast messages

```
GET /broadcast_messages
```

```bash
16
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
```

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

```
GET /broadcast_messages/:id
```

| Attribute   | Type     | Required | Description               |
| ----------- | -------- | -------- | ------------------------- |
| `id`        | integer  | yes      | Broadcast message ID      |

```bash
46
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
47 48 49 50 51 52 53 54 55 56 57 58 59 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

```
POST /broadcast_messages
```

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

```bash
78
curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
```

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

```
PUT /broadcast_messages/:id
```

| Attribute   | Type     | Required | Description               |
| ----------- | -------- | -------- | ------------------------- |
| `id`        | integer  | yes      | Broadcast message ID      |
| `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 |

```bash
111
curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
```

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

```
DELETE /broadcast_messages/:id
```

| Attribute   | Type     | Required | Description               |
| ----------- | -------- | -------- | ------------------------- |
| `id`        | integer  | yes      | Broadcast message ID      |

```bash
139
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
140
```