boards.md 13.7 KB
Newer Older
1 2 3
---
stage: Plan
group: Project Management
4
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5 6
---

7
# Project Issue Boards API
André Guedes's avatar
André Guedes committed
8 9 10

Every API call to boards must be authenticated.

11 12
If a user is not a member of a private project,
a `GET` request on that project results in a `404` status code.
André Guedes's avatar
André Guedes committed
13

14
## List project issue boards
André Guedes's avatar
André Guedes committed
15

16
Lists project issue boards in the given project.
André Guedes's avatar
André Guedes committed
17

18
```plaintext
André Guedes's avatar
André Guedes committed
19 20 21 22 23
GET /projects/:id/boards
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Felipe's avatar
Felipe committed
24
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
André Guedes's avatar
André Guedes committed
25

26
```shell
Greg Myers's avatar
Greg Myers committed
27
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards"
André Guedes's avatar
André Guedes committed
28 29 30 31 32 33 34 35
```

Example response:

```json
[
  {
    "id" : 1,
36
    "name": "board1",
Felipe's avatar
Felipe committed
37 38 39 40 41 42 43 44 45 46
    "project": {
      "id": 5,
      "name": "Diaspora Project Site",
      "name_with_namespace": "Diaspora / Diaspora Project Site",
      "path": "diaspora-project-site",
      "path_with_namespace": "diaspora/diaspora-project-site",
      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
      "web_url": "http://example.com/diaspora/diaspora-project-site"
    },
    "milestone":   {
47
      "id": 12,
Felipe's avatar
Felipe committed
48 49
      "title": "10.0"
    },
André Guedes's avatar
André Guedes committed
50 51 52 53 54 55 56 57
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
Patrick Derichs's avatar
Patrick Derichs committed
58
        "position" : 1,
59
        "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
60 61
        "max_issue_weight": 0,
        "limit_metric": null
André Guedes's avatar
André Guedes committed
62 63 64 65 66 67 68 69
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
Patrick Derichs's avatar
Patrick Derichs committed
70
        "position" : 2,
71
        "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
72 73
        "max_issue_weight": 0,
        "limit_metric":  null
André Guedes's avatar
André Guedes committed
74 75 76 77 78 79 80 81
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
Patrick Derichs's avatar
Patrick Derichs committed
82
        "position" : 3,
83
        "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
84 85
        "max_issue_weight": 0,
        "limit_metric":  null
André Guedes's avatar
André Guedes committed
86 87 88 89 90 91
      }
    ]
  }
]
```

92
Another example response when no board has been activated or exist in the project:
Felipe's avatar
Felipe committed
93

94 95 96 97 98 99 100
```json
[]
```

## Show a single issue board

Get a single project issue board.
Felipe's avatar
Felipe committed
101

102
```plaintext
Felipe's avatar
Felipe committed
103 104 105 106 107 108 109 110
GET /projects/:id/boards/:board_id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |

111
```shell
Greg Myers's avatar
Greg Myers committed
112
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1"
Felipe's avatar
Felipe committed
113 114 115 116 117 118 119
```

Example response:

```json
  {
    "id": 1,
120
    "name": "project issue board",
Felipe's avatar
Felipe committed
121 122 123 124 125 126 127 128 129 130
    "project": {
      "id": 5,
      "name": "Diaspora Project Site",
      "name_with_namespace": "Diaspora / Diaspora Project Site",
      "path": "diaspora-project-site",
      "path_with_namespace": "diaspora/diaspora-project-site",
      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
      "web_url": "http://example.com/diaspora/diaspora-project-site"
    },
    "milestone":   {
131
      "id": 12,
Felipe's avatar
Felipe committed
132 133 134 135 136 137 138 139 140 141
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
Patrick Derichs's avatar
Patrick Derichs committed
142
        "position" : 1,
143
        "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
144 145
        "max_issue_weight": 0,
        "limit_metric":  null
Felipe's avatar
Felipe committed
146 147 148 149 150 151 152 153
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
Patrick Derichs's avatar
Patrick Derichs committed
154
        "position" : 2,
155
        "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
156 157
        "max_issue_weight": 0,
        "limit_metric":  null
Felipe's avatar
Felipe committed
158 159 160 161 162 163 164 165
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
Patrick Derichs's avatar
Patrick Derichs committed
166
        "position" : 3,
167
        "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
168 169
        "max_issue_weight": 0,
        "limit_metric":  null
Felipe's avatar
Felipe committed
170 171 172 173 174
      }
    ]
  }
```

175
## Create an issue board
176

177
Creates a project issue board.
178

