Work items

Last Update: 4/3/2017

api-version = 1.0

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

The Work Items API is used to create, update, or delete work items in Team Services and Team Foundation Server. There are multiple different work item types (bug, task, etc.) that can be accessed.

Common Tasks

This API is often used in combination with other work item tracking APIs for many end-to-end scenarios, check out the work item tracking common tasks to see popular use cases.

C# and .NET Samples

For all of the work items samples, check out the samples page.

Get a list of work items

GET https://{instance}/DefaultCollection/_apis/wit/workitems?api-version={version}&ids={string}[&fields={string}&asOf={DateTime}&$expand={enum{relations}&ErrorPolicy={string}]
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
Query
api-version string Version of the API to use.
ids string A comma-separated list of up to 200 IDs of the work items to get.
fields string A comma-separated list of up to 100 fields to get with each work item.
If not specified, all fields with values are returned. Calculated fields such as Attached File Count must be specifically queried for using this parameter.
asOf DateTime Gets the work items as they existed at this time.
$expand enum { all, relations, none } none Gets work item relationships (work item links, hyperlinks, file attachements, etc.).
ErrorPolicy string { throw, omit } throw Determines if the call will throw an error when encountering a work item (default behavior) that doesn't exist or simply omit it.

By IDs

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems?ids=297,299,300&api-version=1.0

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": 297,
      "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": "2014-12-29T20:49:20.77Z",
        "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.ChangedDate": "2014-12-29T20:49:20.77Z",
        "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.Title": "Customer can sign in using their Microsoft Account",
        "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"
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297"
    },
    {
      "id": 299,
      "rev": 7,
      "fields": {
        "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
        "System.TeamProject": "Fabrikam-Fiber-Git",
        "System.IterationPath": "Fabrikam-Fiber-Git",
        "System.WorkItemType": "Task",
        "System.State": "To Do",
        "System.Reason": "New task",
        "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
        "System.CreatedDate": "2014-12-29T20:49:21.617Z",
        "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.ChangedDate": "2014-12-29T20:49:28.74Z",
        "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.Title": "JavaScript implementation for Microsoft Account",
        "Microsoft.VSTS.Scheduling.RemainingWork": 4,
        "System.Description": "Follow the code samples from MSDN",
        "System.Tags": "Tag1; Tag2"
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    {
      "id": 300,
      "rev": 1,
      "fields": {
        "System.AreaPath": "Fabrikam-Fiber-Git",
        "System.TeamProject": "Fabrikam-Fiber-Git",
        "System.IterationPath": "Fabrikam-Fiber-Git",
        "System.WorkItemType": "Task",
        "System.State": "To Do",
        "System.Reason": "New task",
        "System.CreatedDate": "2014-12-29T20:49:22.103Z",
        "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.ChangedDate": "2014-12-29T20:49:22.103Z",
        "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.Title": "Unit Testing for MSA login",
        "Microsoft.VSTS.Scheduling.RemainingWork": 3,
        "System.Description": "We need to ensure we have coverage to prevent regressions"
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300"
    }
  ]
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItemsByIDs()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _ids = "297,299,300";

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems?ids=" + _ids + "&api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public GetWorkItemsByIDs()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
  int[] _ids = { 297, 299, 300 };

  using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
  {
      List<WorkItem> results = workItemTrackingHttpClient.GetWorkItemsAsync(_ids).Result;
  }
}

With specific fields

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems?ids=297,299,300&fields=System.Id,System.Title,System.WorkItemType,Microsoft.VSTS.Scheduling.RemainingWork&api-version=1.0

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": 297,
      "rev": 1,
      "fields": {
        "System.Id": 297,
        "System.WorkItemType": "Product Backlog Item",
        "System.Title": "Customer can sign in using their Microsoft Account"
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297"
    },
    {
      "id": 299,
      "rev": 7,
      "fields": {
        "System.Id": 299,
        "System.WorkItemType": "Task",
        "System.Title": "JavaScript implementation for Microsoft Account",
        "Microsoft.VSTS.Scheduling.RemainingWork": 4
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    {
      "id": 300,
      "rev": 1,
      "fields": {
        "System.Id": 300,
        "System.WorkItemType": "Task",
        "System.Title": "Unit Testing for MSA login",
        "Microsoft.VSTS.Scheduling.RemainingWork": 3
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300"
    }
  ]
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItemsWithSpecificFields()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _fields = "System.Id,System.Title,System.WorkItemType,Microsoft.VSTS.Scheduling.RemainingWork";
  string _ids = "297,299,300";

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems?ids=" + _ids + "&fields=" + _fields + "&api-version=2.2"").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void GetWorkItemsWithSpecificFields()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
  int[] _ids = { 297, 299, 300 };

  var _fields = new string[] {
      "System.Id",
      "System.Title",
      "System.WorkItemType",
      "Microsoft.VSTS.Scheduling.RemainingWork"
   };

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      List<WorkItem> results = workItemTrackingHttpClient.GetWorkItemsAsync(_ids, _fields).Result;
   }
}

