Get started with the REST APIs

Last Updated: 7/8/2016

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}[:{personalaccesstoken}] 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}[:{personalaccesstoken}] https://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

The examples above use personal access tokens, which requires that you create a personal access token.

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

Verb	Used for...
GET	Get a resource or list of resources
POST	Create a resource Get a list of resources using a more advanced query
PUT	Create a resource if it doesn't exist or, if it does, update it
PATCH	Update a resource
DELETE	Delete 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

Response	Notes
200	Success, and there is a response body.
201	Success, 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.
204	Success, and there is no response body. For example, you'll get this when you delete a resource.
400	The parameters in the URL or in the request body aren't valid.
403	The authenticated user doesn't have permission to perform the operation.
404	The resource doesn't exist, or the authenticated user doesn't have permission to see that it exists.
409	There'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.

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)

Versions of the REST APIs for Visual Studio Team Services

Visual Studio Team Services REST APIs are versioned to ensure client applications and services work as APIs are added and changed.

The current version of the API set is 1.0.

API version must be specified with every request.
API versions are in the format {major}.{minor}[-{stage}] - For example, 1.0, 1.1, 1.2-preview, 2.0.
During a preview APIs are subject to change, but you can specify a precise version of a particular API when needed (For example, 1.0-preview.1, 1.0-preview.2)
Once an API is released (1.0, for example), its preview version (1.0-preview) is deprecated and can be deactivated after 12 weeks.
During this time you should upgrade to the released version of the API. Once a preview API is deactivated, requests that specify a -preview version will be rejected.

API version can be specified either in the header of the HTTP request or as a URL query parameter:

HTTP request header:

Accept: application/json;api-version=1.0

Query parameter:

GET https://{account}.visualstudio.com/defaultcollection/_apis/{area}/{resource}?api-version=1.0

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.

Shared to