Skip to content
Skills Library
DevOps & cloud · Learning & explanation

azure-devops-rest-api

/azure-devops-rest-api

Guide for working with Azure DevOps REST APIs and OpenAPI specifications. Use this skill when implementing new Azure DevOps API integrations, exploring API capabilities, understanding request/response formats, or referencing the official OpenAPI specifications from the vsts-rest-api-specs repository.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
2
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/clone_specs.sh, scripts/find_endpoint.py

What it does and when to use it

Guide for working with Azure DevOps REST APIs and OpenAPI specifications. Use this skill when implementing new Azure DevOps API integrations, exploring API capabilities, understanding request/response formats, or referencing the official OpenAPI specifications from the vsts-rest-api-specs repository.

Original author description

Guide for working with Azure DevOps REST APIs and OpenAPI specifications. Use this skill when implementing new Azure DevOps API integrations, exploring API capabilities, understanding request/response formats, or referencing the official OpenAPI specifications from the vsts-rest-api-specs repository.

How it works

  1. Overview
  2. Key API Areas
  3. API Specification Structure
  4. Implementation Patterns
  5. Reference Resources
  6. Integration with This Repository
Original SKILL.md headings · 149 lines, 820 words
SKILL.md preview
---
name: azure-devops-rest-api
description: Guide for working with Azure DevOps REST APIs and OpenAPI specifications. Use this skill when implementing new Azure DevOps API integrations, exploring API capabilities, understanding request/response formats, or referencing the official OpenAPI specifications from the vsts-rest-api-specs repository.
---

# Azure DevOps REST API

## Overview

