{"id":10531,"library":"azure-devops-node-api","title":"Azure DevOps Node.js API Client","description":"The `azure-devops-node-api` package provides a robust and officially supported Node.js client for programmatically interacting with Azure DevOps Services and on-premises Team Foundation Server (TFS) REST APIs. It offers strongly typed interfaces for various services including Git, Build, Release, Work Items, and more, simplifying authentication and API calls compared to direct HTTP requests. The current stable version is 15.1.2, requiring Node.js >= 16.0.0. The library's release cadence is generally aligned with major Azure DevOps and TFS server updates, with significant version increments often indicating breaking changes tied to server compatibility and new features. Its key differentiator is providing a comprehensive, type-safe wrapper over the Azure DevOps REST APIs, making development more efficient and less error-prone.","status":"active","version":"15.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/azure-devops-node-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install azure-devops-node-api","lang":"bash","label":"npm"},{"cmd":"yarn add azure-devops-node-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add azure-devops-node-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used to establish the connection to Azure DevOps. CommonJS `require` works but `import` is preferred in modern Node.js environments.","wrong":"const WebApi = require('azure-devops-node-api/WebApi');","symbol":"WebApi","correct":"import { WebApi } from 'azure-devops-node-api/WebApi';"},{"note":"This function creates an authentication handler for Personal Access Tokens (PATs), the most common authentication method. Ensure the correct named import is used.","wrong":"import { PersonalAccessTokenHandler } from 'azure-devops-node-api/handlers/pat';","symbol":"getPersonalAccessTokenHandler","correct":"import { getPersonalAccessTokenHandler } from 'azure-devops-node-api/handlers/pat';"},{"note":"Specific API clients like `BuildApi`, `GitApi`, `CoreApi`, etc., are imported directly from their respective paths. Do not import the interface (`IBuildApi`) directly for instantiation.","wrong":"import { IBuildApi } from 'azure-devops-node-api/BuildApi';","symbol":"BuildApi","correct":"import { BuildApi } from 'azure-devops-node-api/BuildApi';"},{"note":"A common pattern for importing all public exports from the main entry point, useful for accessing various utilities and the `WebApi` class without individual path imports.","wrong":"const azdev = require('azure-devops-node-api').default;","symbol":"* as azdev","correct":"import * as azdev from 'azure-devops-node-api';"}],"quickstart":{"code":"import { WebApi } from 'azure-devops-node-api/WebApi';\nimport { getPersonalAccessTokenHandler } from 'azure-devops-node-api/handlers/pat';\nimport { BuildApi } from 'azure-devops-node-api/BuildApi';\n\nasync function listBuilds() {\n  const orgUrl = process.env.AZURE_DEVOPS_ORG_URL ?? 'https://dev.azure.com/your-organization';\n  const token = process.env.AZURE_DEVOPS_PAT ?? ''; // Ensure PAT has 'Build: Read' scope\n  const projectName = process.env.AZURE_DEVOPS_PROJECT_NAME ?? 'MyProject';\n\n  if (!token) {\n    console.error('AZURE_DEVOPS_PAT environment variable is not set.');\n    return;\n  }\n\n  try {\n    const authHandler = getPersonalAccessTokenHandler(token);\n    const connection = new WebApi(orgUrl, authHandler);\n    \n    // Get the Build API client\n    const buildApi: BuildApi = await connection.getBuildApi();\n\n    // List recent builds for a specific project\n    console.log(`Fetching builds for project: ${projectName}...`);\n    const builds = await buildApi.getBuilds(projectName, undefined, undefined, undefined, undefined, undefined, 5); // Get top 5 builds\n\n    if (builds.length === 0) {\n      console.log('No builds found.');\n      return;\n    }\n\n    console.log(`Found ${builds.length} recent builds:`)\n    for (const build of builds) {\n      console.log(`  - Build #${build.buildNumber}: ${build.status} - ${build.result ?? 'N/A'}`);\n    }\n  } catch (error: any) {\n    console.error('Error fetching builds:', error.message);\n    if (error.statusCode === 401) {\n      console.error('Check your PAT and organization URL. Ensure PAT has sufficient scopes.');\n    } else if (error.statusCode === 404) {\n      console.error('Project or organization URL not found.');\n    }\n  }\n}\n\nlistBuilds();\n","lang":"typescript","description":"This quickstart demonstrates how to authenticate with Azure DevOps using a Personal Access Token (PAT), establish a connection, obtain a `BuildApi` client, and list the most recent builds for a specified project."},"warnings":[{"fix":"Review the package's GitHub releases or npm history for specific version compatibility notes. Test upgrades thoroughly in non-production environments. Pay close attention to changes in API client instantiation or method signatures.","message":"Major version updates (e.g., from v6.x to v15.x) frequently introduce breaking changes, primarily due to updates in the underlying Azure DevOps REST API and compatibility with specific TFS server versions. Always consult the official release notes and migration guides when upgrading.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Verify the PAT's scopes in Azure DevOps User Settings -> Personal Access Tokens. Regenerate the PAT if expired or if scopes are insufficient. Test PAT validity using a simple API call.","message":"Authentication failures are common. Ensure your Personal Access Token (PAT) has the necessary scopes for the API calls you are making (e.g., 'Build: Read' for reading build data, 'Work Items: Read, Write' for modifying work items). PATs also have expiry dates.","severity":"gotcha","affected_versions":">=0.7.0"},{"fix":"Check the `npm` package page or GitHub releases for explicit minimum TFS/Azure DevOps Server version compatibility for your specific client library version. Downgrade `azure-devops-node-api` if necessary to match your server's version.","message":"The package maintains compatibility with specific minimum versions of TFS and Azure DevOps Server. Using a newer `azure-devops-node-api` version with an older, incompatible TFS instance will lead to runtime errors or missing functionalities. For example, `v6.6.2` supports TFS 2018 Update 2+, and earlier versions were tied to even older TFS releases.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Ensure your `tsconfig.json` (for TypeScript) or `package.json` (`\"type\": \"module\"`) is correctly configured for your chosen module system. Use `import ... from 'package';` syntax where possible. If encountering issues, try `import * as azdev from 'azure-devops-node-api';` or consult Node.js module documentation.","message":"When migrating to ESM or using modern Node.js module systems, be aware of potential import issues. While `require()` generally works for older versions or CommonJS environments, `import` statements are preferred and sometimes required for newer Node.js versions and environments.","severity":"gotcha","affected_versions":">=10.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Double-check the project name, repository ID, or other resource identifiers for typos. Ensure the PAT has sufficient permissions (e.g., 'Project and Team: Read', 'Code: Read'). Verify the organization URL is correct.","cause":"This error typically indicates that the requested resource (e.g., a project, repository, or build definition) does not exist, or the authenticated user does not have permission to access it within the specified organization or project.","error":"Error: TF400813: The resource cannot be found."},{"fix":"Generate a new PAT in Azure DevOps User Settings with the required scopes. Update the PAT in your application configuration. Ensure the organization URL is correct and accessible.","cause":"The Personal Access Token (PAT) used for authentication is either incorrect, expired, revoked, or does not have the necessary scopes to perform the requested operation.","error":"Error: Failed to authenticate (401 Unauthorized)"},{"fix":"Ensure you have successfully called `connection.getBuildApi()` (or similar for other APIs) and stored its result in a variable before attempting to call methods on it. Add `await` if `getBuildApi()` is an async call.","cause":"This error occurs when attempting to call an API method (e.g., `getBuilds`) on an API client that has not been correctly initialized or retrieved from the `WebApi` connection.","error":"TypeError: Cannot read properties of undefined (reading 'getBuilds')"},{"fix":"Verify your internet connection and DNS settings. Double-check the Azure DevOps organization URL for typos. If behind a proxy, ensure Node.js is configured to use it (e.g., via `HTTPS_PROXY` environment variable).","cause":"The Node.js environment could not resolve the hostname for the Azure DevOps organization URL. This is typically a network connectivity or DNS issue.","error":"Error: getaddrinfo ENOTFOUND dev.azure.com"}],"ecosystem":"npm"}