As of a date

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems?ids=297,299,300&fields=System.Id,System.Title,System.WorkItemType,Microsoft.VSTS.Scheduling.RemainingWork&asOf=2014-12-29T20:49:22.103Z&api-version=1.0

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": 297,
      "rev": 1,
      "fields": {
        "System.Id": 297,
        "System.WorkItemType": "Product Backlog Item",
        "System.Title": "Customer can sign in using their Microsoft Account"
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297"
    },
    {
      "id": 299,
      "rev": 1,
      "fields": {
        "System.Id": 299,
        "System.WorkItemType": "Task",
        "System.Title": "JavaScript implementation for Microsoft Account",
        "Microsoft.VSTS.Scheduling.RemainingWork": 4
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    {
      "id": 300,
      "rev": 1,
      "fields": {
        "System.Id": 300,
        "System.WorkItemType": "Task",
        "System.Title": "Unit Testing for MSA login",
        "Microsoft.VSTS.Scheduling.RemainingWork": 3
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300"
    }
  ]
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItemsAsOfDate()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _fields = "System.Id,System.Title,System.WorkItemType,Microsoft.VSTS.Scheduling.RemainingWork";
  string _ids = "297,299,300";
  DateTime _asOfDate = DateTime.Now.AddDays(-90); //last 90 days

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems?ids=" + _ids + "&fields=" + _fields + "&asOf=" + _asOfDate.ToString() + "&api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void GetWorkItemsAsOfDate()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
  int[] _ids = { 297, 299, 300 };
  DateTime _asOfDate = DateTime.Now.AddDays(-90); //last 90 days

  var _fields = new string[] {
      "System.Id",
      "System.Title",
      "System.WorkItemType",
      "Microsoft.VSTS.Scheduling.RemainingWork"
   };

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      List<WorkItem> results = workItemTrackingHttpClient.GetWorkItemsAsync(_ids, _fields, _asOfDate).Result;
   }
}

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems?ids=297,299,300&$expand=all&api-version=1.0

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": 297,
      "rev": 1,
      "fields": {
        "System.Id": 297,
        "System.AreaId": 3570,
        "System.AreaPath": "Fabrikam-Fiber-Git",
        "System.NodeName": "Fabrikam-Fiber-Git",
        "System.TeamProject": "Fabrikam-Fiber-Git",
        "System.AreaLevel1": "Fabrikam-Fiber-Git",
        "System.Rev": 1,
        "System.AuthorizedDate": "2014-12-29T20:49:20.77Z",
        "System.RevisedDate": "9999-01-01T00:00:00Z",
        "System.IterationId": 3570,
        "System.IterationPath": "Fabrikam-Fiber-Git",
        "System.IterationLevel1": "Fabrikam-Fiber-Git",
        "System.WorkItemType": "Product Backlog Item",
        "System.State": "New",
        "System.Reason": "New backlog item",
        "System.CreatedDate": "2014-12-29T20:49:20.77Z",
        "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.ChangedDate": "2014-12-29T20:49:20.77Z",
        "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.AuthorizedAs": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.PersonId": 77331,
        "System.Watermark": 607,
        "System.Title": "Customer can sign in using their Microsoft Account",
        "Microsoft.VSTS.Scheduling.Effort": 8,
        "WEF_6CB513B6E70E43499D9FC94E5BBFB784_System.ExtensionMarker": true,
        "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"
      },
      "relations": [
        {
          "rel": "System.LinkTypes.Hierarchy-Forward",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299",
          "attributes": {
            "isLocked": false,
            "comment": "decomposition of work"
          }
        },
        {
          "rel": "System.LinkTypes.Hierarchy-Forward",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
          "attributes": {
            "isLocked": false
          }
        },
        {
          "rel": "AttachedFile",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/attachments/098a279a-60b9-40a8-868b-b7fd00c0a439",
          "attributes": {
            "authorizedDate": "2014-12-29T20:49:20.77Z",
            "id": 65273,
            "resourceCreatedDate": "2014-12-29T20:49:20.77Z",
            "resourceModifiedDate": "2014-12-29T20:49:20.77Z",
            "revisedDate": "9999-01-01T00:00:00Z",
            "comment": "Spec for the work",
            "name": "Spec.txt"
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297"
        },
        "workItemUpdates": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297/updates"
        },
        "workItemRevisions": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297/revisions"
        },
        "workItemHistory": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297/history"
        },
        "html": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=297"
        },
        "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/297"
    },
    {
      "id": 299,
      "rev": 7,
      "fields": {
        "System.Id": 299,
        "System.AreaId": 4486,
        "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
        "System.NodeName": "Website",
        "System.TeamProject": "Fabrikam-Fiber-Git",
        "System.AreaLevel1": "Fabrikam-Fiber-Git",
        "System.AreaLevel2": "Website",
        "System.Rev": 7,
        "System.AuthorizedDate": "2014-12-29T20:49:28.74Z",
        "System.RevisedDate": "9999-01-01T00:00:00Z",
        "System.IterationId": 3570,
        "System.IterationPath": "Fabrikam-Fiber-Git",
        "System.IterationLevel1": "Fabrikam-Fiber-Git",
        "System.WorkItemType": "Task",
        "System.State": "To Do",
        "System.Reason": "New task",
        "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
        "System.CreatedDate": "2014-12-29T20:49:21.617Z",
        "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.ChangedDate": "2014-12-29T20:49:28.74Z",
        "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.AuthorizedAs": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.PersonId": 77331,
        "System.Watermark": 616,
        "System.Title": "JavaScript implementation for Microsoft Account",
        "Microsoft.VSTS.Scheduling.RemainingWork": 4,
        "System.Description": "Follow the code samples from MSDN",
        "System.Tags": "Tag1; Tag2"
      },
      "relations": [
        {
          "rel": "System.LinkTypes.Hierarchy-Reverse",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
          "attributes": {
            "isLocked": false,
            "comment": "decomposition of work"
          }
        },
        {
          "rel": "System.LinkTypes.Related",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
          "attributes": {
            "isLocked": false,
            "comment": "adding another task"
          }
        },
        {
          "rel": "Hyperlink",
          "url": "http://blogs.msdn.com/b/bharry/archive/2014/05/12/a-new-api-for-visual-studio-online.aspx",
          "attributes": {
            "authorizedDate": "2014-12-29T20:49:27.98Z",
            "id": 65275,
            "resourceCreatedDate": "2014-12-29T20:49:27.98Z",
            "resourceModifiedDate": "2014-12-29T20:49:27.98Z",
            "revisedDate": "9999-01-01T00:00:00Z"
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
        },
        "workItemUpdates": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
        },
        "workItemRevisions": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
        },
        "workItemHistory": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
        },
        "html": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
        },
        "workItemType": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
        },
        "fields": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
        }
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    {
      "id": 300,
      "rev": 1,
      "fields": {
        "System.Id": 300,
        "System.AreaId": 3570,
        "System.AreaPath": "Fabrikam-Fiber-Git",
        "System.NodeName": "Fabrikam-Fiber-Git",
        "System.TeamProject": "Fabrikam-Fiber-Git",
        "System.AreaLevel1": "Fabrikam-Fiber-Git",
        "System.Rev": 1,
        "System.AuthorizedDate": "2014-12-29T20:49:22.103Z",
        "System.RevisedDate": "9999-01-01T00:00:00Z",
        "System.IterationId": 3570,
        "System.IterationPath": "Fabrikam-Fiber-Git",
        "System.IterationLevel1": "Fabrikam-Fiber-Git",
        "System.WorkItemType": "Task",
        "System.State": "To Do",
        "System.Reason": "New task",
        "System.CreatedDate": "2014-12-29T20:49:22.103Z",
        "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.ChangedDate": "2014-12-29T20:49:22.103Z",
        "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.AuthorizedAs": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
        "System.PersonId": 77331,
        "System.Watermark": 610,
        "System.Title": "Unit Testing for MSA login",
        "Microsoft.VSTS.Scheduling.RemainingWork": 3,
        "System.Description": "We need to ensure we have coverage to prevent regressions"
      },
      "relations": [
        {
          "rel": "System.LinkTypes.Hierarchy-Reverse",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
          "attributes": {
            "isLocked": false
          }
        },
        {
          "rel": "System.LinkTypes.Related",
          "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299",
          "attributes": {
            "isLocked": false,
            "comment": "adding another task"
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300"
        },
        "workItemUpdates": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300/updates"
        },
        "workItemRevisions": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300/revisions"
        },
        "workItemHistory": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300/history"
        },
        "html": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=300"
        },
        "workItemType": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
        },
        "fields": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
        }
      },
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300"
    }
  ]
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItemsWithLinksAndAttachments()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _ids = "297,299,300";

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems?ids=" + _ids + "&expand=all&api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void GetWorkItemsWithLinksAndAttachments()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token"; 
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
  int[] _ids = { 297, 299, 300 };

  using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
  {
      List<WorkItem> results = workItemTrackingHttpClient.GetWorkItemsAsync(_ids, null, null, WorkItemExpand.All).Result;
  }
}

