Project issue boards API

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

Every API call to issue boards must be authenticated.

If a user is not a member of a private project, a GET request on that project results in a 404 status code.

List project issue boards

Lists project issue boards in the given project.

GET /projects/:id/boards

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

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

Example response:

[
  {
    "id" : 1,
    "name": "board1",
    "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":   {
      "id": 12,
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
        "position" : 1,
        "max_issue_count": 0,
        "max_issue_weight": 0,
        "limit_metric": null
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
        "position" : 2,
        "max_issue_count": 0,
        "max_issue_weight": 0,
        "limit_metric":  null
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
        "position" : 3,
        "max_issue_count": 0,
        "max_issue_weight": 0,
        "limit_metric":  null
      }
    ]
  }
]

Another example response when no board has been activated or exist in the project:

[]

Show a single issue board

Get a single project issue board.

GET /projects/:id/boards/:board_id

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

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

Example response:

  {
    "id": 1,
    "name": "project issue board",
    "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":   {
      "id": 12,
      "title": "10.0"
    },
    "lists" : [
      {
        "id" : 1,
        "label" : {
          "name" : "Testing",
          "color" : "#F0AD4E",
          "description" : null
        },
        "position" : 1,
        "max_issue_count": 0,
        "max_issue_weight": 0,
        "limit_metric":  null
      },
      {
        "id" : 2,
        "label" : {
          "name" : "Ready",
          "color" : "#FF0000",
          "description" : null
        },
        "position" : 2,
        "max_issue_count": 0,
        "max_issue_weight": 0,
        "limit_metric":  null
      },
      {
        "id" : 3,
        "label" : {
          "name" : "Production",
          "color" : "#FF5F00",
          "description" : null
        },
        "position" : 3,
        "max_issue_count": 0,
        "max_issue_weight": 0,
        "limit_metric":  null
      }
    ]
  }

Create an issue board

Creates a project issue board.

POST /projects/:id/boards

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

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

Example response:

  {
    "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",
    "lists" : [],
    "group": null,
    "milestone": null,
    "assignee" : null,
    "labels" : [],
    "weight" : null
  }

Update an issue board

Updates a project issue board.

PUT /projects/:id/boards/:board_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project.
`board_id`	integer	yes	The ID of a board.
`name`	string	no	The new name of the board.
`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/projects/5/boards/1?name=new_name&milestone_id=43&assignee_id=1&labels=Doing&weight=4"

Example response:

  {
    "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": [], //deprecated, use `topics` instead
      "topics": [],
      "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
  }

Delete an issue board

Deletes a project issue board.

DELETE /projects/:id/boards/:board_id

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

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

List board lists in a project issue board

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

GET /projects/:id/boards/:board_id/lists

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

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

Example response:

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

Show a single board list

Get a single board list.

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

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project.
`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/projects/5/boards/1/lists/1"

Example response:

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

Create a board list

Creates a new issue board list.

POST /projects/:id/boards/:board_id/lists

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project.
`board_id`	integer	yes	The ID of a board.
`label_id`	integer	no	The ID of a label.
`assignee_id`	integer	no	The ID of a user. Premium and Ultimate only.
`milestone_id`	integer	no	The ID of a milestone. Premium and Ultimate only.

Label, assignee and milestone arguments are mutually exclusive, that is, only one of them are accepted in a request. Check the issue board documentation for more information regarding the required license for each list type.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists?label_id=5"

Example response:

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

Reorder a list in a board

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

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

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project.
`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/projects/5/boards/1/lists/1?position=2"

Example response:

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

Delete a board list from a board

Only for administrators and project owners. Deletes a board list.

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

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

Project issue boards API

List project issue boards

Show a single issue board

Create an issue board

Update an issue board

Delete an issue board

List board lists in a project issue board

Show a single board list

Create a board list

Reorder a list in a board

Delete a board list from a board

Help & feedback

Docs

Product

Feature availability and product trials

Get help