Work item classification nodes

Last Update: 6/21/2017

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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team 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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas?api-version=1.0

Sample response

Status code: 200
{
  "id": 3568,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "area",
  "hasChildren": true,
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
}

Get the area tree with 2 levels of children

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas?$depth=2&api-version=1.0

Sample response

Status code: 200
{
  "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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices/Windows%20Phone"
        },
        {
          "id": 4484,
          "name": "Surface",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices/Surface"
        },
        {
          "id": 4485,
          "name": "iPhone",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices/iPhone"
        }
      ],
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Devices"
    },
    {
      "id": 4486,
      "name": "Website",
      "structureType": "area",
      "hasChildren": false,
      "url": "https://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Backend/Database"
        },
        {
          "id": 4489,
          "name": "Middle-tier",
          "structureType": "area",
          "hasChildren": false,
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Backend/Middle-tier"
        }
      ],
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Backend"
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
}

Sample code

Get the root iteration tree

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations?api-version=1.0

Sample response

Status code: 200
{
  "id": 3569,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "iteration",
  "hasChildren": true,
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
}

Get the iteration tree with 2 levels of children

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations?$depth=2&api-version=1.0

Sample response

Status code: 200
{
  "id": 3569,
  "name": "Fabrikam-Fiber-Git",
  "structureType": "iteration",
  "hasChildren": true,
  "children": [
    {
      "id": 3566,
      "name": "Release 3",
      "structureType": "iteration",
      "hasChildren": false,
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%203"
    },
    {
      "id": 3571,
      "name": "Release 2",
      "structureType": "iteration",
      "hasChildren": false,
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%202"
    },
    {
      "id": 3572,
      "name": "Release 4",
      "structureType": "iteration",
      "hasChildren": false,
      "url": "https://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201/Sprint%203"
        }
      ],
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Release%201"
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
}

Sample code

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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team 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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Web?api-version=1.0

Sample response

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

Sample code

Get an iteration

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Final%20Iteration?api-version=1.0

Sample response

Status code: 200
{
  "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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
}

Sample code

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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team 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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas?api-version=1.0
Content-Type: application/json
{
  "name": "Web"
}

Sample response

Status code: 201
{
  "id": 126391,
  "name": "Web",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Web"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Web"
}

Sample code

Create an iteration

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations?api-version=1.0
Content-Type: application/json
{
  "name": "Final Iteration",
  "attributes": {
    "startDate": "2014-10-27T00:00:00Z",
    "finishDate": "2014-10-31T00:00:00Z"
  }
}

Sample response

Status code: 201
{
  "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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Final%20Iteration"
}

Sample code

Update a classification node

PATCH https://{instance}/DefaultCollection/{project}/_apis/wit/classificationnodes/{nodeType}/{nodePath}?api-version={version}
Parameter Name Type Description
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team 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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Ultimate%20iteration?api-version=1.0
Content-Type: application/json
{
  "attributes": {
    "startDate": "2015-01-26T00:00:00Z",
    "finishDate": "2015-01-30T00:00:00Z"
  }
}

Sample response

Status code: 200
{
  "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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Ultimate%20iteration"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Ultimate%20iteration"
}

Sample code

Rename a classification node

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Web?api-version=1.0
Content-Type: application/json
{
  "name": "Website team"
}

Sample response

Status code: 200
{
  "id": 126391,
  "name": "Website team",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Website%20team"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team 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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Parent%20Area?api-version=1.0
Content-Type: application/json
{
  "id": 126391
}

Sample response

Status code: 200
{
  "id": 126391,
  "name": "Website team",
  "structureType": "area",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Parent%20Area/Website%20team"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Parent%20Area"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Areas/Parent%20Area/Website%20team"
}

Sample code

Move an iteration node

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Parent%20Iteration?api-version=1.0
Content-Type: application/json
{
  "id": 126392
}

Sample response

Status code: 200
{
  "id": 126392,
  "name": "Ultimate iteration",
  "structureType": "iteration",
  "hasChildren": false,
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Parent%20Iteration/Ultimate%20iteration"
    },
    "parent": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/classificationNodes/Iterations/Parent%20Iteration"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team 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://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/areas/Parent%20Area?$reclassifyId=3568&api-version=1.0

Sample response

Status code: 204

Sample code

Delete an iteration node

Sample request

DELETE https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/classificationNodes/iterations/Parent%20Iteration?$reclassifyId=3569&api-version=1.0

Sample response

Status code: 204

Sample code

Samples

Getting Started

If this is your first time using the REST API's or .Net Libraries, check out the geting 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.