Teams

Last Update: 7/14/2017

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

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

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

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

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

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