Azure DevOps Health Getting Started: Account Setup & First Request (2026)

Getting started overview

Getting started with Azure DevOps Health involves a sequence of steps to establish your development environment and enable programmatic access to your projects. The primary method for interacting with Azure DevOps services programmatically is through its Azure DevOps REST API, which supports various operations for managing builds, releases, work items, and more. Alternatively, developers can utilize official client libraries for .NET and Python to abstract much of the HTTP request complexity. Authentication is typically handled via Personal Access Tokens (PATs), which provide a secure and flexible way to grant specific permissions to applications or scripts without exposing full user credentials.

This guide focuses on the streamlined process of setting up an Azure DevOps organization, obtaining the necessary authentication credentials, and executing a foundational API request to confirm connectivity and permissions. Understanding these initial steps is crucial for any further integration or automation efforts within the Azure DevOps ecosystem, such as monitoring build health, tracking deployment statuses, or querying work item progress.

A quick reference for the getting started process is outlined in the table below:

Create an account and get keys

To begin using Azure DevOps Health, you need an Azure DevOps organization. If you don't already have one, you can create it by navigating to the Azure DevOps homepage and selecting "Start free with Azure DevOps". This process typically involves signing in with a Microsoft account and then specifying a name for your new organization. The organization name forms part of your base URL (e.g., https://dev.azure.com/your-organization-name), which is essential for all subsequent API calls.

Generating a Personal Access Token (PAT)

Once your organization is set up, the next critical step is to generate a Personal Access Token (PAT). PATs are the recommended authentication method for programmatic access to Azure DevOps and provide a more secure alternative to using your full credentials. To create a PAT:

1. Sign in to your Azure DevOps organization (e.g., https://dev.azure.com/your-organization-name).
2. In the top-right corner, click on your user icon and select Personal access tokens.
3. Click New Token.
4. Provide a descriptive Name for your token (e.g., "API Health Monitor").
5. Set an Expiration date for the token. For security best practices, choose the shortest duration necessary.
6. Under Scopes, select the specific permissions your application needs. For monitoring project health and listing projects, you'll typically need at least Project & Team > Read and possibly Build > Read or Release > Read, depending on the specific health metrics you intend to query. More granular control over scopes is detailed in the Azure DevOps PAT documentation.
7. Click Create.
8. Copy the generated PAT immediately. It will not be displayed again after you close the dialog. Store it securely, as it grants access to your Azure DevOps resources. Treat it like a password.

It's important to select only the necessary scopes to adhere to the principle of least privilege, minimizing potential security risks.

Your first request

After setting up your organization and generating a PAT, you can make your first API request to verify connectivity. This example demonstrates how to list all projects within your organization using the Azure DevOps REST API. We'll show examples using both curl for a direct HTTP request and Python for a client library approach.

First, ensure you have your organization URL and PAT readily available. For the purpose of this example, let's assume:

• Organization URL: https://dev.azure.com/your-organization-name
• Personal Access Token: YOUR_PAT_HERE

The base URL for the Azure DevOps REST API is typically https://dev.azure.com/{organization}/{project}/_apis/ or https://dev.azure.com/{organization}/_apis/ for organization-level resources. To list projects, we'll use the latter.

Using curl (REST API)

The curl command-line tool is excellent for making quick HTTP requests. Replace your-organization-name and YOUR_PAT_HERE with your actual values. The PAT needs to be Base64 encoded for Basic Authentication, which curl can handle directly when provided with a username (which is empty for PATs) and the PAT as the password.

curl -u :YOUR_PAT_HERE \
     https://dev.azure.com/your-organization-name/_apis/projects?api-version=7.1-preview.4

This command sends a GET request to the projects API endpoint. The -u :YOUR_PAT_HERE flag tells curl to use Basic Authentication with an empty username and your PAT as the password. The api-version parameter is crucial for specifying the desired API version; always refer to the Azure DevOps Projects List documentation for the latest stable version.

A successful response will return a JSON object containing a list of your projects, similar to this (truncated for brevity):

{
  "count": 1,
  "value": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "MyFirstProject",
      "description": "A sample project.",
      "url": "https://dev.azure.com/your-organization-name/_apis/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "state": "wellFormed",
      "revision": 1
    }
  ]
}

Using Python Client Library

For a more structured approach, especially for complex integrations, using the official Python client library is recommended. First, install the necessary package:

pip install azure-devops

Then, you can write a Python script:

from azure.devops.connection import Connection
from msrest.authentication import BasicAuthentication
import os

# Retrieve organization URL and PAT from environment variables for security
organization_url = os.environ.get("AZURE_DEVOPS_ORG_URL", "https://dev.azure.com/your-organization-name")
personal_access_token = os.environ.get("AZURE_DEVOPS_PAT", "YOUR_PAT_HERE")

# Create a connection to the organization
credentials = BasicAuthentication('', personal_access_token)
connection = Connection(base_url=organization_url, creds=credentials)

# Get a client for core operations
core_client = connection.clients.get_core_client()

# Get the list of projects
try:
    projects = core_client.get_projects()
    print("Projects in organization:")
    for project in projects:
        print(f"  - {project.name} (ID: {project.id})")
except Exception as e:
    print(f"An error occurred: {e}")

Remember to set the AZURE_DEVOPS_ORG_URL and AZURE_DEVOPS_PAT environment variables or replace the placeholders directly in the script. Using environment variables is a common security practice for API credentials.

Common next steps

After successfully making your first API call, several common next steps can deepen your integration with Azure DevOps Health:

• Explore More APIs: Dive into the Azure DevOps REST API documentation to discover endpoints relevant to your monitoring needs, such as build statuses, release deployments, test results, or work item queries. For example, you might want to fetch the status of the latest build for a specific pipeline.
• Implement Webhooks: Configure webhooks to receive real-time notifications about events in Azure DevOps (e.g., build completion, pull request updates). This proactive approach helps in building responsive health monitoring systems. Details on Azure DevOps webhooks configuration are available in the documentation.
• Utilize SDKs: For more complex applications, continue using the Azure DevOps .NET or Python client libraries. These SDKs simplify interaction with the API by providing strongly typed objects and handling authentication details, reducing boilerplate code.
• Integrate with Monitoring Tools: Connect Azure DevOps data with external monitoring and alerting platforms like Azure Monitor, Grafana, or custom dashboards. This often involves parsing API responses and pushing metrics to these systems.
• Automate Reporting: Develop scripts or applications to generate regular reports on key health indicators, such as build success rates, deployment frequency, or open bug counts, using the data retrieved from the APIs.
• CI/CD Pipeline Integration: Incorporate API calls directly into your Azure Pipelines to automate checks or trigger actions based on the health status of other components or services.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some common problems and their solutions:

• 401 Unauthorized Error:
  • Incorrect PAT: Double-check that you copied the PAT correctly. Remember it's only shown once. If unsure, generate a new one.
  • Expired PAT: Verify the PAT's expiration date. Generate a new token if it has expired.
  • Insufficient Scopes: Ensure the PAT has the necessary scopes. For listing projects, Project & Team > Read is required. If querying build or release data, ensure corresponding read scopes are granted. Consult the PAT scope documentation for specific API requirements.
  • Incorrect Basic Authentication Header: For curl, ensure the -u :YOUR_PAT_HERE format is correct. The colon before the PAT is crucial to indicate an empty username.
• 404 Not Found Error:
  • Incorrect Organization URL: Verify that your organization URL (e.g., https://dev.azure.com/your-organization-name) is spelled correctly and matches your Azure DevOps organization's URL.
  • Incorrect API Endpoint: Ensure the API endpoint path is correct (e.g., _apis/projects). Refer to the Azure DevOps REST API reference for accurate paths.
  • Incorrect API Version: The api-version parameter is mandatory and specific. Ensure you are using a valid and current API version (e.g., api-version=7.1-preview.4).
• JSON Parsing Errors:
  • Invalid Response: If the API returns an error message that isn't valid JSON, your parsing logic might fail. Check the raw response content for any server-side errors or HTML output that indicates a misconfigured request.
  • Missing Libraries: For Python, ensure azure-devops and msrest libraries are installed if you are using the client library approach.
• Network Connectivity Issues:
  • Firewall/Proxy: If you are behind a corporate firewall or proxy, ensure it is configured to allow outbound connections to dev.azure.com.

When troubleshooting, it's often helpful to start with the simplest possible request (like listing projects) to isolate authentication and URL issues before moving to more complex API calls. Reviewing the Azure DevOps rate limits documentation can also be useful if you are making a large number of requests.