Recycle bin

Last Update: 7/14/2017

api-version = 3.0-preview

The recycle bin contains all work items that have been deleted. They can be restored or permanently destroyed.

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

Get list of ids for all deleted items in the recycle bin

GET https://{instance}/DefaultCollection/{project}_apis/wit/recycleBin?api-version={version}
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project of the deleted work items
Query
api-version string Version of the API to use.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/recyclebin?api-version=3.0-preview

Sample response

Status code: 200
[
  {
    "id": "92",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/92"
  },
  {
    "id": "93",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/93"
  },
  {
    "id": "102",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/102"
  }
]

Sample code

Get a deleted item in the recycle bin

GET https://{instance}/DefaultCollection/{project}/_apis/wit/recyclebin/{id}?api-version={version}
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project of the deleted work items
id int ID of the deleted item
Query
api-version string Version of the API to use.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recyclebin/72?api-version=1.0

Sample response

Status code: 200
{
  "id": "72",
  "type": "WorkItem",
  "Name": "72:First Workitem",
  "Project": "Fabrikam-Fiber-Git",
  "DeletedDate": "2015-01-07T18:13:01.807Z",
  "DeletedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/72?api-version=1.0",
  "resource": {
    "id": 72,
    "rev": 1,
    "fields": {
      "System.AreaPath": "Fabrikam-Fiber-Git",
      "System.TeamProject": "Fabrikam-Fiber-Git",
      "System.IterationPath": "Fabrikam-Fiber-Git",
      "System.WorkItemType": "Product Backlog Item",
      "System.State": "New",
      "System.Reason": "New backlog item",
      "System.CreatedDate": "2015-01-07T18:13:01.807Z",
      "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
      "System.ChangedDate": "2015-01-07T18:13:01.807Z",
      "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
      "System.Title": "First Workitem",
      "Microsoft.VSTS.Scheduling.Effort": 8,
      "WEF_6CB513B6E70E43499D9FC94E5BBFB784_Kanban.Column": "New",
      "System.Description": "Our authorization logic needs to allow for users with Microsoft accounts (formerly Live Ids) - http://msdn.microsoft.com/en-us/library/live/hh826547.aspx"
    },
    "_links": {
      "self": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/72"
      },
      "workItemUpdates": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/72/updates"
      },
      "workItemRevisions": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/72/revisions"
      },
      "workItemHistory": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/72/history"
      },
      "html": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=72"
      },
      "workItemType": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Product%20Backlog%20Item"
      },
      "fields": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
      }
    },
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/72"
  }
}

Sample code

Get multiple deleted items in the recycle bin

GET https://{instance}/DefaultCollection/{project}/_apis/wit/recyclebin?ids={ids}&api-version={version}
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project of the deleted work items
ids string A comma-separated list of up to 200 IDs of the deleted work items to get.
Query
api-version string Version of the API to use.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/recyclebin?ids=92,93,102&api-version=3.0-preview

Sample response

Status code: 200
[
  {
    "id": "92",
    "code": 200,
    "type": "Bug",
    "name": "Bug 92",
    "project": "My Project",
    "deletedDate": "1/31/2017 9:21:14 PM",
    "deletedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/92"
  },
  {
    "id": "93",
    "code": 200,
    "type": "User Story",
    "name": "User Story 93",
    "project": "My Project",
    "deletedDate": "1/31/2017 9:31:00 PM",
    "deletedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/93"
  },
  {
    "id": "102",
    "code": 200,
    "type": "Bug",
    "name": "Bug 102",
    "project": "My Project",
    "deletedDate": "12/30/2016 8:25:15 PM",
    "deletedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recycleBin/102"
  }
]

Sample code

Restore a work item

