Group issue boards API

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

Every API call to group issue boards must be authenticated.

If a user is not a member of a group and the group is private, a GET request results in 404 status code.

List all group issue boards in a group

Lists issue boards in the given group.

GET /groups/:id/boards

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards"

Example response:

[
  {
    "id": 1,
    "name": "group issue board",
    "group": {
      "id": 5,
      "name": "Documentcloud",
      "web_url": "http://example.com/groups/documentcloud"
    },
    "milestone":   {
      "id": 12,
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
        "position" : 1
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
        "position" : 2
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
        "position" : 3
      }
    ]
  }
]

Users on GitLab Premium or Ultimate see different parameters, due to the ability to have multiple group boards.

Example response:

[
  {
    "id": 1,
    "name": "group issue board",
    "group": {
      "id": 5,
      "name": "Documentcloud",
      "web_url": "http://example.com/groups/documentcloud"
    },
    "milestone":   {
      "id": 12,
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
        "position" : 1
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
        "position" : 2
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
        "position" : 3
      }
    ]
  }
]

Single group issue board

Gets a single group issue board.

GET /groups/:id/boards/:board_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards/1"

Example response:

  {
    "id": 1,
    "name": "group issue board",
    "group": {
      "id": 5,
      "name": "Documentcloud",
      "web_url": "http://example.com/groups/documentcloud"
    },
    "milestone":   {
      "id": 12,
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
        "position" : 1
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
        "position" : 2
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
        "position" : 3
      }
    ]
  }

Users on GitLab Premium or Ultimate see different parameters, due to the ability to have multiple group issue boards.

Example response:

  {
    "id": 1,
    "name": "group issue board",
    "group": {
      "id": 5,
      "name": "Documentcloud",
      "web_url": "http://example.com/groups/documentcloud"
    },
    "milestone":   {
      "id": 12,
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
        "position" : 1
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
        "position" : 2
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
        "position" : 3
      }
    ]
  }

Create a group issue board

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Creates a group issue board.

POST /groups/:id/boards

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`name`	string	yes	The name of the new board.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards?name=newboard"

Example response:

  {
    "id": 1,
    "name": "newboard",
    "project": null,
    "lists" : [],
    "group": {
      "id": 5,
      "name": "Documentcloud",
      "web_url": "http://example.com/groups/documentcloud"
    },
    "milestone": null,
    "assignee" : null,
    "labels" : [],
    "weight" : null
  }

Update a group issue board

Updates a group issue board.

PUT /groups/:id/boards/:board_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.
`name`	string	no	The new name of the board.
`hide_backlog_list`	boolean	no	Hide the Open list.
`hide_closed_list`	boolean	no	Hide the Closed list.
`assignee_id`	integer	no	The assignee the board should be scoped to. Premium and Ultimate only.
`milestone_id`	integer	no	The milestone the board should be scoped to. Premium and Ultimate only.
`labels`	string	no	Comma-separated list of label names which the board should be scoped to. Premium and Ultimate only.
`weight`	integer	no	The weight range from 0 to 9, to which the board should be scoped to. Premium and Ultimate only.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards/1?name=new_name&milestone_id=44&assignee_id=1&labels=GroupLabel&weight=4"

Example response:

  {
    "id": 1,
    "project": null,
    "lists": [],
    "name": "new_name",
    "group": {
      "id": 5,
      "name": "Documentcloud",
      "web_url": "http://example.com/groups/documentcloud"
    },
    "milestone": {
      "id": 44,
      "iid": 1,
      "group_id": 5,
      "title": "Group Milestone",
      "description": "Group Milestone Desc",
      "state": "active",
      "created_at": "2018-07-03T07:15:19.271Z",
      "updated_at": "2018-07-03T07:15:19.271Z",
      "due_date": null,
      "start_date": null,
      "web_url": "http://example.com/groups/documentcloud/-/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": 11,
      "name": "GroupLabel",
      "color": "#428BCA",
      "description": ""
    }],
    "weight": 4
  }

Delete a group issue board

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Deletes a group issue board.

DELETE /groups/:id/boards/:board_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards/1"

List group issue board lists

Get a list of the board’s lists. Does not include open and closed lists

GET /groups/:id/boards/:board_id/lists

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards/1/lists"

Example response:

[
  {
    "id" : 1,
    "label" : {
      "name" : "Testing",
      "color" : "#F0AD4E",
      "description" : null
    },
    "position" : 1
  },
  {
    "id" : 2,
    "label" : {
      "name" : "Ready",
      "color" : "#FF0000",
      "description" : null
    },
    "position" : 2
  },
  {
    "id" : 3,
    "label" : {
      "name" : "Production",
      "color" : "#FF5F00",
      "description" : null
    },
    "position" : 3
  }
]

Single group issue board list

Get a single board list.

GET /groups/:id/boards/:board_id/lists/:list_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.
`list_id`	integer	yes	The ID of a board’s list.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1"

Example response:

{
  "id" : 1,
  "label" : {
    "name" : "Testing",
    "color" : "#F0AD4E",
    "description" : null
  },
  "position" : 1
}

New group issue board list

Creates an issue board list.

POST /groups/:id/boards/:board_id/lists

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.
`label_id`	integer	yes	The ID of a label.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/boards/12/lists?milestone_id=7"

Example response:

{
  "id": 9,
  "label": null,
  "position": 0,
  "milestone": {
    "id": 7,
    "iid": 3,
    "group_id": 12,
    "title": "Milestone with due date",
    "description": "",
    "state": "active",
    "created_at": "2017-09-03T07:16:28.596Z",
    "updated_at": "2017-09-03T07:16:49.521Z",
    "due_date": null,
    "start_date": null,
    "web_url": "https://gitlab.example.com/groups/issue-reproduce/-/milestones/3"
  }
}

Edit group issue board list

Updates an existing issue board list. This call is used to change list position.

PUT /groups/:id/boards/:board_id/lists/:list_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`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.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/group/5/boards/1/lists/1?position=2"

Example response:

{
  "id" : 1,
  "label" : {
    "name" : "Testing",
    "color" : "#F0AD4E",
    "description" : null
  },
  "position" : 1
}

Delete a group issue board list

Only for administrators and group owners. Deletes the board list in question.

DELETE /groups/:id/boards/:board_id/lists/:list_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`board_id`	integer	yes	The ID of a board.
`list_id`	integer	yes	The ID of a board’s list.

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards/1/lists/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

Group issue boards API

List all group issue boards in a group

Single group issue board

Create a group issue board

Update a group issue board

Delete a group issue board

List group issue board lists

Single group issue board list

New group issue board list

Edit group issue board list

Delete a group issue board list

Help & feedback

Docs

Product

Feature availability and product trials

Get help