This skill provides guidance for working with Azure DevOps REST APIs using the official OpenAPI specifications from the [vsts-rest-api-specs](https://github.com/MicrosoftDocs/vsts-rest-api-specs) repository. It helps with implementing new API integrations, understanding API capabilities, and referencing the correct request/response formats.

## Key API Areas

Azure DevOps REST APIs are organized into the following main areas:

### Core Services
- **core** - Projects, teams, processes, and organization-level operations
- **git** - Repositories, branches, pull requests, commits
- **build** - Build definitions, builds, and build resources
- **pipelines** - Pipeline definitions and runs
- **release** - Release definitions, deployments, and approvals

### Work Item & Planning
- **wit** (Work Item Tracking) - Work items, queries, and work item types
- **work** - Boards, backlogs, sprints, and team configurations
- **testPlan** - Test plans, suites, and cases
- **testResults** - Test runs and results

### Package & Artifact Management
- **artifacts** - Artifact feeds and packages
- **artifactsPackageTypes** - NuGet, npm, Maven, Python packages

### Security & Governance
- **graph** - Users, groups, and memberships
- **security** - Access control lists and permissions
- **policy** - Branch policies and policy configurations
- **audit** - Audit logs and events

### Extension & Integration
- **extensionManagement** - Extensions and marketplace
- **serviceEndpoint** - Service connections
- **hooks** - Service hooks and subscriptions

## API Specification Structure

The vsts-rest-api-specs repository is organized by API area and version:

```
specification/
  ├── {api-area}/          (e.g., git, build, pipelines)
  │   ├── 7.2/            Latest stable version
  │   │   ├── {area}.json          OpenAPI spec file
  │   │   └── httpExamples/        Example requests/responses
  │   ├── 7.1/
  │   └── ...
```

### Using the Specifications

1. **Identify the API area** - Determine which service area (git, build, wit, etc.) contains the functionality needed
2. **Select the version** - Use the latest version (7.2) unless targeting a specific Azure DevOps Server version
3. **Review the OpenAPI spec** - The main `{area}.json` file contains all endpoints, schemas, and parameters
4. **Check httpExamples** - Real request/response examples for each endpoint

## Implementation Patterns

### Pattern 1: Exploring New API Capabilities

When exploring what APIs are available for a specific feature:

1. Clone the vsts-rest-api-specs repository to `/tmp/vsts-rest-api-specs`
2. Browse the specification directory for the relevant API area
3. Review the OpenAPI spec JSON file for available endpoints
4. Check httpExamples for real-world usage patterns

Example workflow:
```bash
cd /tmp
git clone --depth 1 https://github.com/MicrosoftDocs/vsts-rest-api-specs.git
cd vsts-rest-api-specs/specification/git/7.2
# Review git.json for endpoint definitions
# Check httpExamples/ for request/response samples
```

### Pattern 2: Implementing a New API Feature

When adding new API functionality to the MCP server:

1. **Locate the spec**: Find the relevant OpenAPI specification
2. **Review the schema**: Understand the request parameters and response format
3. **Check examples**: Review httpExamples for real request/response data
4. **Create types**: Define TypeScript interfaces based on the OpenAPI schema
5. **Implement handler**: Create the feature handler following the repository's feature-based architecture
6. **Add tests**: Write unit tests with mocked responses based on httpExamples

### Pattern 3: Understanding Request/Response Formats

When you need to understand the exact format of API requests or responses:

1. Navigate to `specification/{area}/{version}/httpExamples/`
2. Find the relevant endpoint example (e.g., `GET_repositories.json`)
3. Review both the request parameters and response body structure
4. Use this as the basis for creating Zod schemas and TypeScript types

## Reference Resources

### scripts/
Contains helper utilities for working with the API specifications:
- `clone_specs.sh` - Clone or update the vsts-rest-api-specs repository
- `find_endpoint.py` - Search for specific endpoints across all API specs

### references/
Contains curated reference documentation:
- `api_areas.md` - Comprehensive list of all API areas and their purposes
- `common_patterns.md` - Common request/response patterns across APIs
- `authentication.md` - API authentication methods and patterns

### Usage Tips

**Finding the right API:**
- Use the OpenAPI spec's `paths` section to find endpoint URLs
- Check the `tags` property to understand the API category
- Review the `operationId` for the internal Azure DevOps method name

**Understanding schemas:**
- All data models are in the `definitions` section of the OpenAPI spec
- Look for `$ref` properties to follow schema references
- Use httpExamples to see actual data structures

**Version selection:**
- Use version 7.2 for Azure DevOps Services (cloud)
- Check azure-devops-server-{version} folders for on-premises versions
- API versions are additive - newer versions include all older functionality

## Integration with This Repository

When implementing features in this MCP server:

1. **Follow the feature-based architecture**: Create features in `src/features/{api-area}/`
2. **Use Zod for validation**: Define schemas based on OpenAPI definitions
3. **Reference the specs**: Link to the relevant OpenAPI spec in code comments
4. **Include examples**: Use httpExamples data for test fixtures
5. **Match naming**: Use consistent naming with the Azure DevOps API (e.g., `repositoryId`, `pullRequestId`)

Example feature implementation pattern:
```typescript
// src/features/{api-area}/{operation}/
├── feature.ts          // Core implementation using azure-devops-node-api
├── schema.ts           // Zod schemas based on OpenAPI definitions
├── feature.spec.unit.ts // Tests using httpExamples data
└── index.ts            // Exports
```
Files in this package (4)
  • SKILL.md 6 KB
  • references/api_areas.md 3 KB
  • scripts/clone_specs.sh 1 KB
  • scripts/find_endpoint.py 3 KB

Versions

The database has no other skills named azure-devops-rest-api.

Database snapshot: 13.11.2026 · package version 5cadc711ab27 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-design
    Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.
  • 100azure-devops
    Interact with Azure DevOps repositories, pull requests, and APIs using the AZURE_DEVOPS_TOKEN environment variable. Use when working with code hosted on Azure DevOps or managing Azure DevOps resources.
  • 100azure-devops
    Interact with Azure DevOps repositories, pull requests, and APIs using the AZURE_DEVOPS_TOKEN environment variable. Use when working with code hosted on Azure DevOps or managing Azure DevOps resources.
  • 100azure-devops
    Set up Azure Pipelines for CI/CD, configure build and release pipelines, manage Azure DevOps projects, and integrate with Azure services. Use when working with Azure DevOps Services or Server for enterprise DevOps workflows.
  • 100wit-invoke
    Call Azure DevOps REST APIs via az devops invoke command. Use when you need to access Azure DevOps features not available in the CLI, such as work item comments, search, boards, backlogs, capacities, or any wit/work/search API endpoint. Use when the user mentions "invoke", "REST…
  • 100azure-devops
    Azure DevOps via Apideck's Proxy API + managed Vault auth — Apideck handles auth and proxies HTTP calls to Azure DevOps's native API. Use when the user wants to call Azure DevOps (no unified API resource mapping). Routes through Apideck with serviceId "azure-devops".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.