Team projects

Last Update: 7/14/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

Get project properties

Get a collection of team project properties.

GET https://{instance}/_apis/projects/{projectId}/properties?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.profile User profile (read) Grants the ability to read your profile, accounts, collections, projects, teams, and other top-level organizational artifacts.
vso.project Project and team (read) Grants the ability to read projects and teams.

Request parameters

Name In Type Notes
projectId URL GUID Required. The team project ID.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.
keys Query array (string) Optional. A comma-delimited string of team project property names. Wildcard characters ("?" and "*") are supported. If no key is specified, all properties will be returned.

Response

Type Notes
VssJsonCollectionWrapper<array (ProjectProperty)> A collection of team project properties.

Get all team project properties

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?api-version=4.0-preview

Sample response

Status code: 200
{
  "count": 8,
  "value": [
    {
      "name": "System.CurrentProcessTemplateId",
      "value": "2dc3221a-2d39-4138-a4e1-fc4d20d8912d"
    },
    {
      "name": "System.OriginalProcessTemplateId",
      "value": "2dc3221a-2d39-4138-a4e1-fc4d20d8912d"
    },
    {
      "name": "System.ProcessTemplateType",
      "value": "adcc42ab-9882-485e-a3ed-7678f01f66bc"
    },
    {
      "name": "System.Process Template",
      "value": "Agile"
    },
    {
      "name": "System.Microsoft.TeamFoundation.Team.Default",
      "value": "9b7ae5b9-826f-4353-99d6-daaa5cd94ec6"
    },
    {
      "name": "System.SourceControlCapabilityFlags",
      "value": "2"
    },
    {
      "name": "System.SourceControlGitEnabled",
      "value": "True"
    },
    {
      "name": "System.SourceControlGitPermissionsInitialized",
      "value": "True"
    }
  ]
}

Get specific team project properties

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?keys=System.CurrentProcessTemplateId,*SourceControl*&api-version=4.0-preview

Sample response

Status code: 200
{
  "count": 4,
  "value": [
    {
      "name": "System.CurrentProcessTemplateId",
      "value": "2dc3221a-2d39-4138-a4e1-fc4d20d8912d"
    },
    {
      "name": "System.SourceControlCapabilityFlags",
      "value": "2"
    },
    {
      "name": "System.SourceControlGitEnabled",
      "value": "True"
    },
    {
      "name": "System.SourceControlGitPermissionsInitialized",
      "value": "True"
    }
  ]
}

Set project properties

Create, update, and delete team project properties.

PATCH https://{instance}/_apis/projects/{projectId}/properties?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.project_write Project and team (read and write) Grants the ability to read and update projects and teams.

Request parameters

Name In Type Notes
projectId URL GUID Required. The team project ID.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.
Body JsonPatchDocument Required. A JSON Patch document that represents an array of property operations. See RFC 6902 for more details on JSON Patch. The accepted operation verbs are Add and Remove, where Add is used for both creating and updating properties. The path consists of a forward slash and a property name. Media Type: "application/json-patch+json"

Create or update a team project property

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?api-version=4.0-preview
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/Alias",
    "value": "Frabrikam"
  }
]

Sample response

Status code: 204

Delete a team project property

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?api-version=4.0-preview
Content-Type: application/json-patch+json
[
  {
    "op": "remove",
    "path": "/Alias"
  }
]

Sample response

Status code: 204