Edit

Share via

Get started with the REST APIs

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Azure DevOps REST APIs provide powerful programmatic access to work items, repositories, builds, releases, and more. Whether you're building custom integrations, automating workflows, or extending Azure DevOps capabilities, understanding the fundamental patterns and concepts is essential for successful implementation.

Tip

Ready to start coding? Skip to REST API samples for complete working examples with modern authentication patterns.

This article covers the fundamental concepts and patterns for Azure DevOps REST APIs. For practical implementation examples, see REST API samples.

URL structure

The APIs follow a common pattern, as shown in the following example:

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

Tip

As APIs evolve, we recommend that you include an API version in every request. This practice can help you avoid unexpected changes in the API that could break.

Azure DevOps Services

For Azure DevOps Services, instance is dev.azure.com/{organization} and collection is DefaultCollection, so the pattern looks like the following example:

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

Example endpoint:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Azure DevOps Server

For Azure DevOps Server, instance is {server:port}. The default port for a non-SSL connection is 8080.

The default collection is DefaultCollection, but you can use any collection.

Examples:

  • SSL: https://{server}/DefaultCollection/_apis/projects?api-version=7.2
  • Non-SSL: http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

Authentication

Azure DevOps REST APIs support several authentication methods:

  • Microsoft Entra ID - Recommended for production applications
  • Personal Access Tokens (PATs) - Simple authentication for scripts and testing
  • OAuth 2.0 - For non-Microsoft applications
  • Service principals - For automated scenarios

Important

Microsoft Entra ID authentication is the recommended approach for production applications. For implementation examples and complete authentication guidance, see REST API samples and Authentication guidance.

Response format

Azure DevOps REST APIs typically return JSON responses. Here's an example response structure:

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "TeamFoundationVersionControlprojects"
        }
    ],
    "count": 1
}

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

Tip

For complete working examples showing how to parse these responses, see REST API samples.

HTTP methods and operations

Azure DevOps REST APIs use standard HTTP methods:

Method Used for... Example
GET Get a resource or list of resources Get projects, work items
POST Create a resource, or get resources using advanced queries Create work items, query work items
PUT Create or completely replace a resource Create/update work item
PATCH Update specific fields of a resource Update work item fields
DELETE Delete a resource Delete work item

Tip

For practical examples of each HTTP method with complete code samples, see REST API samples.

Request headers and content

When you provide a request body (usually with POST, PUT, and PATCH), include appropriate headers:

Content-Type: application/json

For PATCH operations on work items, use:

Content-Type: application/json-patch+json

HTTP method override

Some web proxies might only support the HTTP verbs GET and POST, but not more modern HTTP verbs like PATCH and DELETE. If your calls might 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 might want to update a work item (PATCH _apis/wit/workitems/3), but you might 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 https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Response codes

Understanding HTTP response codes helps you handle API responses appropriately:

Response Meaning Notes
200 Success Response body contains requested data
201 Created Resource successfully created
204 Success No response body (common with DELETE)
400 Bad Request Invalid parameters or request body
401 Unauthorized Authentication failed or missing
403 Forbidden User lacks permission for operation
404 Not Found Resource doesn't exist or no permission to view
409 Conflict Request conflicts with current resource state

API versioning

Azure DevOps REST APIs are versioned to ensure applications continue working as APIs evolve.

Guidelines

  • Always specify the API version with every request (required)
  • Format API versions as: {major}.{minor} or {major}.{minor}-{stage} (for example, 7.2, 7.2-preview)
  • Use specific preview revisions when available: 7.2-preview.1, 7.2-preview.2
  • Upgrade to released versions when preview APIs are deprecated

Usage

Specify the API version as a URL query parameter:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Or in the request header:

Accept: application/json;api-version=7.2

For supported versions, see REST API versioning.

More resources

For practical implementation guidance and complete code examples, see:

Next steps

Try REST API samples