Get a work item

GET https://{instance}/DefaultCollection/_apis/wit/workitems/{id}?api-version={version}[&$expand={enum{relations}]
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
id string ID of the work item to retrieve.
Query
api-version string Version of the API to use.
$expand enum { all, relations, none } none Gets work item relationships (work item links, hyperlinks and file attachements).

Sample request

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

Sample response

Status code: 200
{
  "id": 309,
  "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": "Customer can sign in using their Microsoft Account",
    "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/309"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=309"
    },
    "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/309"
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItem()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _id = "309";

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems/" + _id + "?api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void GetWorkItem()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
  int _id = 309;

  using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
  {
      WorkItem result = workItemTrackingHttpClient.GetWorkItemAsync(_id).Result;
  }
}

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/309?$expand=relations&api-version=1.0

Sample response

Status code: 200
{
  "id": 309,
  "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": "Customer can sign in using their Microsoft Account",
    "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"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/311",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Hierarchy-Forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/312",
      "attributes": {
        "isLocked": false
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=309"
    },
    "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/309"
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItemWithLinksAndAttachments()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _id = "309";

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems/" + id + "?$expand=relations&api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void GetWorkItemWithLinksAndAttachments()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
   int _id = 309;

  using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
  {
      WorkItem result = workItemTrackingHttpClient.GetWorkItemAsync(_id, null, null, WorkItemExpand.Relations).Result;
  }
}

Fully expanded

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/309?$expand=all&api-version=1.0

Sample response

