Work item classification nodes

Article
08/04/2016

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 = 1.0

All work items have an area and an iteration field. The values that these fields can have are defined in the classification hierarchies.

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

Get a list of classification nodes

GET https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/[{nodePath}]?api-version={version}[&$depth={int}]

Property	Type	Description
URL
instance	string	TFS server name ({server:port}).
project	string	Name or ID of a project that contains the classification nodes.
nodeType	enum {areas, iterations}	The type of classification node you are trying access.
nodePath	string	Path of the classification node.
Query
api-version	string	Version of the API to use.
$depth	int	Depth of children to retrieve.

Get the root area tree

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas?api-version=1.0

Sample response

{
  "id": 3568,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "area",
  "hasChildren": true,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
}

Get the area tree with 2 levels of children

#### Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas?$depth=2&api-version=1.0

Sample response

{
  "id": 3568,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "area",
  "hasChildren": true,
  "children": [
    {
      "id": 4482,
      "name": "Devices",
      "structureType": "area",
      "hasChildren": true,
      "children": [
        {
          "id": 4483,
          "name": "Windows Phone",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices/Windows%20Phone"
        },
        {
          "id": 4484,
          "name": "Surface",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices/Surface"
        },
        {
          "id": 4485,
          "name": "iPhone",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices/iPhone"
        }
      ],
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices"
    },
    {
      "id": 4486,
      "name": "Website",
      "structureType": "area",
      "hasChildren": false,
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Website"
    },
    {
      "id": 4487,
      "name": "Backend",
      "structureType": "area",
      "hasChildren": true,
      "children": [
        {
          "id": 4488,
          "name": "Database",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Backend/Database"
        },
        {
          "id": 4489,
          "name": "Middle-tier",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Backend/Middle-tier"
        }
      ],
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Backend"
    }
  ],
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
}

Sample code

C# (ListAreas method)

Get the root iteration tree

#### Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations?api-version=1.0

Sample response

{
  "id": 3569,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "iteration",
  "hasChildren": true,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
}

Get the iteration tree with 2 levels of children

#### Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations?$depth=2&api-version=1.0

Sample response

{
  "id": 3569,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "iteration",
  "hasChildren": true,
  "children": [
    {
      "id": 3566,
      "name": "Release 3",
      "structureType": "iteration",
      "hasChildren": false,
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%203"
    },
    {
      "id": 3571,
      "name": "Release 2",
      "structureType": "iteration",
      "hasChildren": false,
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%202"
    },
    {
      "id": 3572,
      "name": "Release 4",
      "structureType": "iteration",
      "hasChildren": false,
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%204"
    },
    {
      "id": 3576,
      "name": "Release 1",
      "structureType": "iteration",
      "hasChildren": true,
      "children": [
        {
          "id": 3564,
          "name": "Sprint 4",
          "structureType": "iteration",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%204"
        },
        {
          "id": 3565,
          "name": "Sprint 2",
          "structureType": "iteration",
          "hasChildren": false,
          "attributes": {
            "startDate": "2014-03-17T00:00:00Z",
            "finishDate": "2014-03-28T00:00:00Z"
          },
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%202"
        },
        {
          "id": 3567,
          "name": "Sprint 6",
          "structureType": "iteration",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%206"
        },
        {
          "id": 3573,
          "name": "Sprint 5",
          "structureType": "iteration",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%205"
        },
        {
          "id": 3574,
          "name": "Sprint 1",
          "structureType": "iteration",
          "hasChildren": false,
          "attributes": {
            "startDate": "2014-03-03T00:00:00Z",
            "finishDate": "2014-03-14T00:00:00Z"
          },
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%201"
        },
        {
          "id": 3575,
          "name": "Sprint 3",
          "structureType": "iteration",
          "hasChildren": false,
          "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%203"
        }
      ],
      "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201"
    }
  ],
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
}

Sample code

C# (ListIterations method)

Get a classification node

GET https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/{nodePath}?api-version={version}[&$depth={int}]

Parameter Name	Type	Description
URL
instance	string	TFS server name ({server:port}).
project	string	Name or ID of a project that contains the classification nodes.
nodeType	enum {areas, iterations}	The type of classification node you are trying access.
nodePath	string	Path of the classification node.
Query
api-version	string	Version of the API to use.
$depth	int	Depth of children to retrieve.

Get an area

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Web?api-version=1.0

Sample response

{
  "id": 126391,
  "identifier": "d5d98099-47ac-468a-9579-c059c90bf7c5",
  "name": "Web",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Web"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Web"
}

Sample code

C# (GetArea method)

Get an iteration

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Final%20Iteration?api-version=1.0

Sample response