PATCH https://{instance}/DefaultCollection/_apis/wit/recyclebin/{id}?api-version={version}
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
id int ID of the deleted item
Query
api-version string Version of the API to use.
Body
IsDeleted boolean Value of the IsDeleted field (should be set to false for restoring work items.

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recyclebin/403?api-version=3.0-preview
Content-Type: application/json
{
  "IsDeleted": false
}

Sample response

Status code: 200
{
  "id": 403,
  "code": 200,
  "type": "Bug",
  "name": "Test bug to be deleted and then restored",
  "project": "Fabrikam-Fiber-Git",
  "deletedDate": "1/11/2017 11:18:16 PM",
  "deletedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403",
  "resource": {
    "id": 403,
    "rev": 3,
    "fields": {
      "System.AreaPath": "Fabrikam-Fiber-Git",
      "System.TeamProject": "Fabrikam-Fiber-Git",
      "System.IterationPath": "Fabrikam-Fiber-Git\\Release 1\\Sprint 2",
      "System.WorkItemType": "Bug",
      "System.State": "New",
      "System.Reason": "New defect reported",
      "System.CreatedDate": "2017-01-11T23:14:16.37Z",
      "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
      "System.ChangedDate": "2017-01-11T23:18:16.03Z",
      "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
      "System.Title": "Test bug to be deleted and then restored",
      "System.BoardColumn": "New",
      "System.BoardColumnDone": false,
      "Microsoft.VSTS.Common.StateChangeDate": "2017-01-11T23:14:16.37Z",
      "Microsoft.VSTS.Common.Priority": 2,
      "Microsoft.VSTS.Common.Severity": "3 - Medium",
      "WEF_6CB513B6E70E43499D9FC94E5BBFB784_Kanban.Column": "New",
      "WEF_6CB513B6E70E43499D9FC94E5BBFB784_Kanban.Column.Done": false,
      "Microsoft.VSTS.Common.ValueArea": "Business"
    },
    "_links": {
      "self": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403"
      },
      "workItemUpdates": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403/updates"
      },
      "workItemRevisions": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403/revisions"
      },
      "workItemHistory": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403/history"
      },
      "html": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=403"
      },
      "workItemType": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Bug"
      },
      "fields": {
        "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
      }
    },
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403"
  }
}

Sample code

Restore multiple work items

The batch apis can be leveraged to restore multiple work items at once.

POST https://{instance}/DefaultCollection/_apis/wit/$batch

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/$batch?api-version=3.0-preview
Content-Type: application/json
[
  {
    "method": "PATCH",
    "uri": "/_apis/wit/recyclebin/403?api-version=3.0-preview",
    "headers": {
      "Content-Type": "application/json-patch+json"
    },
    "body": [
      {
        "op": "replace",
        "path": "/IsDeleted",
        "value": "false"
      }
    ]
  },
  {
    "method": "PATCH",
    "uri": "/_apis/wit/recyclebin/404?api-version=3.0-preview",
    "headers": {
      "Content-Type": "application/json-patch+json"
    },
    "body": [
      {
        "op": "replace",
        "path": "/IsDeleted",
        "value": "false"
      }
    ]
  }
]

Sample response

Status code: 200
{
  "count": 2,
  "value": [
    {
      "code": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": "{\"id\":403,\"code\":200,\"type\":\"Bug\",\"name\":\"Test bug to be deleted and then restored\",\"project\":\"Fabrikam-Fiber-Git\",\"deletedDate\":\"1/12/2017 1:18:19 AM\",\"deletedBy\":\"Jamal Hartnett <fabrikamfiber4@hotmail.com>\",\"url\":\"https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/403\"}"
    },
    {
      "code": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": "{\"id\":404,\"code\":200,\"type\":\"Bug\",\"name\":\"Second work item to be restored\",\"project\":\"Fabrikam-Fiber-Git\",\"deletedDate\":\"1/12/2017 1:18:19 AM\",\"deletedBy\":\"Jamal Hartnett <fabrikamfiber4@hotmail.com>\",\"url\":\"https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/404\"}"
    }
  ]
}

Sample code

Permanently delete a work item

DELETE https://{instance}/DefaultCollection/{project}/_apis/wit/recycleBin/{id}?api-version={version}
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project of the deleted work items
id int ID of the deleted item
Query
api-version string Version of the API to use.

Sample request

DELETE https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/recyclebin/403?api-version=3.0-preview

Sample response

Status code: 204

Sample code

Permanently delete multiple work items

The batch apis can be leveraged to restore multiple work items at once.

POST https://{instance}/DefaultCollection/_apis/wit/$batch

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/$batch?api-version=3.0-preview
Content-Type: application/json
[
  {
    "method": "DELETE",
    "uri": "/_apis/wit/recyclebin/405?api-version=3.0-preview",
    "headers": {
      "Content-Type": "application/json-patch+json"
    }
  },
  {
    "method": "DELETE",
    "uri": "/_apis/wit/recyclebin/406?api-version=3.0-preview",
    "headers": {
      "Content-Type": "application/json-patch+json"
    }
  }
]

Sample response

Status code: 200
{
  "count": 2,
  "value": [
    {
      "code": 204
    },
    {
      "code": 204
    }
  ]
}

Sample code