Team projects

Last Update: 4/24/2017

api-version = 1.0

Team projects contain source code, work items, and other resources.

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

Get a list of team projects

Get all team projects in the project collection that the authenticated user has access to.

GET https://{instance}/DefaultCollection/_apis/projects?api-version={version}[&stateFilter{string}&$top={integer}&skip={integer}]
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.
stateFilter enum {
  WellFormed,
  CreatePending,
  Deleting,
  New,
  All
}
WellFormed Return team projects in a specific team project state.
$top integer 100 Number of team projects to return.
$skip integer 0 Number of team projects to skip.

Sample request

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

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "name": "Fabrikam-Fiber-TFVC",
      "description": "Team Foundation Version Control projects.",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "state": "wellFormed"
    },
    {
      "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
      "name": "Fabrikam-Fiber-Git",
      "description": "Git projects",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
      "state": "wellFormed"
    },
    {
      "id": "281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "name": "TestGit",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "state": "wellFormed"
    }
  ]
}

Sample code

By state

State Name Explanation
All All team projects regardless of state.
CreatePending Team project has been queued for creation, but the process has not yet started.
Deleting Team project is in the process of being deleted.
New Team project is in the process of being created.
WellFormed Default: Team project is completely created and ready to use.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects?stateFilter=All&api-version=1.0

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "name": "Fabrikam-Fiber-TFVC",
      "description": "Team Foundation Version Control projects.",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "state": "wellFormed"
    },
    {
      "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
      "name": "Fabrikam-Fiber-Git",
      "description": "Git projects",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
      "state": "wellFormed"
    },
    {
      "id": "281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "name": "TestGit",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "state": "wellFormed"
    }
  ]
}

Sample code

A page at a time

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects?$top=1&$skip=1&api-version=1.0

Sample response

Status code: 200
{
  "count": 1,
  "value": [
    {
      "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "name": "Fabrikam-Fiber-TFVC",
      "description": "Team Foundation Version Control projects.",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "state": "wellFormed"
    }
  ]
}

Get a team project

GET https://{instance}/DefaultCollection/_apis/projects/{project}?api-version={version}[&includeCapabilities={boolean}&includeHistory={boolean}]
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Name or ID of the team project.
Query
api-version string Version of the API to use.
includeCapabilites boolean false Use true to include capabilities (such as source control) in the team project result.
includeHistory boolean false Use true to search within renamed projects that had such name in the past.

With capabilities

Get metadata on a team project, including its capabilities.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/Fabrikam-Fiber-TFVC?includeCapabilities=true&api-version=1.0

Sample response

Status code: 200
{
  "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
  "name": "Fabrikam-Fiber-TFVC",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
  "description": "Team Foundation Version Control projects.",
  "state": "wellFormed",
  "capabilities": {
    "versioncontrol": {
      "sourceControlType": "Tfvc"
    },
    "processTemplate": {
      "templateName": "Microsoft Visual Studio Scrum 2013"
    }
  },
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1"
    },
    "collection": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16"
    },
    "web": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/Fabrikam-Fiber-TFVC"
    }
  },
  "defaultTeam": {
    "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"
  }
}

Sample code

Create a team project

Create a team project in a Visual Studio Team Services account. Use the [GetOperation](#GetOperation) to periodically check for create project status.

POST https://{instance}/defaultcollection/_apis/projects?api-version={version}
Parameter Type 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.
Request Body
name string Name for the project.
description string Description for the project.
capabilities.versioncontrol.sourceControlType enum { Git, Tfvc } Version control type for the project.
capabilities.processTemplate.templateTypeId string Software development schema for the project. See the processes REST API for how to retrieve the list of available processes and their corresponding IDs.

Sample request

POST https://fabrikam.visualstudio.com/defaultcollection/_apis/projects?api-version=2.0-preview
Content-Type: application/json
{
  "name": "FabrikamTravel",
  "description": "Frabrikam travel app for Windows Phone",
  "capabilities": {
    "versioncontrol": {
      "sourceControlType": "Git"
    },
    "processTemplate": {
      "templateTypeId": "6b724908-ef14-45cf-84f8-768b5384da45"
    }
  }
}

Sample response

Status code: 202
{
  "id": "066488b8-b14e-43d1-befc-a2e655266e2b",
  "status": "queued",
  "url": "https://fabrikam.visualstudio.com/DefaultCollection/_apis/operations/066488b8-b14e-43d1-befc-a2e655266e2b"
}

Sample code

Update a team project

Update a team project's description or name. Use the GetOperation to periodically check for update project status.

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

Rename a team project

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1?api-version=2.0-preview
Content-Type: application/json
{
  "name": "Fabrikam-Fiber"
}

Sample response

Status code: 202
{
  "id": "b5f386e9-c67d-4caf-8e78-4e58230c7e90",
  "status": "queued",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/operations/b5f386e9-c67d-4caf-8e78-4e58230c7e90"
}

Sample code

Change a team project description

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1?api-version=2.0-preview
Content-Type: application/json
{
  "description": "TFVC projects."
}

Sample response

Status code: 202
{
  "id": "b5f386e9-c67d-4caf-8e78-4e58230c7e90",
  "status": "queued",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/operations/b5f386e9-c67d-4caf-8e78-4e58230c7e90"
}

Sample code

Get an operation

Monitor the progress of an asynchronous REST API call.

GET https://{instance}/defaultcollection/_apis/operations/{operationid}?api-version={version}
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
operationId string ID of the operation.
Query
api-version string Version of the API to use.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/operations/109787e4-3f2e-4fbb-af75-0be32e63e45d?api-version=2.0

Sample response

Status code: 200
{
  "id": "109787e4-3f2e-4fbb-af75-0be32e63e45d",
  "status": "inProgress",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/operations/109787e4-3f2e-4fbb-af75-0be32e63e45d",
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/operations/109787e4-3f2e-4fbb-af75-0be32e63e45d"
    }
  }
}

Sample code

Delete a team project

Delete a team project. Use the GetOperation to periodically check for delete project status.

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

Sample request

DELETE https://fabrikam.visualstudio.com/DefaultCollection/_apis/projects/98dd5ded-8110-459b-8241-3d12b2eeaf18?api-version=1.0

Sample response

Status Code: 204

Sample code