julianobarbosa/azure-devops

Azure DevOps REST API Skill

Comprehensive guide for Azure DevOps REST API v7.2 operations including work items, pipelines, repositories, test plans, wikis, and search functionality.

Quick Reference

| Area | Base URL | MCP Tool Prefix | |------|----------|-----------------| | Core | dev.azure.com/{org}/_apis/ | mcp__ado__core_* | | Work Items | dev.azure.com/{org}/{project}/_apis/wit/ | mcp__ado__wit_* | | Pipelines | dev.azure.com/{org}/{project}/_apis/pipelines/ | mcp__ado__pipelines_* | | Git/Repos | dev.azure.com/{org}/{project}/_apis/git/ | mcp__ado__repo_* | | Test Plans | dev.azure.com/{org}/{project}/_apis/testplan/ | mcp__ado__testplan_* | | Wiki | dev.azure.com/{org}/{project}/_apis/wiki/ | mcp__ado__wiki_* | | Search | almsearch.dev.azure.com/{org}/_apis/search/ | mcp__ado__search_* |

Authentication Methods

Personal Access Token (PAT)

# Base64 encode empty username with PAT
AUTH=$(echo -n ":${PAT}" | base64)
curl -H "Authorization: Basic ${AUTH}" https://dev.azure.com/{org}/_apis/projects

OAuth 2.0 Scopes

| Scope | Access Level | |-------|--------------| | vso.work | Read work items | | vso.work_write | Create/update work items | | vso.code | Read source code | | vso.code_write | Create branches, PRs | | vso.build_execute | Run pipelines | | vso.test | Read test plans | | vso.wiki | Read wikis |

API Versioning

Format: {major}.{minor}[-{stage}[.{resource-version}]]

• Current: 7.2-preview.3
• Example: api-version=7.2-preview.3

---

1. Work Item Operations

Available MCP Tools

mcp__ado__wit_get_work_item          - Get single work item
mcp__ado__wit_get_work_items_batch_by_ids - Get multiple work items
mcp__ado__wit_my_work_items          - Get items assigned to me
mcp__ado__wit_create_work_item       - Create new work item
mcp__ado__wit_update_work_item       - Update work item fields
mcp__ado__wit_update_work_items_batch - Bulk update work items
mcp__ado__wit_add_work_item_comment  - Add comment to work item
mcp__ado__wit_list_work_item_comments - List work item comments
mcp__ado__wit_add_child_work_items   - Create child work items
mcp__ado__wit_work_items_link        - Link work items together
mcp__ado__wit_work_item_unlink       - Remove work item links
mcp__ado__wit_link_work_item_to_pull_request - Link to PR
mcp__ado__wit_add_artifact_link      - Add artifact links (branch, commit, build)
mcp__ado__wit_get_work_item_type     - Get work item type definition
mcp__ado__wit_list_backlogs          - List team backlogs
mcp__ado__wit_list_backlog_work_items - Get backlog items
mcp__ado__wit_get_work_items_for_iteration - Get sprint items
mcp__ado__wit_get_query              - Get saved query
mcp__ado__wit_get_query_results_by_id - Execute saved query

WIQL Query Syntax

Basic Structure

SELECT [Fields]
FROM workitems
WHERE [Conditions]
ORDER BY [Fields]
ASOF [DateTime]

Common Macros

| Macro | Description | |-------|-------------| | @Me | Current user | | @project | Current project | | @Today | Today's date | | @Today - N | N days ago | | @CurrentIteration | Current sprint | | @StartOfMonth | First of month |

Example Queries

-- Active tasks assigned to me
SELECT [System.Id], [System.Title], [System.State]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Task'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
ORDER BY [System.Priority] ASC

-- Bugs created in last 30 days
SELECT [System.Id], [System.Title], [System.CreatedDate]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Bug'
  AND [System.CreatedDate] >= @Today - 30

-- Parent-child hierarchy
SELECT [Source].[System.Id], [Target].[System.Id]
FROM workitemLinks
WHERE [Source].[System.TeamProject] = @project
  AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
MODE (Recursive)

JSON Patch Operations

