Partager via

Projects

  • Article

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

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

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

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

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

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

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

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

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"
  }
]