Work Item Tracking API Reference

Work Item Tracking API Reference

Comprehensive reference for Azure DevOps Work Item Tracking REST API operations.

Table of Contents

• Work Item Fields
• Work Item Types
• WIQL Reference
• Link Types
• State Transitions

Work Item Fields

System Fields

Scheduling Fields

Bug-Specific Fields

Custom Field Pattern

Custom fields follow the pattern: Custom.{FieldName}

Work Item Types

Agile Process Template

Scrum Process Template

CMMI Process Template

WIQL Reference

Query Syntax

SELECT [Field1], [Field2], ...
FROM workitems | workitemLinks
WHERE [Conditions]
ORDER BY [Field] [ASC|DESC]
ASOF [DateTime]
MODE [Options]

Operators

Macros

Link Query Modes

Example Queries

-- Active bugs assigned to me, high priority
SELECT [System.Id], [System.Title], [System.State], [Microsoft.VSTS.Common.Severity]
FROM workitems
WHERE [System.TeamProject] = @Project
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [Microsoft.VSTS.Common.Priority] <= 2
ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.CreatedDate] DESC

-- Items changed in last week
SELECT [System.Id], [System.Title], [System.ChangedDate], [System.ChangedBy]
FROM workitems
WHERE [System.TeamProject] = @Project
  AND [System.ChangedDate] >= @Today - 7
ORDER BY [System.ChangedDate] DESC

-- Current sprint work items
SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo]
FROM workitems
WHERE [System.TeamProject] = @Project
  AND [System.IterationPath] = @CurrentIteration
  AND [System.WorkItemType] IN ('User Story', 'Task', 'Bug')
ORDER BY [System.State], [System.AssignedTo]

-- Parent-child hierarchy
SELECT [Source].[System.Id], [Source].[System.Title],
       [Target].[System.Id], [Target].[System.Title]
FROM workitemLinks
WHERE [Source].[System.TeamProject] = @Project
  AND [Source].[System.WorkItemType] = 'User Story'
  AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
  AND [Target].[System.WorkItemType] = 'Task'
MODE (MustContain)

Link Types

Standard Link Types

External Link Types

VSTFS Link URIs

# Branch
vstfs:///Git/Ref/{projectId}/{repositoryId}/GB{branchName}

# Commit
vstfs:///Git/Commit/{projectId}/{repositoryId}/{commitId}

# Pull Request
vstfs:///Git/PullRequestId/{projectId}/{pullRequestId}

# Build
vstfs:///Build/Build/{projectId}/{buildId}

# Release
vstfs:///ReleaseManagement/ReleaseEnvironment/{projectId}/{releaseId}:{environmentId}

State Transitions

Agile Bug States

New → Active → Resolved → Closed
         ↓         ↓
      Removed   Removed

Agile User Story States

New → Active → Resolved → Closed
         ↓
      Removed

Agile Task States

New → Active → Closed
         ↓
      Removed

State Reasons

MCP Tool Usage Examples

Get Work Item

# Using mcp__ado__wit_get_work_item
params = {
    "project": "MyProject",
    "id": 12345,
    "expand": "relations",  # Include links
    "fields": ["System.Id", "System.Title", "System.State"]
}

Create Work Item

# Using mcp__ado__wit_create_work_item
params = {
    "project": "MyProject",
    "workItemType": "Bug",
    "fields": [
        {"name": "System.Title", "value": "Login button not working"},
        {"name": "System.Description", "value": "Users cannot click the login button"},
        {"name": "Microsoft.VSTS.Common.Severity", "value": "2 - High"},
        {"name": "System.AssignedTo", "value": "user@company.com"}
    ]
}

Update Work Item

# Using mcp__ado__wit_update_work_item
params = {
    "id": 12345,
    "updates": [
        {"op": "add", "path": "/fields/System.State", "value": "Active"},
        {"op": "add", "path": "/fields/System.AssignedTo", "value": "dev@company.com"}
    ]
}

Link Work Items

# Using mcp__ado__wit_work_items_link
params = {
    "project": "MyProject",
    "updates": [
        {"id": 12345, "linkToId": 12346, "type": "child"},
        {"id": 12345, "linkToId": 12347, "type": "related"}
    ]
}

Add Artifact Link

# Using mcp__ado__wit_add_artifact_link
params = {
    "workItemId": 12345,
    "project": "MyProject",
    "linkType": "Branch",
    "projectId": "project-guid",
    "repositoryId": "repo-guid",
    "branchName": "feature/new-feature"
}