179
```plaintext
180 181 182 183 184 185 186 187
POST /projects/:id/boards
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the new board |

188
```shell
Greg Myers's avatar
Greg Myers committed
189
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards?name=newboard"
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
```

Example response:

```json
  {
    "id": 1,
    "project": {
      "id": 5,
      "name": "Diaspora Project Site",
      "name_with_namespace": "Diaspora / Diaspora Project Site",
      "path": "diaspora-project-site",
      "path_with_namespace": "diaspora/diaspora-project-site",
      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
      "web_url": "http://example.com/diaspora/diaspora-project-site"
    },
    "name": "newboard",
207 208 209 210 211 212
    "lists" : [],
    "group": null,
    "milestone": null,
    "assignee" : null,
    "labels" : [],
    "weight" : null
213 214 215
  }
```

216
## Update an issue board
217

218
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5954) in GitLab 11.1.
219

220
Updates a project issue board.
221

222
```plaintext
223 224 225
PUT /projects/:id/boards/:board_id
```

226 227 228 229 230
| Attribute                    | Type           | Required | Description |
| ---------------------------- | -------------- | -------- | ----------- |
| `id`                         | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id`                   | integer        | yes      | The ID of a board |
| `name`                       | string         | no       | The new name of the board |
231 232 233 234
| `assignee_id` **(PREMIUM)**  | integer        | no       | The assignee the board should be scoped to |
| `milestone_id` **(PREMIUM)** | integer        | no       | The milestone the board should be scoped to |
| `labels` **(PREMIUM)**       | string         | no       | Comma-separated list of label names which the board should be scoped to |
| `weight` **(PREMIUM)**       | integer        | no       | The weight range from 0 to 9, to which the board should be scoped to |
235

236
```shell
Greg Myers's avatar
Greg Myers committed
237
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1?name=new_name&milestone_id=43&assignee_id=1&labels=Doing&weight=4"
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
```

Example response:

```json
  {
    "id": 1,
    "project": {
      "id": 5,
      "name": "Diaspora Project Site",
      "name_with_namespace": "Diaspora / Diaspora Project Site",
      "path": "diaspora-project-site",
      "path_with_namespace": "diaspora/diaspora-project-site",
      "created_at": "2018-07-03T05:48:49.982Z",
      "default_branch": null,
      "tag_list": [],
      "ssh_url_to_repo": "ssh://user@example.com/diaspora/diaspora-project-site.git",
      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
      "web_url": "http://example.com/diaspora/diaspora-project-site",
      "readme_url": null,
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "last_activity_at": "2018-07-03T05:48:49.982Z"
    },
    "lists": [],
    "name": "new_name",
    "group": null,
    "milestone": {
      "id": 43,
      "iid": 1,
      "project_id": 15,
      "title": "Milestone 1",
      "description": "Milestone 1 desc",
      "state": "active",
      "created_at": "2018-07-03T06:36:42.618Z",
      "updated_at": "2018-07-03T06:36:42.618Z",
      "due_date": null,
      "start_date": null,
      "web_url": "http://example.com/root/board1/milestones/1"
    },
    "assignee": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
      "web_url": "http://example.com/root"
    },
    "labels": [{
      "id": 10,
      "name": "Doing",
      "color": "#5CB85C",
      "description": null
    }],
    "weight": 4
  }
```

297
## Delete an issue board
298

299
Deletes a project issue board.
300

301
```plaintext
302 303 304 305 306 307 308 309
DELETE /projects/:id/boards/:board_id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |

310
```shell
Greg Myers's avatar
Greg Myers committed
311
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1"
312 313
```

314
## List board lists in a project issue board
André Guedes's avatar
André Guedes committed
315 316

Get a list of the board's lists.
317
Does not include `open` and `closed` lists.
André Guedes's avatar
André Guedes committed
318

319
```plaintext
André Guedes's avatar
André Guedes committed
320 321 322 323 324
GET /projects/:id/boards/:board_id/lists
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Felipe's avatar
Felipe committed
325 326
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
André Guedes's avatar
André Guedes committed
327

328
```shell
Greg Myers's avatar
Greg Myers committed
329
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists"
André Guedes's avatar
André Guedes committed
330 331 332 333 334 335 336 337 338 339 340 341 342
```

Example response:

```json
[
  {
    "id" : 1,
    "label" : {
      "name" : "Testing",
      "color" : "#F0AD4E",
      "description" : null
    },
Patrick Derichs's avatar
Patrick Derichs committed
343
    "position" : 1,
344
    "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
345 346
    "max_issue_weight": 0,
    "limit_metric":  null
André Guedes's avatar
André Guedes committed
347 348 349 350 351 352 353 354
  },
  {
    "id" : 2,
    "label" : {
      "name" : "Ready",
      "color" : "#FF0000",
      "description" : null
    },
Patrick Derichs's avatar
Patrick Derichs committed
355
    "position" : 2,
356
    "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
357 358
    "max_issue_weight": 0,
    "limit_metric":  null
André Guedes's avatar
André Guedes committed
359 360 361 362 363 364 365 366
  },
  {
    "id" : 3,
    "label" : {
      "name" : "Production",
      "color" : "#FF5F00",
      "description" : null
    },
Patrick Derichs's avatar
Patrick Derichs committed
367
    "position" : 3,
368
    "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
369 370
    "max_issue_weight": 0,
    "limit_metric":  null
André Guedes's avatar
André Guedes committed
371 372 373 374
  }
]
```

