Columns on a Kanban board

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 2.0-preview.1

If you haven't already, look at the information on getting started with these APIs.

Get columns on a board

GET https://{instance}/defaultcollection/{project}/{team}/_apis/work/boards/{board}/columns?api-version={api-version}

Parameter	Type	Default Value	Notes
URL
instance	string		TFS server name ({server:port}).
project	string		Name or ID of a project.
team	string	Project's default team Id	Name or ID of a team within the project.
board	string		Name or ID of the specific board.
Query
api-version	string		Version of the API to use.

By ID

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam/Fabrikam%20Team/_apis/work/boards/41688c28-a3fc-4811-977d-247a33f18a00/columns?api-version=2.0-preview

Sample response

{
  "count": 4,
  "value": [
    {
      "id": "12eed5fb-8af3-47bb-9d2a-058fbe7e1196",
      "name": "New",
      "itemLimit": 0,
      "stateMappings": {
        "Product Backlog Item": "New",
        "Bug": "New"
      },
      "columnType": "incoming"
    },
    {
      "id": "5f72391d-af1c-4754-9459-23138eba13e3",
      "name": "Approved",
      "itemLimit": 5,
      "stateMappings": {
        "Product Backlog Item": "Approved",
        "Bug": "Approved"
      },
      "isSplit": false,
      "description": "",
      "columnType": "inProgress"
    },
    {
      "id": "4ddb0875-547e-4d2c-b36a-4ea9a1f7be41",
      "name": "Committed",
      "itemLimit": 5,
      "stateMappings": {
        "Product Backlog Item": "Committed",
        "Bug": "Committed"
      },
      "isSplit": false,
      "description": "",
      "columnType": "inProgress"
    },
    {
      "id": "1016c466-6cb6-4bf9-9a19-4e9cc88204df",
      "name": "Done",
      "itemLimit": 0,
      "stateMappings": {
        "Product Backlog Item": "Done",
        "Bug": "Done"
      },
      "columnType": "outgoing"
    }
  ]
}

By name

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam/Fabrikam%20Team/_apis/work/boards/Backlog%20items/columns?api-version=2.0-preview

Sample response

{
  "count": 4,
  "value": [
    {
      "id": "12eed5fb-8af3-47bb-9d2a-058fbe7e1196",
      "name": "New",
      "itemLimit": 0,
      "stateMappings": {
        "Product Backlog Item": "New",
        "Bug": "New"
      },
      "columnType": "incoming"
    },
    {
      "id": "5f72391d-af1c-4754-9459-23138eba13e3",
      "name": "Approved",
      "itemLimit": 5,
      "stateMappings": {
        "Product Backlog Item": "Approved",
        "Bug": "Approved"
      },
      "isSplit": false,
      "description": "",
      "columnType": "inProgress"
    },
    {
      "id": "4ddb0875-547e-4d2c-b36a-4ea9a1f7be41",
      "name": "Committed",
      "itemLimit": 5,
      "stateMappings": {
        "Product Backlog Item": "Committed",
        "Bug": "Committed"
      },
      "isSplit": false,
      "description": "",
      "columnType": "inProgress"
    },
    {
      "id": "1016c466-6cb6-4bf9-9a19-4e9cc88204df",
      "name": "Done",
      "itemLimit": 0,
      "stateMappings": {
        "Product Backlog Item": "Done",
        "Bug": "Done"
      },
      "columnType": "outgoing"
    }
  ]
}

Update columns on a board

Allow user to update or delete an existing board column, or add a new column to the board.

PUT https://{instance}/defaultcollection/{project}/{team}/_apis/work/boards/{board}/columns?api-version={api-version}

Parameter	Type	Default Value	Notes
URL
instance	string		TFS server name ({server:port}).
project	string		Name or ID of a project.
team	string	Project's default team Id	Name or ID of a team within the project.
board	string		Name or ID of the specific board.
Query
api-version	string		Version of the API to use.
Body
columns.id	string	null	ID of a column, required for update. The new columns have ID of null. (Optional)
columns.name	string		Name of a column.
columns.itemLimit	int	0	For first and last column, this indicates the max number of items we display on the board. For other columns, this indicates the WIP limit.
columns.stateMappings	name/value pair		The state of the item that should be mapping to the column.
columns.isSplit	boolean	false	Indicates if the column should be split, not applicable for first and last columns.
columns.description	string	empty string	Definition of done for a column, not applicable for first and last columns.

Assumption:

1. Column order is determined by the order of element presenting in post data.
2. If a column ID is null, we treat it as a new column.
3. Any existing column that is NOT on the post data will be deleted.

For each column, all applicable parameters are required even if no change. If any of the field values are not valid, the board will not be updated.