Status code: 200
{
  "id": 309,
  "rev": 1,
  "fields": {
    "System.Id": 309,
    "System.AreaId": 3570,
    "System.AreaPath": "Fabrikam-Fiber-Git",
    "System.NodeName": "Fabrikam-Fiber-Git",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.AreaLevel1": "Fabrikam-Fiber-Git",
    "System.Rev": 1,
    "System.AuthorizedDate": "2015-01-07T18:13:01.807Z",
    "System.RevisedDate": "9999-01-01T00:00:00Z",
    "System.IterationId": 3570,
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.IterationLevel1": "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.AuthorizedAs": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.PersonId": 77331,
    "System.Watermark": 649,
    "System.Title": "Customer can sign in using their Microsoft Account",
    "Microsoft.VSTS.Scheduling.Effort": 8,
    "WEF_6CB513B6E70E43499D9FC94E5BBFB784_System.ExtensionMarker": true,
    "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"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/311",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Hierarchy-Forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/312",
      "attributes": {
        "isLocked": false
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/309/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=309"
    },
    "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/309"
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetWorkItemFullyExpanded()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
  string _id = "309";

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       //send the request and content
       HttpResponseMessage response = client.GetAsync("_apis/wit/workitems/" + _id + "?$expand=all&api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void GetWorkItemFullyExpanded()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
  int _id = 309;

  using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
  {
      WorkItem result = workItemTrackingHttpClient.GetWorkItemAsync(_id, null, null, WorkItemExpand.All).Result;
  }
}

Get default values

Get the default values that will be filled in automatically when you create a new work item of a specific type.

GET https://{instance}/DefaultCollection/{project}/_apis/wit/workitems/${workItemTypeName}?api-version={version}
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team project where the work item type is defined.
workItemTypeName string Name of the work item type.
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/workitems/$Task?api-version=1.0

Sample response

Status code: 200
{
  "fields": {
    "System.WorkItemType": "Task",
    "System.AreaPath": "Fabrikam-Fiber-Git",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>"
  },
  "_links": {
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems"
}

Sample code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

...

public void GetDefaultValues()
{
    string _personalAccessToken = "your personal access token";
    string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));

    //use the httpclient
    using (var client = new HttpClient())
    {
        //set our headers
        client.BaseAddress = new Uri("https://accountname.visualstudio.com/");
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

        //send the request and content
        HttpResponseMessage response = client.GetAsync("Fabrikam-Fiber-Git/_apis/wit/workitems/$Task?api-version=2.2").Result;

        if (response.IsSuccessStatusCode)
        {
            var result = response.Content.ReadAsStringAsync().Result;
        }
    }
}

Create a work item

When you create a work item, you can provide values for any of the work item fields.

PATCH https://{instance}/DefaultCollection/{project}/_apis/wit/workitems/${workItemTypeName}?api-version={version}
Content-Type: application/json-patch+json
[
    {
        "op": "add",
        "path": { string }
        "value": { string or int, depending on the field }
    },
    {
        "op": "add",
        "path": "/relations/-",
        "value":
        {
            "rel": { string },
            "url": { string },
            "attributes":
            {
                { name/value pairs }
            }
        }
    }
]
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of a team project where the work item should be created.
workItemTypeName string Name of the work item type.
Query
api-version string Version of the API to use.
Body - field
op enum { add, replace, test } The operation to perform on the field.
You can use add or replace to set the value of a field when you create a work item.
Use test to verify that the value is valid without actually saving the work item.
path string Path to the value you want to add, replace, remove, or test.
For a field, use "/fields/{reference name}".
value string or int, depending on the field New value to set.
Body - relation
op enum { add, replace, remove, test } The operation to perform on the relation.
Use test to verify that the relation is valid without actually saving the work item.
path string Path to the value you want to add, replace, remove, or test.
For a specific relation, use "relations/Id".
For all relations, use "/relations/-".
value.rel string Type of the relationship. Examples include, work-item/hierarchy-forward, changeset, or attachment.
Get the list of relations that a work item type supports using relation types.
value.url string URL of the item you are relating to the current work item.
value.attributes array of name/value pairs Additional attributes of the relationship (e.g. comment, isLocked, etc.)

If any of the new field values or relations are not valid, the work item will not be created.

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/workitems/$Task?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/fields/System.Title",
    "value": "JavaScript implementation for Microsoft Account"
  }
]

Sample response

Status code: 200
{
  "id": 298,
  "rev": 1,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.CreatedDate": "2014-12-29T20:49:21.21Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:21.21Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account"
  },
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/298"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/298/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/298/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/298/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=298"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/298"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void CreateWorkItem()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _project = "My project name";

   Object[] patchDocument = new Object[1];

  patchDocument[0] = new {
      op = "add",
      path = "/fields/System.Title",
      value = "JavaScript implementation for Microsoft Account"
  };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/" + projectName + "/_apis/wit/workitems/$Task?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void CreateWorkItem()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   string _project = "My project name";

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.Title",
          Value = "JavaScript implementation for Microsoft Account"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
       var result = workItemTrackingHttpClient.CreateWorkItemAsync(patchDocument, projectName, "Task").Result;
   }
}

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/workitems/$Task?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/fields/System.Title",
    "value": "JavaScript implementation for Microsoft Account"
  },
  {
    "op": "add",
    "path": "/fields/Microsoft.VSTS.Scheduling.RemainingWork",
    "value": 4
  },
  {
    "op": "add",
    "path": "/fields/System.Description",
    "value": "Follow the code samples from MSDN"
  },
  {
    "op": "add",
    "path": "/fields/System.History",
    "value": "Jim has the most context around this."
  },
  {
    "op": "add",
    "path": "/relations/-",
    "value": {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "comment": "decomposition of work"
      }
    }
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 1,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:21.617Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Jim has the most context around this."
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void CreateWorkItemWithWorkItemLink()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _project = "My project name";

   Object[] patchDocument = new Object[5];

  patchDocument[0] = new { op = "add", path = "/fields/System.Title", value = "JavaScript implementation for Microsoft Account" };
  patchDocument[1] = new { op = "add", path = "/fields/Microsoft.VSTS.Scheduling.RemainingWork", value = "4" };
  patchDocument[2] = new { op = "add", path = "/fields/System.Description", value = "Follow the code samples from MSDN" };
  patchDocument[3] = new { op = "add", path = "/fields/System.History", value = "Jim has the most context around this." };
  patchDocument[4] = new {
      op = "add",
      path = "/relations/-",
      value = new {
          rel = "System.LinkTypes.Hierarchy-Reverse",
          url = "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297"
          attributes = new {
              comment = "decomposition of work"
          }
      }
  };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/" + projectName + "/_apis/wit/workitems/$Task?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void CreateWorkItemWithWorkItemLink()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   string _project = "My project name";

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.Title",
          Value = "JavaScript implementation for Microsoft Account"
      }
  );

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/Microsoft.VSTS.Scheduling.RemainingWork",
          Value = "4"
      }
  );

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.Description",
          Value = "Follow the code samples from MSDN"
      }
  );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.History",
          Value = "Jim has the most context around this."
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/relations/-",
          Value = new {
              rel = "System.LinkTypes.Hierarchy-Reverse",
              url = linkUrl,
              attributes = new {
                  comment = "decomposition of work"
              }
          }
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.CreateWorkItemAsync(patchDocument, projectName, "Task").Result;
   }
}

