Get started with the REST APIs

Integrate your app with Visual Studio Online using these REST APIs.

Most APIs follow a common pattern:

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

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

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

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

Tip: To avoid having your app or service broken as APIs evolve, specify an API version on every request.

The example above is using basic authentication, which requires that you enable alternate credentials. We'll look at the other options, includuing OAuth, later.

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 Visual Studio 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.

Authorization

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.

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.