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.0Sample response
{
"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.0Sample response
{
"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.0Sample response
{
"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.0Sample response
{
"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-previewContent-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
{
"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-previewContent-Type: application/json{
"name": "Fabrikam-Fiber"
}Sample response
{
"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-previewContent-Type: application/json{
"description": "TFVC projects."
}Sample response
{
"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.0Sample response
{
"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-previewSample response
{
"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-previewSample response
{
"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-previewContent-Type: application/json-patch+json[
{
"op": "add",
"path": "/Alias",
"value": "Frabrikam"
}
]Sample response
Status code: 204Delete 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-previewContent-Type: application/json-patch+json[
{
"op": "remove",
"path": "/Alias"
}
]