When update fails, it will return bad request. Four exceptions can be thrown depending on the errors:

1. DeletedBoardColumnIsNotEmptyException
2. BoardValidationFailureException
3. BoardUpdateFailureException
4. NoPermissionUpdateBoardColumnsException

Status code: 400

{
    "$id": "1",
    "innerException": null,
    "message": "TF401017: You cannot delete column: InProgress.  This column has 1 items in it. You must first move the items to another column, then try deleting the column again..",
    "typeName": "Microsoft.TeamFoundation.Agile.Server.Exceptions.DeletedBoardColumnIsNotEmptyException, MMicrosoft.TeamFoundation.Agile.Server, Version=14.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a",
    "typeKey": "DeletedBoardColumnIsNotEmptyException",
    "errorCode": 0,
    "eventId": 3000
}

Sample request

PUT https://mytfsserver/DefaultCollection/Fabrikam/Fabrikam%20Team/_apis/work/boards/Backlog%20items/columns?api-version=2.0-preview

[
  {
    "id": "12eed5fb-8af3-47bb-9d2a-058fbe7e1196",
    "name": "New",
    "itemLimit": 0,
    "stateMappings": {
      "Product Backlog Item": "New",
      "Bug": "New"
    },
    "columnType": "incoming"
  },
  {
    "id": "5f72391d-af1c-4754-9459-23138eba13e3",
    "name": "Approved",
    "itemLimit": 5,
    "stateMappings": {
      "Product Backlog Item": "Approved",
      "Bug": "Approved"
    },
    "isSplit": false,
    "description": "",
    "columnType": "inProgress"
  },
  {
    "id": "4ddb0875-547e-4d2c-b36a-4ea9a1f7be41",
    "name": "Committed",
    "itemLimit": 5,
    "stateMappings": {
      "Product Backlog Item": "Committed",
      "Bug": "Committed"
    },
    "isSplit": false,
    "description": "",
    "columnType": "inProgress"
  },
  {
    "id": "1016c466-6cb6-4bf9-9a19-4e9cc88204df",
    "name": "Done",
    "itemLimit": 0,
    "stateMappings": {
      "Product Backlog Item": "Done",
      "Bug": "Done"
    },
    "columnType": "outgoing"
  }
]

Sample response

{
  "count": 4,
  "value": [
    {
      "id": "12eed5fb-8af3-47bb-9d2a-058fbe7e1196",
      "name": "New",
      "itemLimit": 0,
      "stateMappings": {
        "Product Backlog Item": "New",
        "Bug": "New"
      },
      "columnType": "incoming"
    },
    {
      "id": "5f72391d-af1c-4754-9459-23138eba13e3",
      "name": "Approved",
      "itemLimit": 5,
      "stateMappings": {
        "Product Backlog Item": "Approved",
        "Bug": "Approved"
      },
      "isSplit": false,
      "description": "",
      "columnType": "inProgress"
    },
    {
      "id": "4ddb0875-547e-4d2c-b36a-4ea9a1f7be41",
      "name": "Committed",
      "itemLimit": 5,
      "stateMappings": {
        "Product Backlog Item": "Committed",
        "Bug": "Committed"
      },
      "isSplit": false,
      "description": "",
      "columnType": "inProgress"
    },
    {
      "id": "1016c466-6cb6-4bf9-9a19-4e9cc88204df",
      "name": "Done",
      "itemLimit": 0,
      "stateMappings": {
        "Product Backlog Item": "Done",
        "Bug": "Done"
      },
      "columnType": "outgoing"
    }
  ]
}

Get available board columns

GET https://{instance}/defaultcollection/[{project}/]_apis/work/boardcolumns/?api-version={api-version}

Parameter	Type	Default Value	Notes
URL
instance	string		TFS server name ({server:port}).
project	string		Name or ID of a project.
Query
api-version	string		Version of the API to use.

For a project

Sample request

GET mytfsserver/defaultcollection/fabrikam/_apis/work/boardColumns/?api-version=2.0-preview.1

Sample response

{
  "count": 4,
  "value": [
    {
      "name": "Active"
    },
    {
      "name": "Closed"
    },
    {
      "name": "New"
    },
    {
      "name": "Resolved"
    }
  ]
}

For a collection

Sample request

GET mytfsserver/defaultcollection/_apis/work/boardColumns/?api-version=2.0-preview.1

Sample response

{
  "count": 8,
  "value": [
    {
      "name": "Active"
    },
    {
      "name": "Closed"
    },
    {
      "name": "Development"
    },
    {
      "name": "Done"
    },
    {
      "name": "New"
    },
    {
      "name": "Ready"
    },
    {
      "name": "Resolved"
    },
    {
      "name": "Test"
    }
  ]
}