Work items

Last Update: 3/6/2017

api-version = 1.0

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

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 are returned.
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;
   }
}

Samples

Getting Started

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

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

Create Bug

Creating a new bug (or any work item) is pretty straight forward. You just need to set the field values and send a JSON-Patch object to the REST Enpoint.

You can view the sample REST endpoint here

There are a few things happening in the code sample below:

  1. Create an array of objects to set the field values
  2. Convert that array to a serialized json object
  3. Send that serialized json object to the REST endpoint

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

...

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

Object[] patchDocument = new Object[4];

patchDocument[0] = new { op = "add", path = "/fields/System.Title", value = "Authorization Errors" }; patchDocument[1] = new { op = "add", path = "/fields/Microsoft.VSTS.TCM.ReproSteps", value = "Our authorization logic needs to allow for users with Microsoft accounts (formerly Live Ids) - http://msdn.microsoft.com/en-us/library/live/hh826547.aspx" }; patchDocument[2] = new { op = "add", path = "/fields/Microsoft.VSTS.Common.Priority", value = "1" }; patchDocument[3] = new { op = "add", path = "/fields/Microsoft.VSTS.Common.Severity", value = "2 - High" };

//use the httpclient using (var client = new HttpClient()) { //set our headers 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"); 
   var method = new HttpMethod("PATCH");
   var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/fabrikam/_apis/wit/workitems/$Bug?api-version=2.2") { Content = patchValue };
   var response = client.SendAsync(request).Result;

   //if the response is successfull, set the result to the workitem object
   if (response.IsSuccessStatusCode)
   {
       var result = response.Content.ReadAsStringAsync().Result;
   }

} }