[
  {"op": "add", "path": "/fields/System.Title", "value": "New Title"},
  {"op": "replace", "path": "/fields/System.State", "value": "Active"},
  {"op": "add", "path": "/relations/-", "value": {
    "rel": "System.LinkTypes.Related",
    "url": "https://dev.azure.com/{org}/_apis/wit/workItems/{id}"
  }}
]

Link Types Reference

| Type | Rel Name | |------|----------| | Parent | System.LinkTypes.Hierarchy-Reverse | | Child | System.LinkTypes.Hierarchy-Forward | | Related | System.LinkTypes.Related | | Predecessor | System.LinkTypes.Dependency-Reverse | | Successor | System.LinkTypes.Dependency-Forward |

---

2. Pipeline Operations

Available MCP Tools

mcp__ado__pipelines_get_build_definitions - List pipeline definitions
mcp__ado__pipelines_get_build_definition_revisions - Get definition history
mcp__ado__pipelines_get_builds         - List builds
mcp__ado__pipelines_get_build_status   - Get build status
mcp__ado__pipelines_get_build_log      - Get build logs
mcp__ado__pipelines_get_build_log_by_id - Get specific log
mcp__ado__pipelines_get_build_changes  - Get commits in build
mcp__ado__pipelines_run_pipeline       - Trigger pipeline run
mcp__ado__pipelines_get_run            - Get pipeline run details
mcp__ado__pipelines_list_runs          - List pipeline runs
mcp__ado__pipelines_update_build_stage - Retry/cancel stage

Pipeline Trigger Example

{
  "resources": {
    "repositories": {
      "self": {"refName": "refs/heads/feature-branch"}
    }
  },
  "templateParameters": {
    "environment": "staging"
  },
  "variables": {
    "customVar": {"value": "custom-value", "isSecret": false}
  }
}

Build Status Values

| Status | Description | |--------|-------------| | none | Not started | | inProgress | Running | | completed | Finished | | cancelling | Being cancelled | | postponed | Delayed | | notStarted | Queued |

Build Result Values

| Result | Description | |--------|-------------| | succeeded | All tasks passed | | partiallySucceeded | Some tasks failed | | failed | Build failed | | canceled | User cancelled |

---

3. Repository Operations

Available MCP Tools

mcp__ado__repo_list_repos_by_project   - List repositories
mcp__ado__repo_get_repo_by_name_or_id  - Get repository details
mcp__ado__repo_list_branches_by_repo   - List branches
mcp__ado__repo_list_my_branches_by_repo - List my branches
mcp__ado__repo_get_branch_by_name      - Get branch details
mcp__ado__repo_create_branch           - Create new branch
mcp__ado__repo_search_commits          - Search commit history
mcp__ado__repo_list_pull_requests_by_repo_or_project - List PRs
mcp__ado__repo_get_pull_request_by_id  - Get PR details
mcp__ado__repo_create_pull_request     - Create PR
mcp__ado__repo_update_pull_request     - Update PR (autocomplete, status)
mcp__ado__repo_update_pull_request_reviewers - Add/remove reviewers
mcp__ado__repo_list_pull_request_threads - List PR comments
mcp__ado__repo_list_pull_request_thread_comments - Get thread comments
mcp__ado__repo_create_pull_request_thread - Create comment thread
mcp__ado__repo_reply_to_comment        - Reply to comment
mcp__ado__repo_resolve_comment         - Resolve thread
mcp__ado__repo_list_pull_requests_by_commits - Find PR by commit

PR Status Values

| Status | Description | |--------|-------------| | active | Open for review | | abandoned | Closed without merge | | completed | Merged |

Merge Strategies

| Strategy | Description | |----------|-------------| | noFastForward | Merge commit (default) | | squash | Squash commits | | rebase | Rebase and fast-forward | | rebaseMerge | Rebase with merge commit |

---

4. Test Plan Operations

Available MCP Tools

mcp__ado__testplan_list_test_plans     - List test plans
mcp__ado__testplan_create_test_plan    - Create test plan
mcp__ado__testplan_create_test_suite   - Create test suite
mcp__ado__testplan_list_test_cases     - List test cases in suite
mcp__ado__testplan_create_test_case    - Create test case
mcp__ado__testplan_update_test_case_steps - Update test steps
mcp__ado__testplan_add_test_cases_to_suite - Add cases to suite
mcp__ado__testplan_show_test_results_from_build_id - Get test results

