azure-devops

What this skill does

# Azure DevOps API Skill

## Security

**Never output, suggest, or generate code that embeds PAT values verbatim.** Always reference credentials via environment variables (e.g., `$AZURE_DEVOPS_PAT`) or a secrets manager such as Azure Key Vault. When generating scripts or curl examples, use placeholder variable references — never literal token strings.

This skill provides comprehensive guidance for working with the Azure DevOps REST API, enabling programmatic access to all Azure DevOps Services and Azure DevOps Server resources.

## Overview

Azure DevOps REST API is a RESTful web API enabling you to access and manage work items, repositories, pipelines, test plans, artifacts, and more across all Azure DevOps services.

**Base URL:** `https://dev.azure.com/{organization}/{project}/_apis/{area}/{resource}?api-version={version}`
- **Organization:** Your Azure DevOps organization name
- **Project:** Project name (optional for org-level resources)
- **API Version:** Required on all requests (e.g., `7.1`, `7.0`, `6.0`)
- **Authentication:** Personal Access Tokens (PAT), OAuth 2.0, or Azure AD

## Quick Start

### Authentication Requirements

Azure DevOps supports multiple authentication methods:

1. **Personal Access Token (PAT)** - Most common for scripts and integrations
2. **OAuth 2.0** - For web applications
3. **Azure Active Directory** - For enterprise applications
4. **SSH Keys** - For Git operations only

### Basic PAT Authentication
```http
GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.1
Authorization: Basic {base64-encoded-PAT}
```

To encode PAT: `base64(":{PAT}")` — Note the colon before the PAT. Always read the PAT from an environment variable (e.g., `$AZURE_DEVOPS_PAT`) rather than hardcoding it in scripts or outputs.

### Common Request Pattern
```http
GET https://dev.azure.com/{organization}/{project}/_apis/{resource}?api-version=7.1
Authorization: Basic {encoded-PAT}
Content-Type: application/json
```

## Core Services

Azure DevOps is organized into major service areas. Each area has its own set of REST APIs:

### Azure Boards - Work Item Tracking

**Work Items**
- **Create work item:** `POST /{organization}/{project}/_apis/wit/workitems/${type}?api-version=7.1`
- **Get work item:** `GET /{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1`
- **Update work item:** `PATCH /{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1`
- **Delete work item:** `DELETE /{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1`

Request body uses JSON Patch format:
```json
[
  {
    "op": "add",
    "path": "/fields/System.Title",
    "value": "New bug report"
  },
  {
    "op": "add",
    "path": "/fields/System.AssignedTo",
    "value": "[email protected]"
  }
]
```

**Queries**
- **Run stored query:** `GET /{organization}/{project}/_apis/wit/wiql/{id}?api-version=7.1`
- **Run WIQL query:** `POST /{organization}/{project}/_apis/wit/wiql?api-version=7.1`
  ```json
  {
    "query": "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] = 'Active'"
  }
  ```

**Boards & Backlogs**
- **Get boards:** `GET /{organization}/{project}/{team}/_apis/work/boards?api-version=7.1`
- **Get backlog items:** `GET /{organization}/{project}/{team}/_apis/work/backlogs/{backlogId}/workItems?api-version=7.1`
- **Get iterations:** `GET /{organization}/{project}/{team}/_apis/work/teamsettings/iterations?api-version=7.1`
- **Get capacity:** `GET /{organization}/{project}/{team}/_apis/work/teamsettings/iterations/{iterationId}/capacities?api-version=7.1`

**Work Item Types & Fields**
- **List work item types:** `GET /{organization}/{project}/_apis/wit/workitemtypes?api-version=7.1`
- **List fields:** `GET /{organization}/{project}/_apis/wit/fields?api-version=7.1`
- **Get field:** `GET /{organization}/{project}/_apis/wit/fields/{fieldNameOrRefName}?api-version=7.1`

**Area & Iteration Paths**
- **Get areas:** `GET /{organization}/{project}/_apis/wit/classificationnodes/areas?api-version=7.1`
- **Get iterations:** `GET /{organization}/{project}/_apis/wit/classificationnodes/iterations?api-version=7.1`
- **Create area:** `POST /{organization}/{project}/_apis/wit/classificationnodes/areas?api-version=7.1`

### Azure Repos - Source Control

**Git Repositories**
- **List repositories:** `GET /{organization}/{project}/_apis/git/repositories?api-version=7.1`
- **Get repository:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}?api-version=7.1`
- **Create repository:** `POST /{organization}/{project}/_apis/git/repositories?api-version=7.1`
- **Delete repository:** `DELETE /{organization}/{project}/_apis/git/repositories/{repositoryId}?api-version=7.1`

**Commits**
- **Get commits:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/commits?api-version=7.1`
- **Get commit:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/commits/{commitId}?api-version=7.1`
- **Get commit changes:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/commits/{commitId}/changes?api-version=7.1`

**Branches**
- **Get branches:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/refs?filter=heads/&api-version=7.1`
- **Create branch:** `POST /{organization}/{project}/_apis/git/repositories/{repositoryId}/refs?api-version=7.1`
- **Delete branch:** `POST /{organization}/{project}/_apis/git/repositories/{repositoryId}/refs?api-version=7.1`
  ```json
  [
    {
      "name": "refs/heads/feature-branch",
      "oldObjectId": "0000000000000000000000000000000000000000",
      "newObjectId": "{commitId}"
    }
  ]
  ```

**Pull Requests**
- **Get pull requests:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1`
- **Get pull request:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}?api-version=7.1`
- **Create pull request:** `POST /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1`
  ```json
  {
    "sourceRefName": "refs/heads/feature",
    "targetRefName": "refs/heads/main",
    "title": "PR Title",
    "description": "PR Description"
  }
  ```
- **Update pull request:** `PATCH /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}?api-version=7.1`
- **Get PR reviewers:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/reviewers?api-version=7.1`
- **Add PR reviewer:** `PUT /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/reviewers/{reviewerId}?api-version=7.1`
- **Get PR work items:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/workitems?api-version=7.1`
- **Get PR threads:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/threads?api-version=7.1`
- **Add PR comment:** `POST /{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/threads?api-version=7.1`

**Pushes**
- **Get pushes:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pushes?api-version=7.1`
- **Get push:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/pushes/{pushId}?api-version=7.1`

**Items (Files & Folders)**
- **Get item:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/items?path={path}&api-version=7.1`
- **Get item content:** `GET /{organization}/{project}/_apis/git/repositories/{repositoryId}/items?path={path}&download=true&api-version=7.1`
- **Get items batch:** `POST /{organization}/{project}/_apis/git/repositories/{repositoryId}/itemsbatch?api-version=7.1`

**Policies**
- **Get policy configurations:** `GET /{organization}/{project}/_apis/policy/configurations?api-version=7.1`
- **Create policy:** `POST /{organization}/{project}/_apis/policy/configurations?api