Update work items

PATCH https://{instance}/DefaultCollection/_apis/wit/workitems/{id}?api-version={version}
Content-Type: application/json-patch+json
[
    {
        "op": "add",
        "path": { string }
        "value": { string or int, depending on the field }
    },
    {
        "op": "add",
        "path": "/relations/-",
        "value":
        {
            "rel": { string },
            "url": { string },
            "attributes":
            {
                { name/value pairs }
            }
        }
    }
]
Parameter Type Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
id string ID of the work item to retrieve.
Query
api-version string Version of the API to use.
Body - field
op enum { add, replace, remove, test } The operation to perform on the field.
You can use add or replace to set the value of a field.
Use remove to clear the value of the field.
Use test to verify that the value is valid without actually saving the work item.
path string Path to the value you want to add, replace, remove, or test.
For a field, use "/fields/{reference name}".
value string or int, depending on the field New value to set.
Body - relation
op enum { add, replace, remove, test } The operation to perform on the relation.
Use test to verify that the relation is valid without actually saving the work item.
path string Path to the value you want to add, replace, remove, or test.
For a specific relation, use "relations/Id".
For all relations, use "/relations/-".
value.rel string Type of the relationship. Examples include, work-item/hierarchy-forward, changeset, or attachment.
Get the list of relations that a work item type supports using relation types.
value.url string URL of the item you are relating to the current work item.
value.attributes array of name/value pairs Additional attributes of the relationship (e.g. comment, isLocked, etc.)

If any of the new field values or relations are not valid, or if the work item has been saved by someone else since the revision was retrieved, the work item will not be updated.

Update a field

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 1
  },
  {
    "op": "add",
    "path": "/fields/System.AreaPath",
    "value": "Fabrikam-Fiber-Git\\Website"
  },
  {
    "op": "add",
    "path": "/fields/System.History",
    "value": "Moving to the right area path"
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 2,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:23.933Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Moving to the right area path"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemUpdateField()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[3];

  patchDocument[0] = new { op = "test", path = "/rev", value = "1" };
   patchDocument[1] = new { op = "add", path = "/fields/Microsoft.VSTS.Common.Priority", value = "2" };
   patchDocument[2] = new { op = "add", path = "/fields/System.History", value = "Changing priority" };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemUpdateField()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Test,
           Path = "/rev",
          Value = "1"
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/Microsoft.VSTS.Common.Priority",
          Value = "2"
      }
   );

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.History",
          Value = "Changing priority"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Move work item

API Availability: Team Services only (not TFS)

In order to move a work item, we need to update 3 fields (System.TeamProject, System.AreaPath and System.IterationPath). The below example shows that a work item was moved to a destination team project (Fabrikam-Scrum).

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/398?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/fields/System.TeamProject",
    "value": "Fabrikam-Scrum"
  },
  {
    "op": "add",
    "path": "/fields/System.AreaPath",
    "value": "Fabrikam-Scrum"
  },
  {
    "op": "add",
    "path": "/fields/System.IterationPath",
    "value": "Fabrikam-Scrum"
  }
]

Sample response

Status code: 200
{
  "id": 398,
  "rev": 2,
  "fields": {
    "System.AreaPath": "Fabrikam-Scrum",
    "System.TeamProject": "Fabrikam-Scrum",
    "System.IterationPath": "Fabrikam-Scrum",
    "System.WorkItemType": "Bug",
    "System.State": "New",
    "System.Reason": "New defect reported",
    "System.CreatedDate": "2016-04-07T16:42:06.55Z",
    "System.CreatedBy": "Chuck Reinhart <fabrikamfiber3@hotmail.com>",
    "System.ChangedDate": "2016-04-07T16:42:07.737Z",
    "System.ChangedBy": "Chuck Reinhart <fabrikamfiber3@hotmail.com>",
    "System.Title": "First bug",
    "System.BoardColumn": "New",
    "System.BoardColumnDone": false,
    "Microsoft.VSTS.Common.StateChangeDate": "2016-04-07T16:42:06.55Z",
    "Microsoft.VSTS.Common.Priority": 2,
    "Microsoft.VSTS.Common.Severity": "3 - Medium",
    "WEF_F9DCD9224F6E466499435017DB7D2D07_Kanban.Column": "New",
    "WEF_F9DCD9224F6E466499435017DB7D2D07_Kanban.Column.Done": false,
    "Microsoft.VSTS.Common.ValueArea": "Business",
    "WEF_F571AABFDCE945628B5E816FF5294898_Kanban.Column": "New",
    "WEF_F571AABFDCE945628B5E816FF5294898_Kanban.Column.Done": false
  },
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=398"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/b5c43ab0-20bb-44df-9690-7d3ea77c31cc/_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/398"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemMoveWorkItem()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[3];

   // set the required field values for the destination
  patchDocument[0] = new { op = "add", path = "/fields/System.TeamProject", value = "Fabrikam-Scrum" };
  patchDocument[1] = new { op = "add", path = "/fields/System.AreaPath", value = "Fabrikam-Scrum" };
  patchDocument[2] = new { op = "add", path = "/fields/System.IterationPath", value = "Fabrikam-Scrum" };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemMoveWorkItem()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.TeamProject",
          Value = "Fabrikam-Scrum"
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.AreaPath",
          Value = "Fabrikam-Scrum"
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.IterationPath",
          Value = "Fabrikam-Scrum"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Change work item type

API Availability: Team Services only (not TFS)

In order to change a work item type, we need to update the System.WorkItemType field as well as any required fields on the target work item type. In the sample request below a Bug work item was converted to a Task.

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/398?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/fields/System.WorkItemType",
    "value": "Task"
  },
  {
    "op": "add",
    "path": "/fields/System.State",
    "value": "To Do"
  }
]

