Teams

Article
08/04/2016

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 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://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams?api-version=2.2

Sample response

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

Sample code

C# (ListOrderedTeams method)

A page at a time

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams?$top=1&$skip=1&api-version=2.2

Sample response

{
  "value": [
    {
      "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
      "name": "Fabrikam-Fiber-TFVC Team",
      "url": "https://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd",
      "description": "The default project team.",
      "identityUrl": "https://mytfsserver/DefaultCollection/_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://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca?api-version=2.2

Sample response

{
  "id": "564e8204-a90b-4432-883b-d4363c6125ca",
  "name": "Quality assurance",
  "url": "https://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca",
  "description": "Testing staff",
  "identityUrl": "https://mytfsserver/DefaultCollection/_apis/Identities/564e8204-a90b-4432-883b-d4363c6125ca"
}

Sample code

C# (GetTeam method)

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://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/564e8204-a90b-4432-883b-d4363c6125ca/members/?api-version=2.2

Sample response

{
  "value": [
    {
      "id": "3b5f0c34-4aec-4bf4-8708-1d36f0dbc468",
      "displayName": "Christie Church",
      "uniqueName": "fabrikamfiber1@hotmail.com",
      "url": "https://mytfsserver/DefaultCollection/_apis/Identities/3b5f0c34-4aec-4bf4-8708-1d36f0dbc468",
      "imageUrl": "https://mytfsserver/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://mytfsserver/DefaultCollection/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
      "imageUrl": "https://mytfsserver/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://mytfsserver/DefaultCollection/_apis/Identities/19d9411e-9a34-45bb-b985-d24d9d87c0c9",
      "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=19d9411e-9a34-45bb-b985-d24d9d87c0c9"
    }
  ],
  "count": 3
}

Sample code

C# (GetTeamMembers method)

A page at a time

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams?$top=1&$skip=1&api-version=2.2

Sample response

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

Create a team

Create a team in a 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://mytfsserver/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams?api-version=2.2

{
  "name": "My new team"
}

Sample response

{
  "id": "8e8aa4ff-848a-474a-9033-93190137c8e4",
  "name": "My New Team",
  "url": "https://mytfsserver/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams/8e8aa4ff-848a-474a-9033-93190137c8e4",
  "description": "",
  "identityUrl": "https://mytfsserver/DefaultCollection/_apis/Identities/8e8aa4ff-848a-474a-9033-93190137c8e4"
}

Sample code

C# (CreateTeam method)

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://mytfsserver/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams?api-version=2.2

{
  "name": "My new team",
  "description": "Description of my team"
}

Sample response

{
  "id": "8e8aa4ff-848a-474a-9033-93190137c8e4",
  "name": "My New Team",
  "url": "https://mytfsserver/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams/8e8aa4ff-848a-474a-9033-93190137c8e4",
  "description": "Description of my team",
  "identityUrl": "https://mytfsserver/DefaultCollection/_apis/Identities/8e8aa4ff-848a-474a-9033-93190137c8e4"
}

Sample code

C# (RenameTeam method)

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://mytfsserver/DefaultCollection/_apis/projects/8e5a3cfb-fed3-46f3-8657-e3b175cd0305/teams/8e8aa4ff-848a-474a-9033-93190137c8e4?api-version=2.2

Sample code

C# (DeleteTeam method)

Share via

Teams

Get a list of teams

Sample request

Sample response

Sample code

A page at a time

Sample request

Sample response

Get a team

Sample request

Sample response

Sample code

Get a team's members

Sample request

Sample response

Sample code

A page at a time

Sample request

Sample response

Create a team

Sample request

Sample response

Sample code

Update a team

Sample request

Sample response

Sample code

Delete a team

Sample request

Sample request

Sample code

Additional resources