Teams

Last Update: 12/13/2016

api-version = 1.0

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

Get a list of teams

Get all teams within the project that the authenticated user has access to.

GET https://{instance}/DefaultCollection/_apis/projects/{project}/teams?api-version={version}[&$top={integer}&$skip={integer}]
Parameter Type Default Notes
URL
instance string VS Team Services account ({instance}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of the project.
Query
api-version string Version of the API to use.
$top integer 100 Maximum number of teams to return.
$skip integer 0 Number of teams to skip.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams?api-version=2.2

Sample response

Status code: 200
{
  "value": [
    {
      "id": "564e8204-a90b-4432-883b-d4363c6125ca",
      "name": "Quality assurance",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca",
      "description": "Testing staff",
      "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/564e8204-a90b-4432-883b-d4363c6125ca"
    },
    {
      "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
      "name": "Fabrikam-Fiber-TFVC Team",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd",
      "description": "The default project team.",
      "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/66df9be7-3586-467b-9c5f-425b29afedfd"
    }
  ],
  "count": 2
}

Sample Code

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

...

public class WebApiTeams 
{
   public WebApiTeam[] value { get; set; }
   public int count { get; set; }
}

public class WebApiTeam
{
   public string id { get; set; }
   public string name { get; set; }
   public string url { get; set; }
   public string description { get; set; }
   public string identityUrl { get; set; }
}

public void GetTeams()
{   
   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";

   //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/projects/" + _project + "/teams?api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           WebApiTeams teams = response.Content.ReadAsAsync<WebApiTeams>().Result;       
       }             
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public GetTeams()
{
   //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";

   using (TeamHttpClient teamHttpClient = new TeamHttpClient(_uri, _credentials))
   {
       IEnumerable<WebApiTeam> results = teamHttpClient.GetTeamsAsync(_project).Result;     
   }
}

A page at a time

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams?$top=1&$skip=1&api-version=2.2

Sample response

Status code: 200
{
  "value": [
    {
      "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
      "name": "Fabrikam-Fiber-TFVC Team",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd",
      "description": "The default project team.",
      "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/66df9be7-3586-467b-9c5f-425b29afedfd"
    }
  ],
  "count": 1
}

Get a team

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

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca?api-version=2.2

Sample response

Status code: 200
{
  "id": "564e8204-a90b-4432-883b-d4363c6125ca",
  "name": "Quality assurance",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca",
  "description": "Testing staff",
  "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/564e8204-a90b-4432-883b-d4363c6125ca"
}

Sample Code

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

...

public class WebApiTeam
{
   public string id { get; set; }
   public string name { get; set; }
   public string url { get; set; }
   public string description { get; set; }
   public string identityUrl { get; set; }
}

public void GetTeam()
{   
   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";
   string _team = "My team";

   //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/projects/" + _project + "/teams/" + _team + "?api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           WebApiTeam team = response.Content.ReadAsAsync<WebApiTeam>().Result;       
       }             
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public GetTeam()
{
   //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";
   string _team = "My team";

   using (TeamHttpClient teamHttpClient = new TeamHttpClient(_uri, _credentials))
   {
       WebApiTeam result = teamHttpClient.GetTeamAsync(_project, _team).Result;     
   }
}

Get a team's members

Append /members to the end of the URL to get a list of identity references for the team's members.

GET https://{instance}/DefaultCollection/_apis/projects/{project}/teams/{team}/members?api-version={version}[&$top={integer}&$skip={integer}]
Parameter Type Default Notes
URL
instance string VS Team Services account ({instance}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of the project.
team string Name or ID of the team.
Query
api-version string Version of the API to use.
$top integer 100 Maximum number of teams to return.
$skip integer 0 Number of teams to skip.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca/members/?api-version=2.2

Sample response

Status code: 200
{
  "value": [
    {
      "id": "3b5f0c34-4aec-4bf4-8708-1d36f0dbc468",
      "displayName": "Christie Church",
      "uniqueName": "fabrikamfiber1@hotmail.com",
      "url": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/3b5f0c34-4aec-4bf4-8708-1d36f0dbc468",
      "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=3b5f0c34-4aec-4bf4-8708-1d36f0dbc468"
    },
    {
      "id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
      "displayName": "Chuck Reinhart",
      "uniqueName": "fabrikamfiber3@hotmail.com",
      "url": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
      "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
    },
    {
      "id": "19d9411e-9a34-45bb-b985-d24d9d87c0c9",
      "displayName": "Johnnie McLeod",
      "uniqueName": "fabrikamfiber2@hotmail.com",
      "url": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/19d9411e-9a34-45bb-b985-d24d9d87c0c9",
      "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=19d9411e-9a34-45bb-b985-d24d9d87c0c9"
    }
  ],
  "count": 3
}

Sample Code

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

...

public class Members
{
   public Member[] value { get; set; }
   public int count { get; set; }
}

public class Member
{
   public string id { get; set; }
   public string displayName { get; set; }
   public string uniqueName { get; set; }
   public string url { get; set; }
   public string imageUrl { get; set; }
}

public void GetTeamMembers()
{   
   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";
   string _team = "My team";

   //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/projects/" + _project + "/teams/" + _team + "/members?api-version=2.2").Result;

       if (response.IsSuccessStatusCode)
       {
           Members members = response.Content.ReadAsAsync<Members>().Result;       
       }             
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public GetTeamMembers()
{
   //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";
   string _team = "My team"

   using (TeamHttpClient teamHttpClient = new TeamHttpClient(_uri, _credentials))
   {
       IEnumerable<IdentityRef> results = teamHttpClient.GetTeamMembersAsync(_project, _team).Result;               
   }
}


A page at a time

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams?$top=1&$skip=1&api-version=2.2

Sample response

Status code: 200
{
  "value": [
    {
      "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
      "name": "Fabrikam-Fiber-TFVC Team",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd",
      "description": "The default project team.",
      "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/66df9be7-3586-467b-9c5f-425b29afedfd"
    }
  ],
  "count": 1
}

Create a team

Create a team in a team project

POST https://{instance}.VisualStudio.com/DefaultCollection/_apis/projects/{project}/teams?api-version={version}
Content-Type: application/json
{
    "name": {string},
    "description": {string}
}
Parameter Type Notes
URL
account string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of the project.
Query
api-version string Version of the API to use.
Body
name string Name of the team.
description string Description of the team.

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams?api-version=2.2
Content-Type: application/json
{
  "name": "My new team"
}

Sample response

Status code: 200
{
  "id": "8e8aa4ff-848a-474a-9033-93190137c8e4",
  "name": "My New Team",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams/8e8aa4ff-848a-474a-9033-93190137c8e4",
  "description": "",
  "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/8e8aa4ff-848a-474a-9033-93190137c8e4"
}

Sample Code

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

....

public class WebApiTeam
{
   public string id { get; set; }
   public string name { get; set; }
   public string url { get; set; }
   public string description { get; set; }
   public string identityUrl { get; set; }
}

public void CreateTeam()
{   
   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"; 

   //create a team object to save
   Object teamData = new { name = "My new team" };

   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(teamData), Encoding.UTF8, "application/json"); // mediaType needs to be application/json-patch+json for a patch call
       var method = new HttpMethod("POST");

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

       if (response.IsSuccessStatusCode)
       {
           WebApiTeam teamResponse = response.Content.ReadAsAsync<WebApiTeam>().Result;            
       }
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public CreateTeam()
{
   //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";

   WebApiTeam teamData = new WebApiTeam()
   {
       Name = "My new team"
   };

   using (TeamHttpClient teamHttpClient = new TeamHttpClient(_uri, _credentials))
   {
       WebApiTeam result = teamHttpClient.CreateTeamAsync(teamData, _project).Result;
   }
}

Update a team

Rename a team or change a team's description

PATCH https://{instance}.VisualStudio.com/DefaultCollection/_apis/projects/{project}/teams/{team}?api-version={version}
Content-Type: application/json
{
  "name": {string},
  "description": {string}
}
Parameter Type Notes
URL
account string Your Visual Studio Online account.
project string Name or ID of the project.
team string Name or ID of the team.
Query
api-version string Version of the API to use.
Body
name string New name of the team.
description string New description of the team.

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams?api-version=2.2
Content-Type: application/json
{
  "name": "My new team",
  "description": "Description of my team"
}

Sample response

Status code: 200
{
  "id": "8e8aa4ff-848a-474a-9033-93190137c8e4",
  "name": "My New Team",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams/8e8aa4ff-848a-474a-9033-93190137c8e4",
  "description": "Description of my team",
  "identityUrl": "https://fabrikam-fiber-inc.vssps.visualstudio.com/_apis/Identities/8e8aa4ff-848a-474a-9033-93190137c8e4"
}

Sample Code

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

....

public class WebApiTeam
{
   public string id { get; set; }
   public string name { get; set; }
   public string url { get; set; }
   public string description { get; set; }
   public string identityUrl { get; set; }
}

public void UpdateTeam()
{   
   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"; 
   string _team = "My team";

   //create a team object to save
   Object teamData = new { name = "My updated team", description = "my teams awesome description" };

   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(team), 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/projects/" + _project + "/teams/" + _team + "?api-version=2.2") { Content = patchValue };
       var response = client.SendAsync(request).Result;

       if (response.IsSuccessStatusCode)
       {
           WebApiTeam teamResponse = response.Content.ReadAsAsync<WebApiTeam>().Result;     
       }  
   }    
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public UpdateTeam()
{
   //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";
   string _team = "My team";

   WebApiTeam teamData = new WebApiTeam()
   {
       Name = "My updated team",
       Description = "my awesome team description"
   };

   using (TeamHttpClient teamHttpClient = new TeamHttpClient(_uri, _credentials))
   {
       WebApiTeam result = teamHttpClient.UpdateTeamAsync(teamData, _project, _team).Result;
   }
}

Delete a team

Permanently delete a team.

DELETE https://{instance}.VisualStudio.com/DefaultCollection/_apis/projects/{project}/teams/{team}?api-version={version}
Parameter Type Notes
URL
account string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of the project.
team string Name or ID of the team.
Query
api-version string Version of the API to use.

Sample request

DELETE https://fabrikam.VisualStudio.com/DefaultCollection/_apis/projects/fabrikam-fiber/teams/2ddc9d25-b0fe-45ed-97d1-d94c5a562c0b?api-version=2.2

Sample request

DELETE https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams/8e8aa4ff-848a-474a-9033-93190137c8e4?api-version=2.2

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 DeleteTeam()
{   
   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"; 
   string _team = "My team";

   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 method = new HttpMethod("DELETE");

       var request = new HttpRequestMessage(method, "https://accountname.visualstudio.com/_apis/projects/" + _project + "/teams/" + _team + "?api-version=2.2");
       var response = client.SendAsync(request).Result;        
   }
}
using Microsoft.TeamFoundation.Core.WebApi;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

...

public DeleteTeam()
{
   //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";
   string _team = "My team";  

   using (TeamHttpClient teamHttpClient = new TeamHttpClient(_uri, _credentials))
   {
       WebApiTeam result = teamHttpClient.DeleteTeamAsync(_project, _team).SyncResult();
   }
}