Sample response

Status code: 200
{
  "id": 398,
  "rev": 3,
  "fields": {
    "System.AreaPath": "Fabrikam-Scrum",
    "System.TeamProject": "Fabrikam-Scrum",
    "System.IterationPath": "Fabrikam-Scrum",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New defect reported",
    "System.CreatedDate": "2016-04-07T16:42:06.55Z",
    "System.CreatedBy": "Chuck Reinhart <fabrikamfiber3@hotmail.com>",
    "System.ChangedDate": "2016-04-07T16:42:08.167Z",
    "System.ChangedBy": "Chuck Reinhart <fabrikamfiber3@hotmail.com>",
    "System.Title": "First bug",
    "Microsoft.VSTS.Common.StateChangeDate": "2016-04-07T16:42:08.167Z",
    "Microsoft.VSTS.Common.Priority": 2,
    "Microsoft.VSTS.Common.Severity": "3 - Medium",
    "WEF_F9DCD9224F6E466499435017DB7D2D07_Kanban.Column": "New",
    "WEF_F9DCD9224F6E466499435017DB7D2D07_Kanban.Column.Done": false,
    "Microsoft.VSTS.Common.ValueArea": "Business",
    "WEF_F571AABFDCE945628B5E816FF5294898_Kanban.Column": "New",
    "WEF_F571AABFDCE945628B5E816FF5294898_Kanban.Column.Done": false
  },
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=398"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/b5c43ab0-20bb-44df-9690-7d3ea77c31cc/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/398"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemChangeWorkItemType()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[2];

   //change the work item type, state and reason values in order to change the work item type
  patchDocument[0] = new { op = "add", path = "/fields/System.WorkItemType", value = "User Story" };
  patchDocument[1] = new { op = "add", path = "/fields/System.State", value = "Active" };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemChangeWorkItemType()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.WorkItemType",
          Value = "User Story"
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.State",
          Value = "Active"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Add a tag

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 6
  },
  {
    "op": "add",
    "path": "/fields/System.Tags",
    "value": "Tag1; Tag2"
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 7,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:28.74Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.Tags": "Tag1; Tag2"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    },
    {
      "rel": "Hyperlink",
      "url": "http://blogs.msdn.com/b/bharry/archive/2014/05/12/a-new-api-for-visual-studio-online.aspx",
      "attributes": {
        "authorizedDate": "2014-12-29T20:49:27.98Z",
        "id": 65275,
        "resourceCreatedDate": "2014-12-29T20:49:27.98Z",
        "resourceModifiedDate": "2014-12-29T20:49:27.98Z",
        "revisedDate": "9999-01-01T00:00:00Z"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemAddTag()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[1];

  patchDocument[0] = new { op = "add", path = "/fields/System.Tags", value = "Tag1; Tag2" };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemAddTag()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token"; 
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.Tags",
          Value = "Tag1; Tag2"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 3
  },
  {
    "op": "add",
    "path": "/relations/-",
    "value": {
      "rel": "System.LinkTypes.Dependency-forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "comment": "Making a new link for the dependency"
      }
    }
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 3,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:24.67Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Johnnie is going to take this work over."
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    },
    {
      "rel": "System.LinkTypes.Dependency-Forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "Making a new link for the dependency"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemAddLink()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[1];

  patchDocument[0] = new {
      op = "add",
      path = "/relations/-",
      value = new {
          rel = "System.LinkTypes.Dependency-forward",
          url = "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
          attributes = new {
              comment = "Making a new link for the dependency"
          }
      }
   };

   using (var client = new HttpClient())
    {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
    }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemAddLink()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/relations/-",
          Value = new {
              rel = "System.LinkTypes.Dependency-forward",
              url = "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
              attributes = new {
                  comment = "Making a new link for the dependency"
              }
          }
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 3
  },
  {
    "op": "replace",
    "path": "/relations/2/attributes/comment",
    "value": "Adding traceability to dependencies"
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 3,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:24.67Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Johnnie is going to take this work over."
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    },
    {
      "rel": "System.LinkTypes.Dependency-Forward",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "Adding traceability to dependencies"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemUpdateLink()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[2];

  patchDocument[0] = new { op = "test", path = "/rev", value = "1" };
  patchDocument[1] = new {
      op = "replace",
      path = "/relations/0/attributes/comment",
      value = "Adding traceability to dependencies"
   };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemUpdateLink()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";    
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Test,
          Path = "/rev",
          Value = "1"
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Replace,
          Path = "/relations/0/attributes/comment",
          Value = "Adding traceability to dependencies"                  
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 3
  },
  {
    "op": "remove",
    "path": "/relations/2"
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 3,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:24.67Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Johnnie is going to take this work over."
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemRemoveLink()
{   
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299"; 

   Object[] patchDocument = new Object[2];

  patchDocument[0] = new { op = "test", path = "/rev", value = "1" };
  patchDocument[1] = new {
      op = "remove",
      path = "/relations/0",               
  };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;           
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemRemoveLink()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";    
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Test,
          Path = "/rev",
          Value = "1"
      }
   );

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Remove,
          Path = "/relations/0"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Add an attachment

To attach a file to a work item, upload the attachment to the attachment store, then attach it to the work item.

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 3
  },
  {
    "op": "add",
    "path": "/fields/System.History",
    "value": "Adding the necessary spec"
  },
  {
    "op": "add",
    "path": "/relations/-",
    "value": {
      "rel": "AttachedFile",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/attachments/098a279a-60b9-40a8-868b-b7fd00c0a439?fileName=Spec.txt",
      "attributes": {
        "comment": "Spec for the work"
      }
    }
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 4,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:26.99Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Adding the necessary spec"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    },
    {
      "rel": "AttachedFile",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/attachments/098a279a-60b9-40a8-868b-b7fd00c0a439",
      "attributes": {
        "authorizedDate": "2014-12-29T20:49:26.99Z",
        "id": 65274,
        "resourceCreatedDate": "2014-12-29T20:49:26.99Z",
        "resourceModifiedDate": "2014-12-29T20:49:26.99Z",
        "revisedDate": "9999-01-01T00:00:00Z",
        "comment": "Spec for the work",
        "name": "Spec.txt"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

//needed to bind upload attachment results to
public class AttachmentReference
{
    public string id { get; set; }
    public string url { get; set; }
}

public void UpdateWorkItemAddAttachment()
{   
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "1234"; //change to id for a specific work item 
   string _filePath = "C:\\temp\\";   
   string _fileName = "my-picture.png";

   //read file bytes and put into byte array        
   Byte[] bytes = System.IO.File.ReadAllBytes(@_filePath + _fileName);

   using (var client = new HttpClient())
   {
       client.BaseAddress = new Uri("https://account.visualstudio.com");
       client.DefaultRequestHeaders.Accept.Clear();    
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/octet-stream")); 
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       ByteArrayContent content = new ByteArrayContent(bytes);
       content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
       HttpResponseMessage uploadResponse = client.PostAsync("_apis/wit/attachments?fileName=" + _fileName + "&api-version=2.2", content).Result;

       if (uploadResponse.IsSuccessStatusCode)
       {
           //get the result, we need this to get the url of the attachment
           var attachmentReference = uploadResponse.Content.ReadAsAsync<AttachmentReference>().Result;

           //now that we have the attachment uploaded
           //lets attach it to our bug

           Object[] patchDocument = new Object[1];

           //add values to create the attachment link
           patchDocument[0] = new {
               op = "add",
               path = "/relations/-",
               value = new {
                   rel = "AttachedFile",
                   url = attachmentReference.url, //url from upload result
                   attributes = new {
                       comment = "adding attachment to bug"
                   }
               }
           };            

           client.DefaultRequestHeaders.Accept.Clear();
           client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
           client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

           //serialize the fields array into a json string          
           var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json-patch+json"); //mediaType needs to be application/json-patch+json for a patch call

           //set the httpmethod to Patch
           var method = new HttpMethod("PATCH");

           //send the request
           var request = new HttpRequestMessage(method, "https://account.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
           var response = client.SendAsync(request).Result;

           if (response.IsSuccessStatusCode)
           {
               var result = response.Content.ReadAsStringAsync().Result;
           }            
       }     
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemAddAttachment()
{
   string _personalAccessToken = "your personal access token";
   Uri _uri = new Uri("https://account.visualstudio.com");
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
   int _id = 1234      //change to an id for a work item
   string _filePath = "C:\\temp\\my-picture.png";

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
       //upload attachment to attachment store and
       //get a reference to that file
       AttachmentReference attachmentReference = workItemTrackingHttpClient.CreateAttachmentAsync(_filePath).Result;

       //now that we have uploaded the attachment
       //update the bug to link back to the attachment

       JsonPatchDocument patchDocument = new JsonPatchDocument();

       patchDocument.Add(new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/relations/-",
           Value = new {
               rel = "AttachedFile",
               url = attachmentReference.Url,
               attributes = new {
                  comment = "adding link to bug"
               }
           }
       });

       //update bug
       WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Remove an attachment

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 4
  },
  {
    "op": "remove",
    "path": "/relations/2"
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 5,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:27.48Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemRemoveAttachment()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[2];

  patchDocument[0] = new { op = "test", path = "/rev", value = "1" };
  patchDocument[1] = new {
      op = "remove",
      path = "/relations/0",
   };

   using (var client = new HttpClient())
    {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
    }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemRemoveAttachment()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Test,
          Path = "/rev",
          Value = "1"
      }
   );

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Remove,
          Path = "/relations/0"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/299?api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/rev",
    "value": 5
  },
  {
    "op": "add",
    "path": "/fields/System.History",
    "value": "Linking to a blog article for context"
  },
  {
    "op": "add",
    "path": "/relations/-",
    "value": {
      "rel": "Hyperlink",
      "url": "http://blogs.msdn.com/b/bharry/archive/2014/05/12/a-new-api-for-visual-studio-online.aspx"
    }
  }
]

Sample response

Status code: 200
{
  "id": 299,
  "rev": 6,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Website",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Johnnie McLeod <fabrikamfiber2@hotmail.com>",
    "System.CreatedDate": "2014-12-29T20:49:21.617Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2014-12-29T20:49:27.98Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.History": "Linking to a blog article for context"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/297",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/300",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    },
    {
      "rel": "Hyperlink",
      "url": "http://blogs.msdn.com/b/bharry/archive/2014/05/12/a-new-api-for-visual-studio-online.aspx",
      "attributes": {
        "authorizedDate": "2014-12-29T20:49:27.98Z",
        "id": 65275,
        "resourceCreatedDate": "2014-12-29T20:49:27.98Z",
        "resourceModifiedDate": "2014-12-29T20:49:27.98Z",
        "revisedDate": "9999-01-01T00:00:00Z"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=299"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/299"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemAddHyperLink()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[1];

  patchDocument[0] = new {
      op = "add",
      path = "/relations/-",
      value = new {
          rel = "Hyperlink",
          url = "http://www.visualstudio.com/team-services",
          attributes = new {
              comment = "Visual Studio Team Services"
          }
      }
   };

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemAddHyperLink()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

   JsonPatchDocument patchDocument = new JsonPatchDocument();

   patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/relations/-",
          Value = new {
              rel = "Hyperlink",
              url = "http://www.visualstudio.com/team-services",
              attributes = new {
                  comment = "Visual Studio Team Services"
              }
          }
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Make an update bypassing rules

For scenarios, such as migration or synchronization tools, when you want to make changes to a work item that otherwise would be invalid, you may optionally choose to bypass the rules engine on a work item update. This allows you to modify the work item fields without any restrictions, for example you can assign a work item to a user no longer in the organization.

To modify the System.CreatedBy, System.CreatedDate, System.ChangedBy, or System.ChangedDate fields, you must be a member of the "Project Collection Service Acccounts" group.

NOTE: System.CreatedBy and System.CreatedDate can only be modified using bypass rules on work item creation, i.e. the first revision of a work item.

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workitems/335?bypassRules=true&api-version=1.0
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/fields/System.AssignedTo",
    "value": "Invalid Value"
  }
]

Sample response

Status code: 200
{
  "id": 335,
  "rev": 8,
  "fields": {
    "System.AreaPath": "Fabrikam-Fiber-Git\\Web",
    "System.TeamProject": "Fabrikam-Fiber-Git",
    "System.IterationPath": "Fabrikam-Fiber-Git",
    "System.WorkItemType": "Task",
    "System.State": "To Do",
    "System.Reason": "New task",
    "System.AssignedTo": "Invalid Value",
    "System.CreatedDate": "2015-03-06T21:34:17.777Z",
    "System.CreatedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.ChangedDate": "2015-03-06T21:34:23.167Z",
    "System.ChangedBy": "Jamal Hartnett <fabrikamfiber4@hotmail.com>",
    "System.Title": "JavaScript implementation for Microsoft Account",
    "Microsoft.VSTS.Scheduling.RemainingWork": 4,
    "System.Description": "Follow the code samples from MSDN",
    "System.Tags": "Tag1; Tag2"
  },
  "relations": [
    {
      "rel": "System.LinkTypes.Hierarchy-Reverse",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/333",
      "attributes": {
        "isLocked": false,
        "comment": "decomposition of work"
      }
    },
    {
      "rel": "System.LinkTypes.Related",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/336",
      "attributes": {
        "isLocked": false,
        "comment": "adding another task"
      }
    },
    {
      "rel": "Hyperlink",
      "url": "http://blogs.msdn.com/b/bharry/archive/2014/05/12/a-new-api-for-visual-studio-online.aspx",
      "attributes": {
        "authorizedDate": "2015-03-06T21:34:22.32Z",
        "id": 135231,
        "resourceCreatedDate": "2015-03-06T21:34:22.32Z",
        "resourceModifiedDate": "2015-03-06T21:34:22.32Z",
        "revisedDate": "9999-01-01T00:00:00Z"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/335"
    },
    "workItemUpdates": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/335/updates"
    },
    "workItemRevisions": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/335/revisions"
    },
    "workItemHistory": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/335/history"
    },
    "html": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/web/wi.aspx?pcguid=d81542e4-cdfa-4333-b082-1ae2d6c3ad16&id=335"
    },
    "workItemType": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/fields"
    }
  },
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/335"
}

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void UpdateWorkItemByPassingRules()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

   Object[] patchDocument = new Object[1];

  patchDocument[0] = new { op = "replace", path = "/fields/System.CreatedBy", value = "Foo <Foo@hotmail.com>" };

  using (var client = new HttpClient())
    {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
    }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void UpdateWorkItemByPassingRules()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  JsonPatchDocument patchDocument = new JsonPatchDocument();

  patchDocument.Add(
      new JsonPatchOperation() {
          Operation = Operation.Add,
          Path = "/fields/System.CreatedBy",
          Value = "Foo <Foo@hotmail.com>"
      }
   );

   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
      WorkItem result = workItemTrackingHttpClient.UpdateWorkItemAsync(patchDocument, _id).Result;
   }
}

Delete a work item

Sample request

DELETE https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-Git/_apis/wit/workitems/72?api-version=1.0

Sample response

Status code: 204

Sample Code

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

....

public void DeleteWorkItem()
{
   string _personalAccessToken = "your personal access token";
   string _credentials = Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes(string.Format("{0}:{1}", "", _personalAccessToken)));
   string _id = "299";

  using (var client = new HttpClient())
   {
       client.DefaultRequestHeaders.Accept.Clear();
       client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
       client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", _credentials);

       var patchValue = new StringContent(JsonConvert.SerializeObject(patchDocument), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call

      var method = new HttpMethod("DELETE");
       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/wit/workitems/" + _id + "?api-version=2.2");
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public void DeleteWorkItem()
{
   //create uri and VssBasicCredential variables
   Uri _uri = new Uri("https://accountname.visualstudio.com");
   string _personalAccessToken = "your personal access token";
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   int _id = 299;

  using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
  {
      WorkItemDelete results = workItemTrackingHttpClient.DeleteWorkItemAsync(_id, false).Result;
  }
}