```cl
using System;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.WebApi.Patch.Json;
using Microsoft.VisualStudio.Services.WebApi.Patch;
using Microsoft.VisualStudio.Services.Common;

...

public void CreateBug()
{
   string _personalAccessToken = "your personal access token";
   string _projectName = "fabrikam"
   Uri _uri = new Uri("https://account.visualstudio.com");
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   JsonPatchDocument patchDocument = new JsonPatchDocument();

   //add fields to your patch document
   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/System.Title",
           Value = "Authorization Errors"
       }
   );

   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/Microsoft.VSTS.TCM.ReproSteps",
           Value = "Our authorization logic needs to allow for users with Microsoft accounts (formerly Live Ids) - http://msdn.microsoft.com/en-us/library/live/hh826547.aspx"
       }
   );

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

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

   //use the workItemTrackingHttpClient
   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
       //create a work item
       WorkItem result = workItemTrackingHttpClient.CreateWorkItemAsync(patchDocument, _projectName, "Bug").Result;
   }
}

Contracts: WorkItem, JSONPatchDocument, JSONPatchOperation

Migrating work items

Often, when migrating work items from another source, organizations want to retain all the original properties of the work item. For example, you may want to create a bug that retains the original created date and created by values from the system where it originated. By using the basic REST example above, this is not possible since the Created and Changed date fields are automatically calculated by the system. Luckily, there is a solution - 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. There are some limitations on what's supported:

  • To modify the System.CreatedBy or System.ChangedBy fields, you must be a member of the "Project Collection Service Acccounts" group.
  • Created Date and Created By can ONLY be set on the initial revision
  • Changed Date must always be increasing, meaning you can't have a revision

The code is the same as Create Bug. However, we pass the bypassRules=true parameter to the REST endpoint.

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

...

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

   Object[] patchDocument = new Object[6];

   patchDocument[0] = new { op = "add", path = "/fields/System.Title", value = "Imported bug from my other system (rest api)" };
   patchDocument[1] = new { op = "add", path = "/fields/Microsoft.VSTS.TCM.ReproSteps", value = "Our authorization logic needs to allow for users with Microsoft accounts (formerly Live Ids) - http://msdn.microsoft.com/en-us/library/live/hh826547.aspx" };
   patchDocument[2] = new { op = "add", path = "/fields/System.CreatedBy", value = "Some User" };
   patchDocument[3] = new { op = "add", path = "/fields/System.ChangedBy", value = "Some User" };
   patchDocument[4] = new { op = "add", path = "/fields/System.CreatedDate", value = "4/15/2016" };
   patchDocument[5] = new { op = "add", path = "/fields/System.History", value = "Data imported from source" };

   //use the httpclient
   using (var client = new HttpClient())
   {
       //set our headers
       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"); 

       var method = new HttpMethod("PATCH");
       var request = new HttpRequestMessage(method, "https://account.visualstudio.com/fabrikam/_apis/wit/workitems/$Bug?bypassRules=true&api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       //if the response is successfull, set the result to the workitem object
       if (response.IsSuccessStatusCode)
       {
           var result = response.Content.ReadAsStringAsync().Result;
       }
   }
}
using System;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.WebApi.Patch.Json;
using Microsoft.VisualStudio.Services.WebApi.Patch;
using Microsoft.VisualStudio.Services.Common;

...

public void CreateBugByPassingRules()
{
   string _personalAccessToken = "your personal access token";
   string _projectName = "fabrikam"
   Uri _uri = new Uri("https://account.visualstudio.com");
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);

   JsonPatchDocument patchDocument = new JsonPatchDocument();

   //add fields to your patch document
   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/System.Title",
           Value = "Imported bug from my other system (client lib)"
       }
   );

   patchDocument.Add(
     new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/Microsoft.VSTS.TCM.ReproSteps",
           Value = "Our authorization logic needs to allow for users with Microsoft accounts (formerly Live Ids) - http://msdn.microsoft.com/en-us/library/live/hh826547.aspx"
       }
   );

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

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

   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/System.CreatedDate",
           Value = "4/15/2016"
       }
   );

   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/System.History",
           Value = "Data imported from source"
       }
   );

   //use the workItemTrackingHttpClient
   using (WorkItemTrackingHttpClient workItemTrackingHttpClient = new WorkItemTrackingHttpClient(_uri, _credentials))
   {
       //create a work item
       WorkItem result = workItemTrackingHttpClient.CreateWorkItemAsync(patchDocument, _projectName, "Bug", null, true).Result;
   }
}

Contracts: WorkItem, JSONPatchDocument, JSONPatchOperation

Update Bug

In this example we are going to update the values of a bug. Before we get started with the code, there are couple of assumptions being made:

  1. We already know the id for the bug (work item) that we want to update
  2. We know exactly what fields we want to update and values we want to update them to

Later on we will learn how to query for work items and then update them in bulk.


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

...

public void UpdateBug()
{
   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

   Object[] patchDocument = new Object[3];

   //change some values on a few fields
   patchDocument[0] = new { op = "add", path = "/fields/System.History", value = "Tracking that we changed the priority and severity of this bug to high" };
   patchDocument[1] = new { op = "add", path = "/fields/Microsoft.VSTS.Common.Priority", value = "1" };
   patchDocument[2] = new { op = "add", path = "/fields/Microsoft.VSTS.Common.Severity", value = "1 - Critical" };

   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);

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

       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 System;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.WebApi.Patch.Json;
using Microsoft.VisualStudio.Services.WebApi.Patch;
using Microsoft.VisualStudio.Services.Common;

...

public void UpdateBug()
{
   string _personalAccessToken = "your personal access token";
   Uri _uri = new Uri("https://account.visualstudio.com");
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
   int _id = 1234;

   //create a JSON-Patch Document and add the fields you want to update
   JsonPatchDocument patchDocument = new JsonPatchDocument();

   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/System.History",
           Value = "Tracking that we changed the priority and severity of this bug to high"
       }
   );

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

   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/Microsoft.VSTS.Common.Severity",
           Value = "1 - Critical"
       }
   );

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

Contracts: WorkItem, JSONPatchDocument, JSONPatchOperation

Add Comment to Bug

This sample is very simular to Update a Bug example. The difference is, we only need to add a value for the System.History field.

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

...

public void AddCommentToBug()
{
   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

   Object[] patchDocument = new Object[1];

   //just adding a comment so only need to add the System.History field
   patchDocument[0] = new { op = "add", path = "/fields/System.History", value = "Adding 'hello world' comment to this bug" };

   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);

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

       var method = new HttpMethod("PATCH");
       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 System;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.WebApi.Patch.Json;
using Microsoft.VisualStudio.Services.WebApi.Patch;
using Microsoft.VisualStudio.Services.Common;

...

public void AddCommentToBug()
{
   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

   //create a JSON-Patch Document and the System.History field with the comment value
   JsonPatchDocument patchDocument = new JsonPatchDocument();

   patchDocument.Add(
       new JsonPatchOperation() {
           Operation = Operation.Add,
           Path = "/fields/System.History",
           Value = "Adding 'hello world' comment to this bug"
       }
   );

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

Contracts: WorkItem, JSONPatchDocument, JSONPatchOperation

Change Bug to a User Story

Depending on your worflow, you may want to change the type of a work item. For examaple, if someone creates a bug but it is really a change request. Instead of creating a new user story, you can change the type from a bug to a user story.

The below example is very simular to the Update a Bug example. You just need to set the /fields/System.WorkItemType field to a User Story.

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

...

public void ChangeBugToUserStory()
{
   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

   Object[] patchDocument = new Object[1];

   //change some values on a few fields
   patchDocument[0] = new { op = "add", path = "/fields/System.WorkItemType", value = "User Story" };

   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);

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


       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 System;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.WebApi.Patch.Json;
using Microsoft.VisualStudio.Services.WebApi.Patch;
using Microsoft.VisualStudio.Services.Common;

...

public void ChangeBugToUserStory()
{
   string _personalAccessToken = "your personal access token";
   Uri _uri = new Uri("https://account.visualstudio.com");
   VssBasicCredential _credentials = new VssBasicCredential("", _personalAccessToken);
   in _id = 1234;      //change to an id for a work item

   //create a JSON-Patch Document and add the fields you want to update
   JsonPatchDocument patchDocument = new JsonPatchDocument();

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

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

Contracts: WorkItem, JSONPatchDocument, JSONPatchOperation

For more work item tracking samples, check out the sample page.