{
  "id": 126392,
  "name": "Final Iteration",
  "structureType": "iteration",
  "hasChildren": false,
  "attributes": {
    "startDate": "2014-10-27T00:00:00Z",
    "finishDate": "2014-10-31T00:00:00Z"
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
}

Sample code

C# (GetIteration method)

Create a classification node

POST https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/{nodePath}?api-version={version}[&$depth={int}]

Parameter Name	Type	Description
URL
instance	string	TFS server name ({server:port}).
project	string	Name or ID of a project that contains the classification nodes.
nodeType	enum {areas, iterations}	The type of classification node you are trying access.
nodePath	string	Path of the classification nodes.
Query
api-version	string	Version of the API to use.
Body
name	string	Name of the classification node.
attributes	array of name/value pairs	Additional attributes of the node. E.g. startDate and finishDate for iterations.

Create an area

Sample request

POST https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas?api-version=1.0

{
  "name": "Web"
}

Sample response

{
  "id": 126391,
  "name": "Web",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Web"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Web"
}

Sample code

C# (CreateArea method)

Create an iteration

Sample request

POST https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations?api-version=1.0

{
  "name": "Final Iteration",
  "attributes": {
    "startDate": "2014-10-27T00:00:00Z",
    "finishDate": "2014-10-31T00:00:00Z"
  }
}

Sample response

{
  "id": 126392,
  "name": "Final Iteration",
  "structureType": "iteration",
  "hasChildren": false,
  "attributes": {
    "startDate": "2014-10-27T00:00:00Z",
    "finishDate": "2014-10-31T00:00:00Z"
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
}

Sample code

C# (CreateIteration method)

Update a classification node

PATCH https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/{nodePath}?api-version={version}

Parameter Name	Type	Description
URL
instance	string	TFS server name ({server:port}).
project	string	Name or ID of a project that contains the classification nodes.
nodeType	enum {areas, iterations}	The type of classification node you are trying access.
nodePath	string	Path of the classification nodes.
Query
api-version	string	Version of the API to use.
Body
name	string	Name of the classification node.
attributes	array of name/value pairs	Additional attributes of the node. E.g. startDate and finishDate for iterations.

Update iteration dates

Start and end dates for iterations can be accessed and set through the startDate and finishDate attributes on iteration nodes.

Sample request

PATCH https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Ultimate%20iteration?api-version=1.0

{
  "attributes": {
    "startDate": "2015-01-26T00:00:00Z",
    "finishDate": "2015-01-30T00:00:00Z"
  }
}

Sample response

{
  "id": 126392,
  "name": "Ultimate iteration",
  "structureType": "iteration",
  "hasChildren": false,
  "attributes": {
    "startDate": "2015-01-26T00:00:00Z",
    "finishDate": "2015-01-30T00:00:00Z"
  },
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Ultimate%20iteration"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Ultimate%20iteration"
}

Sample code

C# (UpdateIterationDates method)

Rename a classification node

Sample request

PATCH https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Web?api-version=1.0

{
  "name": "Website team"
}

Sample response

{
  "id": 126391,
  "name": "Website team",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Website%20team"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Website%20team"
}

Sample code

Move a classification node

POST https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/{targetNodeName}?api-version={version}

Parameter Name	Type	Description
URL
instance	string	TFS server name ({server:port}).
project	string	Name or ID of a project that contains the classification nodes.
nodeType	enum {areas, iterations}	The type of classification node you are trying access.
targetNodePath	string	Path of the target parent classification node.
Query
api-version	string	Version of the API to use.
Body
id	int	ID of the node being moved.

Move an area node

Sample request

POST https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Parent%20Area?api-version=1.0

{
  "id": 126391
}

Sample response

{
  "id": 126391,
  "name": "Website team",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Parent%20Area/Website%20team"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Parent%20Area"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Parent%20Area/Website%20team"
}

Sample code

C# (MoveArea method)

Move an iteration node

Sample request

POST https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Parent%20Iteration?api-version=1.0

{
  "id": 126392
}

Sample response

{
  "id": 126392,
  "name": "Ultimate iteration",
  "structureType": "iteration",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Parent%20Iteration/Ultimate%20iteration"
    },
    "parent": {
      "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Parent%20Iteration"
    }
  },
  "url": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Parent%20Iteration/Ultimate%20iteration"
}

Delete a classification node

DELETE https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/{nodePath}?api-version={version}[?$reclassifyId={reclassifyId}]

Parameter Name	Type	Description
URL
instance	string	TFS server name ({server:port}).
project	string	Name or ID of a project that contains the classification nodes.
nodeType	enum {areas, iterations}	The type of classification node you are trying access.
nodePath	string	Path of the classification nodes.
Query
api-version	string	Version of the API to use.
reclassifyId	string	ID of the node where work items of the deleted node are moved.

Delete an area node

Sample request

DELETE https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Parent%20Area?$reclassifyId=3568&api-version=1.0

Sample code

C# (DeleteArea method)

Delete an iteration node

Sample request

DELETE https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Parent%20Iteration?$reclassifyId=3569&api-version=1.0

Sample code

C# (DeleteIteration method)

Samples

Getting Started

If this is your first time using the REST API's or .NET Libraries, check out the getting started sample first.

All sample source code can be found in our GitHub repo.

Get Full Area or Iteration Tree

Get the full tree of area paths. You can do the same with iterations by changing the type to Iterations.

C# (GetFullTree method)

Share via

Work item classification nodes

Get a list of classification nodes

Get the root area tree

Sample request

Sample response

Get the area tree with 2 levels of children

Sample response

Sample code

Get the root iteration tree

Sample response

Get the iteration tree with 2 levels of children

Sample response

Sample code

Get a classification node

Get an area

Sample request

Sample response

Sample code

Get an iteration

Sample request

Sample response

Sample code

Create a classification node

Create an area

Sample request

Sample response

Sample code

Create an iteration

Sample request

Sample response

Sample code

Update a classification node

Update iteration dates

Sample request

Sample response

Sample code

Rename a classification node

Sample request

Sample response

Sample code

Move a classification node

Move an area node

Sample request

Sample response

Sample code

Move an iteration node

Sample request

Sample response

Delete a classification node

Delete an area node

Sample request

Sample code

Delete an iteration node

Sample request

Sample code

Samples

Getting Started

Get Full Area or Iteration Tree

Additional resources