Get started with the REST APIs

Integrate your app with VS Team Services and TFS using these REST APIs.

These APIs follow a common pattern:

VERB https://{instance}[/{collection}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}
Tip: To avoid having your app or service broken as APIs evolve, specify an API version on every request.

VS Team Services

For VS Team Services, instance is {account}.visualstudio.com and collection is DefaultCollection, so the pattern looks like this:

VERB https://{account}.VisualStudio.com/DefaultCollection/_apis[/{area}]/{resource}?api-version={version}

For example, here's how to get a list of team projects in a Visual Studio Team Services account.

curl -u {username}[:{password}] https://{account}.VisualStudio.com/DefaultCollection/_apis/projects?api-version=2.0

If you don't have a Visual Studio Team Services account, you can set one up for free.

Later, we'll look at the other options, including OAuth.

TFS

For TFS, instance is {server:port} and by default the port is 8080. The default collection is DefaultCollection, but can be any collection.

Here's how to get a list of team projects from TFS using the default port and collection.

curl -u {username}[:{password}] https://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

The examples above use basic authentication, which requires that you enable alternate credentials.

Responses

You should get a response like this.

{
    "value": [
        {
            "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": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

The response is JSON. That's generally what you'll get back from the REST APIs, although there are a few exceptions, like Git blobs.

Now you should be able to look around the specific API areas like work item tracking or Git and get to the resources that you need. Keep reading to learn more about the general patterns that are used in these APIs.

HTTP verbs

VerbUsed for...
GETGet a resource or list of resources
POSTCreate a resource
Get a list of resources using a more advanced query
PUTCreate a resource if it doesn't exist or, if it does, update it
PATCHUpdate a resource
DELETEDelete a resource

Request headers and request content

When you provide request body (usually with the POST, PUT and PATCH verbs), include request headers that describe the body. For example,

POST https://fabrikam-fiber-inc.VisualStudio.com/DefaultCollection/_apis/build/requests
Content-Type: application/json
{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

HTTP method override

Some web proxies may only support the HTTP verbs GET and POST, but not more modern HTTP verbs like PATCH and DELETE. If your calls may pass through one of these proxies, you can send the actual verb using a POST method, with a header to override the method. For example, you may want to update a work item (PATCH _apis/wit/workitems/3), but you may have to go through a proxy that only allows GET or POST. You can pass the proper verb (PATCH in this case) as an HTTP request header parameter and use POST as the actual HTTP method.

POST _apis/wit/workitems/3
X-HTTP-Method-Override: PATCH
{
   (PATCH request body)
}

Response codes

ResponseNotes
200Success, and there is a response body.
201Success, when creating resources. Some APIs return 200 when successfully creating a resource. Look at the docs for the API you're using to be sure.
204Success, and there is no response body. For example, you'll get this when you delete a resource.
400The parameters in the URL or in the request body aren't valid.
403The authenticated user doesn't have permission to perform the operation.
404The resource doesn't exist, or the authenticated user doesn't have permission to see that it exists.
409There's a conflict between the request and the state of the data on the server. For example, if you attempt to submit a pull request and there is already a pull request for the commits, the response code is 409.

Auth

You can use basic authentication with your app while you're just getting the integration to work. To avoid your users having to sign in to yet another service, implement OAuth integration.

Cross-origin resource sharing (CORS)

Visual Studio Team Services supports CORS. This enables JavaScript code served from a domain other than *.visualstudio.com to make Ajax requests to Visual Studio Team Services REST APIs. For this to work, each request must provide credentials (personal access tokens and OAuth access tokens are both supported options). Example:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://fabrikam.visualstudio.com/defaultcollection/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

(replace myPatToken with a personal access token)

Help and feedback

Get your technical questions answerd, request a feature, or reporting a bug on the support page.

Q&A

Q: Is there a .NET library that I can use to access the web APIs?

A: Yes, see the overview of client libraries.