375
## Show a single board list
André Guedes's avatar
André Guedes committed
376 377 378

Get a single board list.

379
```plaintext
André Guedes's avatar
André Guedes committed
380 381 382 383 384
GET /projects/:id/boards/:board_id/lists/:list_id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Felipe's avatar
Felipe committed
385 386 387
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
| `list_id`| integer | yes | The ID of a board's list |
André Guedes's avatar
André Guedes committed
388

389
```shell
Greg Myers's avatar
Greg Myers committed
390
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1"
André Guedes's avatar
André Guedes committed
391 392 393 394 395 396 397 398 399 400 401 402
```

Example response:

```json
{
  "id" : 1,
  "label" : {
    "name" : "Testing",
    "color" : "#F0AD4E",
    "description" : null
  },
Patrick Derichs's avatar
Patrick Derichs committed
403
  "position" : 1,
404
  "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
405 406
  "max_issue_weight": 0,
  "limit_metric":  null
André Guedes's avatar
André Guedes committed
407 408 409
}
```

410
## Create a board list
André Guedes's avatar
André Guedes committed
411

412
Creates a new issue board list.
André Guedes's avatar
André Guedes committed
413

414
```plaintext
André Guedes's avatar
André Guedes committed
415 416 417 418 419
POST /projects/:id/boards/:board_id/lists
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Felipe's avatar
Felipe committed
420 421
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
422
| `label_id` | integer | no | The ID of a label |
423 424
| `assignee_id` **(PREMIUM)** | integer | no | The ID of a user |
| `milestone_id` **(PREMIUM)** | integer | no | The ID of a milestone |
425

426
NOTE:
427 428
Label, assignee and milestone arguments are mutually exclusive,
that is, only one of them are accepted in a request.
429
Check the [Issue Board documentation](../user/project/issue_board.md)
430
for more information regarding the required license for each list type.
André Guedes's avatar
André Guedes committed
431

432
```shell
Greg Myers's avatar
Greg Myers committed
433
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists?label_id=5"
André Guedes's avatar
André Guedes committed
434 435 436 437 438 439 440 441 442 443 444 445
```

Example response:

```json
{
  "id" : 1,
  "label" : {
    "name" : "Testing",
    "color" : "#F0AD4E",
    "description" : null
  },
Patrick Derichs's avatar
Patrick Derichs committed
446
  "position" : 1,
447
  "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
448 449
  "max_issue_weight": 0,
  "limit_metric":  null
André Guedes's avatar
André Guedes committed
450 451 452
}
```

453
## Reorder a list in a board
André Guedes's avatar
André Guedes committed
454

455
Updates an existing issue board list. This call is used to change list position.
André Guedes's avatar
André Guedes committed
456

457
```plaintext
André Guedes's avatar
André Guedes committed
458 459 460 461 462
PUT /projects/:id/boards/:board_id/lists/:list_id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Felipe's avatar
Felipe committed
463 464 465 466
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
| `list_id` | integer | yes | The ID of a board's list |
| `position` | integer | yes | The position of the list |
André Guedes's avatar
André Guedes committed
467

468
```shell
Greg Myers's avatar
Greg Myers committed
469
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1?position=2"
André Guedes's avatar
André Guedes committed
470 471 472 473 474 475 476 477 478 479 480 481
```

Example response:

```json
{
  "id" : 1,
  "label" : {
    "name" : "Testing",
    "color" : "#F0AD4E",
    "description" : null
  },
Patrick Derichs's avatar
Patrick Derichs committed
482
  "position" : 1,
483
  "max_issue_count": 0,
Patrick Derichs's avatar
Patrick Derichs committed
484 485
  "max_issue_weight": 0,
  "limit_metric":  null
André Guedes's avatar
André Guedes committed
486 487 488
}
```

489
## Delete a board list from a board
André Guedes's avatar
André Guedes committed
490

491
Only for administrators and project owners. Deletes a board list.
André Guedes's avatar
André Guedes committed
492

493
```plaintext
André Guedes's avatar
André Guedes committed
494 495 496 497 498
DELETE /projects/:id/boards/:board_id/lists/:list_id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Felipe's avatar
Felipe committed
499 500 501
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
| `list_id` | integer | yes | The ID of a board's list |
André Guedes's avatar
André Guedes committed
502

503
```shell
Greg Myers's avatar
Greg Myers committed
504
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1"
André Guedes's avatar
André Guedes committed
505
```