Test Case Steps Format

1. Navigate to login page|Login page displayed
2. Enter username|Username field populated
3. Enter password|Password field populated
4. Click login button|User is logged in successfully

Test Suite Types

| Type | Description | |------|-------------| | staticTestSuite | Manual hierarchy | | dynamicTestSuite | Query-based | | requirementTestSuite | Linked to requirement |

Test Outcome Values

| Outcome | Description | |---------|-------------| | Passed | Test passed | | Failed | Test failed | | Blocked | Cannot execute | | NotExecuted | Not run | | Inconclusive | No clear result |

---

5. Wiki Operations

Available MCP Tools

mcp__ado__wiki_list_wikis              - List wikis
mcp__ado__wiki_get_wiki                - Get wiki details
mcp__ado__wiki_list_pages              - List wiki pages
mcp__ado__wiki_get_page                - Get page metadata
mcp__ado__wiki_get_page_content        - Get page content
mcp__ado__wiki_create_or_update_page   - Create/update page

Wiki Types

| Type | Description | |------|-------------| | projectWiki | Project-scoped wiki | | codeWiki | Git-backed wiki |

Page Path Format

• Root: /
• Subpage: /Parent/Child
• Spaces: /My%20Page

---

6. Search Operations

Available MCP Tools

mcp__ado__search_code                  - Search source code
mcp__ado__search_workitem              - Search work items
mcp__ado__search_wiki                  - Search wiki pages

Code Search Filters

{
  "Project": ["project-name"],
  "Repository": ["repo-name"],
  "Path": ["/src"],
  "Branch": ["main"],
  "CodeElement": ["class", "def", "function"]
}

Work Item Search Filters

{
  "System.TeamProject": ["project-name"],
  "System.WorkItemType": ["Bug", "Task"],
  "System.State": ["Active", "New"],
  "System.AssignedTo": ["[email protected]"]
}

---

7. Core Operations

Available MCP Tools

mcp__ado__core_list_projects           - List projects
mcp__ado__core_list_project_teams      - List teams
mcp__ado__core_get_identity_ids        - Get user identity
mcp__ado__work_list_team_iterations    - List iterations
mcp__ado__work_list_iterations         - List all iterations
mcp__ado__work_create_iterations       - Create iterations
mcp__ado__work_assign_iterations       - Assign to team
mcp__ado__work_get_team_capacity       - Get team capacity
mcp__ado__work_update_team_capacity    - Update capacity
mcp__ado__work_get_iteration_capacities - Get iteration capacity

---

8. Advanced Security Operations

Available MCP Tools

mcp__ado__advsec_get_alerts            - Get security alerts
mcp__ado__advsec_get_alert_details     - Get alert details

Alert Types

| Type | Description | |------|-------------| | Dependency | Vulnerable dependencies | | Secret | Exposed secrets | | Code | Code vulnerabilities |

---

Rate Limiting

TSTU (Throughput Unit) Limits

• Anonymous: 200 TSTUs/minute
• Authenticated: 1200 TSTUs/minute

Response Headers

X-RateLimit-Resource: core
X-RateLimit-Delay: 500
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1609459200
Retry-After: 30

Handling Rate Limits

import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 30))
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Rate limit exceeded after retries")

---

Error Handling

HTTP Status Codes

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 204 | No Content (DELETE) | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 409 | Conflict (version) | | 429 | Rate Limited | | 500 | Server Error |

Error Response Format

{
  "$id": "1",
  "innerException": null,
  "message": "Error description",
  "typeName": "Microsoft.VisualStudio.Services.WebApi.VssServiceException",
  "typeKey": "VssServiceException",
  "errorCode": 0
}

---

Common Field Reference

System Fields

| Field | Reference Name | |-------|----------------| | ID | System.Id | | Title | System.Title | | State | System.State | | Assigned To | System.AssignedTo | | Area Path | System.AreaPath | | Iteration Path | System.IterationPath | | Work Item Type | System.WorkItemType | | Created Date | System.CreatedDate | | Changed Date | System.ChangedDate | | Tags | System.Tags | | Description | System.Description |

