Recycle bin

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 = 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	TFS server name ({server:port}).
project	string	Project of the deleted work items
Query
api-version	string	Version of the API to use.

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/recyclebin?api-version=3.0-preview

Sample response

[
  {
    "id": "92",
    "url": "https://mytfsserver/DefaultCollection/_apis/wit/recycleBin/92"
  },
  {
    "id": "93",
    "url": "https://mytfsserver/DefaultCollection/_apis/wit/recycleBin/93"
  },
  {
    "id": "102",
    "url": "https://mytfsserver/DefaultCollection/_apis/wit/recycleBin/102"
  }
]

Sample code

C# (GetDeleteWorkItems method)

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	TFS server name ({server:port}).
project	string	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://mytfsserver/DefaultCollection/_apis/wit/recyclebin/72?api-version=1.0

Sample response

{
  "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://mytfsserver/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) - https://msdn.microsoft.com/library/live/hh826547.aspx"
    },
    "_links": {
      "self": {
        "href": "https://mytfsserver/DefaultCollection/_apis/wit/workItems/72"
      },
      "workItemUpdates": {
        "href": "https://mytfsserver/DefaultCollection/_apis/wit/workItems/72/updates"
      },
      "workItemRevisions": {
        "href": "https://mytfsserver/DefaultCollection/_apis/wit/workItems/72/revisions"
      },
      "workItemHistory": {
        "href": "https://mytfsserver/DefaultCollection/_apis/wit/workItems/72/history"
      },
      "html": {
        "href": "https://mytfsserver/DefaultCollection/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=72"
      },
      "workItemType": {
        "href": "https://mytfsserver/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Product%20Backlog%20Item"
      },
      "fields": {
        "href": "https://mytfsserver/DefaultCollection/_apis/wit/fields"
      }
    },
    "url": "https://mytfsserver/DefaultCollection/_apis/wit/workItems/72"
  }
}

Sample code

C# (GetDeleteWorkItem method)

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	TFS server name ({server:port}).
project	string	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://mytfsserver/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/recyclebin?ids=92,93,102&api-version=3.0-preview

Sample response

[
  {
    "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://mytfsserver/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://mytfsserver/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://mytfsserver/DefaultCollection/_apis/wit/recycleBin/102"
  }
]

Sample code

C# (GetMultipleDeletedWorkItems method)

Restore a work item

PATCH https://{instance}/DefaultCollection/_apis/wit/recyclebin/{id}?api-version={version}

Parameter	Type	Notes
URL
instance	string	TFS server name ({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 code

C# (RestoreWorkItem method)

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://mytfsserver/DefaultCollection/_apis/wit/$batch?api-version=3.0-preview

[
  {
    "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

{
  "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://mytfsserver/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://mytfsserver/DefaultCollection/_apis/wit/workItems/404\"}"
    }
  ]
}

Sample code

C# (RestoreMultipleWorkItems method)

Permanently delete a work item

DELETE https://{instance}/DefaultCollection/{project}/_apis/wit/recycleBin/{id}?api-version={version}

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
project	string	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://mytfsserver/DefaultCollection/_apis/wit/recyclebin/403?api-version=3.0-preview

Sample code

C# (PermanentlyDeleteWorkItem method)

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://mytfsserver/DefaultCollection/_apis/wit/$batch?api-version=3.0-preview

[
  {
    "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

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

Sample code

C# (PermanentlyDeleteMultipleWorkItems method)

Share via

Recycle bin

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

Sample request

Sample response

Sample code

Get a deleted item in the recycle bin

Sample request

Sample response

Sample code

Get multiple deleted items in the recycle bin

Sample request

Sample response

Sample code

Restore a work item

Sample code

Restore multiple work items

Sample request

Sample response

Sample code

Permanently delete a work item

Sample request

Sample code

Permanently delete multiple work items

Sample request

Sample response

Sample code

Additional resources