Projects

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

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 projects

Get all 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		TFS server name ({server:port}).
Query
api-version	string		Version of the API to use.
stateFilter	enum {   WellFormed,   CreatePending,   Deleting,   New,   All }	WellFormed	Return projects in a specific project state.
$top	integer	100	Number of projects to return.
$skip	integer	0	Number of projects to skip.

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects?api-version=1.0

Sample response

{
  "count": 3,
  "value": [
    {
      "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "name": "Fabrikam-Fiber-TFVC",
      "description": "Team Foundation Version Control projects.",
      "url": "https://mytfsserver/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://mytfsserver/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
      "state": "wellFormed"
    },
    {
      "id": "281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "name": "TestGit",
      "url": "https://mytfsserver/DefaultCollection/_apis/projects/281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "state": "wellFormed"
    }
  ]
}

Sample code

• C# (ListAllProjectsAndTeams method)

By state

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

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects?stateFilter=All&api-version=1.0

Sample response

{
  "count": 3,
  "value": [
    {
      "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
      "name": "Fabrikam-Fiber-TFVC",
      "description": "Team Foundation Version Control projects.",
      "url": "https://mytfsserver/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://mytfsserver/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
      "state": "wellFormed"
    },
    {
      "id": "281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "name": "TestGit",
      "url": "https://mytfsserver/DefaultCollection/_apis/projects/281f9a5b-af0d-49b4-a1df-fe6f5e5f84d0",
      "state": "wellFormed"
    }
  ]
}

Sample code

• C# (ListProjectsByState method)

A page at a time

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects?$top=1&$skip=1&api-version=1.0

Sample response

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

Get a project

GET https://{instance}/DefaultCollection/_apis/projects/{project}?api-version={version}[&includeCapabilities={boolean}&includeHistory={boolean}]

Parameter	Type	Default	Notes
URL
instance	string		TFS server name ({server:port}).
project	string		Name or ID of the project.
Query
api-version	string		Version of the API to use.
includeCapabilities	boolean	false	Use true to include capabilities (such as source control) in the 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 project, including its capabilities.

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects/Fabrikam-Fiber-TFVC?includeCapabilities=true&api-version=1.0

Sample response

{
  "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
  "name": "Fabrikam-Fiber-TFVC",
  "url": "https://mytfsserver/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://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1"
    },
    "collection": {
      "href": "https://mytfsserver/DefaultCollection/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16"
    },
    "web": {
      "href": "https://mytfsserver/DefaultCollection/Fabrikam-Fiber-TFVC"
    }
  },
  "defaultTeam": {
    "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"
  }
}

Sample code

• C# (GetProjectDetails method)

Create a project

Create a project in a VSTS organization. Use the GetOperation to periodically check for create project status.

POST https://{instance}/defaultcollection/_apis/projects?api-version={version}

Parameter	Type	Notes
URL
instance	string	TFS server name ({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://mytfsserver/DefaultCollection/_apis/projects?api-version=2.0-preview

{
  "name": "FabrikamTravel",
  "description": "Fabrikam 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://mytfsserver/DefaultCollection/_apis/operations/066488b8-b14e-43d1-befc-a2e655266e2b"
}

Sample code

• C# (CreateProject method)

Update a project

Update a 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	TFS server name ({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 project.
description	string	Description for the project.

Rename a project

Sample request

PATCH https://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1?api-version=2.0-preview

{
  "name": "Fabrikam-Fiber"
}

Sample response

{
  "id": "b5f386e9-c67d-4caf-8e78-4e58230c7e90",
  "status": "queued",
  "url": "https://mytfsserver/DefaultCollection/_apis/operations/b5f386e9-c67d-4caf-8e78-4e58230c7e90"
}

Sample code

• C# (RenameProject method)

Change a project description

Sample request

PATCH https://mytfsserver/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1?api-version=2.0-preview

{
  "description": "TFVC projects."
}

Sample response

{
  "id": "b5f386e9-c67d-4caf-8e78-4e58230c7e90",
  "status": "queued",
  "url": "https://mytfsserver/DefaultCollection/_apis/operations/b5f386e9-c67d-4caf-8e78-4e58230c7e90"
}

Sample code

• C# (ChangeProjectDescription method)

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		TFS server name ({server:port}).
operationId	string		ID of the operation.
Query
api-version	string		Version of the API to use.

Sample request

GET https://mytfsserver/DefaultCollection/_apis/operations/109787e4-3f2e-4fbb-af75-0be32e63e45d?api-version=2.0

Sample response

{
  "id": "109787e4-3f2e-4fbb-af75-0be32e63e45d",
  "status": "inProgress",
  "url": "https://mytfsserver/DefaultCollection/_apis/operations/109787e4-3f2e-4fbb-af75-0be32e63e45d",
  "_links": {
    "self": {
      "href": "https://mytfsserver/DefaultCollection/_apis/operations/109787e4-3f2e-4fbb-af75-0be32e63e45d"
    }
  }
}

Sample code

• C# (WaitForLongRunningOperation method)

Delete a project

Delete a 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	TFS server name ({server:port}).
id	string	ID for the 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

• C# (DeleteProject method)

Get project properties

Get a collection of 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 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 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 project properties.

Get all project properties

Sample request

GET https://mytfsserver/DefaultCollection/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?api-version=4.0-preview

Sample 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 project properties

Sample request

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

Sample 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 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 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 project property

Sample request

PATCH https://mytfsserver/DefaultCollection/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?api-version=4.0-preview

[
  {
    "op": "add",
    "path": "/Alias",
    "value": "Fabrikam"
  }
]

Delete a project property

Sample request

PATCH https://mytfsserver/DefaultCollection/_apis/projects/94e82dfb-8ce4-430c-aa97-07ee10c83d5f/properties?api-version=4.0-preview

[
  {
    "op": "remove",
    "path": "/Alias"
  }
]