Scheduling Fields

| Field | Reference Name | |-------|----------------| | Story Points | Microsoft.VSTS.Scheduling.Effort | | Remaining Work | Microsoft.VSTS.Scheduling.RemainingWork | | Original Estimate | Microsoft.VSTS.Scheduling.OriginalEstimate | | Completed Work | Microsoft.VSTS.Scheduling.CompletedWork |

---

Multi-Repo Work Item Segregation

When a single Azure DevOps project contains multiple repositories, use Area Paths for primary segregation and hierarchical Iteration Paths for repo-scoped sprint/epic tracking.

Target Structure

Area Paths:                          Iteration Paths:
project\                             project\Iteration\
├── repo-a           (per-repo)      ├── Sprint 1        (shared across repos)
├── repo-b           (per-repo)      ├── Sprint 2        (shared across repos)
└── repo-c           (per-repo)      ├── repo-a\         (repo-scoped container)
                                     │   ├── epic-1-...  (auto-created by sync)
                                     │   └── epic-2-...
                                     └── repo-b\         (repo-scoped container)

Path Format Differences (Critical)

Azure DevOps uses two different path formats for iterations:

| Operation | Format | Example | |-----------|--------|---------| | az boards iteration project create --path | \Project\Iteration\Parent (literal "Iteration" segment required) | \devops-team\Iteration\azure-quota-automation | | az boards work-item update --iteration | Project\Parent\Child (no "Iteration" segment, no leading \) | devops-team\azure-quota-automation\epic-1-slug |

Setup Commands for a New Repo

# 1. Create area path (if not exists)
az boards area project create --name "<repo-name>" --path "\<project>"

# 2. Create iteration container
az boards iteration project create --name "<repo-name>" --path "\<project>\Iteration"

# 3. Configure BMAD sync (devops-sync-config.yaml)
# areaPath: "<project>\\<repo-name>"
# iterationRootPath: "<repo-name>"

Moving Iterations (No Native Move)

Azure DevOps CLI has no move command for iterations. To restructure:

1. Verify no work items assigned: az boards query --wiql "... WHERE [System.IterationPath] = '...'"
2. Delete: az boards iteration project delete --path "\project\Iteration\old-path" --yes
3. Recreate under new parent: az boards iteration project create --name "name" --path "\project\Iteration\new-parent"
4. Update state files with new iteration IDs

Common Error: TF401347

TF401347: The iteration path does not exist — caused by using the wrong path format. Check:

• --iteration on work items uses Project\Parent\Child (no "Iteration" segment)
• --path on iteration create uses \Project\Iteration\Parent (with "Iteration" segment)

---

Best Practices

1. Use Batch Operations

• Use mcp__ado__wit_get_work_items_batch_by_ids instead of multiple single calls
• Max 200 items per batch request

2. Minimize Field Selection

• Only request fields you need: fields=System.Id,System.Title,System.State
• Reduces response size and API load

3. Handle Pagination

• Use $top and $skip for large result sets
• Follow continuation tokens when provided

4. Version Control

• Use test operation in JSON Patch for optimistic concurrency
• Always check rev field before updates

5. Error Recovery

• Implement exponential backoff for rate limits
• Log correlation IDs from response headers

---

References

• Azure DevOps REST API v7.2
• WIQL Syntax Reference
• Authentication Guide
• Rate Limits

---

Gotchas

• REST API rate limits are per-org per-PAT — concurrent batch jobs share the budget. HTTP 429 returns retry-after but most clients ignore it.
• WIQL [System.AssignedTo] returns identity ref objects, not names — equality comparison needs EVER operator or a UPN-shaped string match.
• Work-item rev-based optimistic concurrency: concurrent updates with stale rev fail silently (the update is dropped, not errored).
• Pipeline YAML stage-less mode: a YAML with only jobs: runs as one implicit stage, but APIs filtering by stage name return empty.
• PAT scopes are union, not intersection — a "Read & Write" scope on Code doesn't grant Build access; missing scopes get 401 with vague "TF400813" error.
• Date macros (@Today, @StartOfWeek) work in some queries and not others — saved query in UI may not match WIQL via API.