Skip to content

GitLab

and though bugs are the bane of my existence, rest assured the wretched thing will get the best of care here

Project Issue Boards API

Every API call to 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 owned by the authenticated user 
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 owned by the authenticated user
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 owned by the authenticated user
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

Introduced in GitLab Starter 11.1.

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 owned by the authenticated user
board_id integer yes The ID of a board
name string no The new name of the board
assignee_id (STARTER) integer no The assignee the board should be scoped to
milestone_id (STARTER) integer no The milestone the board should be scoped to
labels (STARTER) string no Comma-separated list of label names which the board should be scoped to
weight (STARTER) integer no The weight range from 0 to 9, to which the board should be scoped to 
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": [],
      "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 owned by the authenticated user
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 owned by the authenticated user
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 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 
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 owned by the authenticated user
board_id integer yes The ID of a board
label_id integer no The ID of a label
assignee_id (PREMIUM) integer no The ID of a user
milestone_id (PREMIUM) integer no The ID of a milestone

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