openapi: 3.1.0
info:
title: Azure DevOps Work Items API
description: >
REST API for managing work items, work item types, fields, queries, attachments,
and comments in Azure Boards. Enables programmatic access to agile planning
and tracking resources across sprints, backlogs, and boards.
version: '7.1'
contact:
name: Microsoft Azure DevOps
url: https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://dev.azure.com/{organization}/{project}/_apis
description: Azure DevOps Work Item Tracking API
variables:
organization:
description: Azure DevOps organization name or ID
default: myorganization
project:
description: Azure DevOps project name or ID
default: myproject
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Attachments
description: Operations for work item attachments
- name: Comments
description: Operations for work item comments
- name: Work Item Tracking
description: Operations for querying and tracking work items using WIQL
- name: Work Item Types
description: Operations for work item type definitions and fields
- name: Work Items
description: Operations for managing work items (Bugs, Tasks, User Stories, etc.)
paths:
/wit/workitems:
get:
operationId: workItems_list
summary: Azure DevOps List work items by IDs
description: >
Returns a list of work items by their IDs. You must provide a comma-separated
list of work item IDs. Optionally filter by specific fields, as-of date, or
expand relations and links.
tags:
- Work Items
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: ids
in: query
required: true
description: Comma-separated list of work item IDs (up to 200)
schema:
type: string
example: '1,2,3,4,5'
- name: fields
in: query
required: false
description: Comma-separated list of fields to return (e.g., System.Title,System.State)
schema:
type: string
- name: asOf
in: query
required: false
description: Work items as of a specific date and time (ISO 8601 format)
schema:
type: string
format: date-time
- name: $expand
in: query
required: false
description: Expand relations, links, or fields in the response
schema:
type: string
enum: [none, relations, links, fields, all]
responses:
'200':
description: List of work items returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: Number of work items returned
value:
type: array
items:
$ref: '#/components/schemas/WorkItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/wit/workitems/{type}:
post:
operationId: workItems_create
summary: Azure DevOps Create a work item
description: >
Creates a new work item of the specified type. The request body must be a
JSON Patch document describing the fields to set on the new work item.
Common types include Bug, Task, User Story, Feature, and Epic.
tags:
- Work Items
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: type
in: path
required: true
description: Work item type (e.g., Bug, Task, User Story)
schema:
type: string
example: 'Bug'
- name: validateOnly
in: query
required: false
description: Validate the fields without saving the work item
schema:
type: boolean
- name: bypassRules
in: query
required: false
description: Do not enforce the work item type rules on this update
schema:
type: boolean
- name: suppressNotifications
in: query
required: false
description: Do not fire any notifications for this change
schema:
type: boolean
requestBody:
required: true
description: JSON Patch document with field operations for the new work item
content:
application/json-patch+json:
schema:
type: array
items:
$ref: '#/components/schemas/JsonPatchOperation'
example:
- op: add
path: /fields/System.Title
value: 'Fix login button alignment'
- op: add
path: /fields/System.Description
value: 'The login button is misaligned on mobile screens'
responses:
'200':
description: Work item created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/wit/workitems/{id}:
get:
operationId: workItems_get
summary: Azure DevOps Get a work item by ID
description: >
Returns a single work item by its numeric ID. Optionally filter the fields
returned, specify a point-in-time with asOf, or expand relations and links.
tags:
- Work Items
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: id
in: path
required: true
description: Numeric ID of the work item
schema:
type: integer
example: 42
- name: fields
in: query
required: false
description: Comma-separated list of fields to return
schema:
type: string
- name: asOf
in: query
required: false
description: Work item as of a specific date and time
schema:
type: string
format: date-time
- name: $expand
in: query
required: false
description: Expand relations, links, or fields
schema:
type: string
enum: [none, relations, links, fields, all]
responses:
'200':
description: Work item returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItem'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: workItems_update
summary: Azure DevOps Update a work item
description: >
Updates an existing work item by applying a JSON Patch document. Supports
updating fields, adding relations, and modifying links. Use the add, replace,
remove, and test operations to make changes.
tags:
- Work Items
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: id
in: path
required: true
description: Numeric ID of the work item to update
schema:
type: integer
- name: validateOnly
in: query
required: false
description: Validate fields without saving the work item
schema:
type: boolean
- name: bypassRules
in: query
required: false
description: Do not enforce work item type rules on this update
schema:
type: boolean
- name: suppressNotifications
in: query
required: false
description: Do not fire any notifications for this change
schema:
type: boolean
requestBody:
required: true
description: JSON Patch document with field update operations
content:
application/json-patch+json:
schema:
type: array
items:
$ref: '#/components/schemas/JsonPatchOperation'
example:
- op: replace
path: /fields/System.State
value: 'Active'
- op: replace
path: /fields/System.AssignedTo
value: '[email protected]'
responses:
'200':
description: Work item updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: workItems_delete
summary: Azure DevOps Delete a work item
description: >
Moves a work item to the recycle bin. The work item can be recovered from
the recycle bin or permanently deleted. Deletion requires appropriate permissions.
tags:
- Work Items
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: id
in: path
required: true
description: Numeric ID of the work item to delete
schema:
type: integer
- name: destroy
in: query
required: false
description: Permanently delete the work item instead of moving to recycle bin
schema:
type: boolean
responses:
'204':
description: Work item deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/wit/wiql:
post:
operationId: workItems_queryByWiql
summary: Azure DevOps Execute a WIQL query
description: >
Executes a Work Item Query Language (WIQL) query and returns a list of
work item references that match the query criteria. WIQL is a SQL-like
language specific to Azure DevOps work item querying.
tags:
- Work Item Tracking
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: $top
in: query
required: false
description: Maximum number of results to return
schema:
type: integer
maximum: 20000
- name: timePrecision
in: query
required: false
description: Whether or not to use time precision
schema:
type: boolean
requestBody:
required: true
description: WIQL query object
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: The WIQL query string
example:
query: "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] = 'Bug' ORDER BY [System.CreatedDate] DESC"
responses:
'200':
description: Query results returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItemQueryResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/wit/workitemtypes:
get:
operationId: workItemTypes_list
summary: Azure DevOps List work item types
description: >
Returns a list of all work item types defined in the project. Work item types
include Bug, Task, User Story, Feature, Epic, and any custom types defined
in the process template.
tags:
- Work Item Types
parameters:
- $ref: '#/components/parameters/ApiVersion'
responses:
'200':
description: List of work item types returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/WorkItemType'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/wit/workitemtypes/{type}:
get:
operationId: workItemTypes_get
summary: Azure DevOps Get a work item type
description: >
Returns detailed information about a specific work item type, including its
fields, transitions, states, and rules. The type name is case-sensitive and
must match exactly (e.g., 'Bug', 'Task', 'User Story').
tags:
- Work Item Types
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: type
in: path
required: true
description: Name of the work item type
schema:
type: string
example: 'Bug'
responses:
'200':
description: Work item type returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItemType'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/wit/fields:
get:
operationId: fields_list
summary: Azure DevOps List work item fields
description: >
Returns a list of all work item fields available in the project. Includes
both system fields (System.*) and custom fields, with their types,
reference names, and whether they are read-only.
tags:
- Work Item Types
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: $expand
in: query
required: false
description: Include additional details such as allowed values
schema:
type: string
enum: [none, extensionFields, includeDeleted]
responses:
'200':
description: List of fields returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/WorkItemField'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/wit/workitems/{id}/comments:
get:
operationId: workItems_listComments
summary: Azure DevOps Get work item comments
description: >
Returns all comments for a specific work item, ordered by creation date.
Comments are user-authored notes attached to a work item and are separate
from the work item's history.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: id
in: path
required: true
description: Numeric ID of the work item
schema:
type: integer
- name: $top
in: query
required: false
description: Maximum number of comments to return
schema:
type: integer
- name: continuationToken
in: query
required: false
description: Continuation token for paging
schema:
type: string
responses:
'200':
description: Comments returned successfully
content:
application/json:
schema:
type: object
properties:
totalCount:
type: integer
count:
type: integer
comments:
type: array
items:
$ref: '#/components/schemas/WorkItemComment'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: workItems_addComment
summary: Azure DevOps Add a comment to a work item
description: >
Adds a new comment to a work item. The comment body supports HTML markup.
The new comment is appended to the existing list of comments.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: id
in: path
required: true
description: Numeric ID of the work item
schema:
type: integer
requestBody:
required: true
description: Comment to add to the work item
content:
application/json:
schema:
type: object
required:
- text
properties:
text:
type: string
description: Comment text (HTML supported)
example:
text: '<p>This bug has been reproduced in the staging environment.</p>'
responses:
'200':
description: Comment added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItemComment'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/wit/attachments/{id}:
get:
operationId: attachments_get
summary: Azure DevOps Get attachment info
description: >
Returns metadata about an attachment by its GUID identifier. The response
includes the attachment URL, file name, size, and creation date. Use the
URL in the response to download the actual attachment content.
tags:
- Attachments
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: id
in: path
required: true
description: GUID of the attachment
schema:
type: string
format: uuid
responses:
'200':
description: Attachment info returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentReference'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/wit/attachments:
post:
operationId: attachments_upload
summary: Azure DevOps Upload an attachment
description: >
Uploads a new attachment and returns the attachment reference including
the ID and URL. After uploading, attach the file to a work item using
the work item update operation with a relation of type AttachedFile.
tags:
- Attachments
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: fileName
in: query
required: true
description: Name of the file being uploaded
schema:
type: string
- name: uploadType
in: query
required: false
description: Upload type (simple for files up to 130 MB)
schema:
type: string
enum: [simple, chunked]
requestBody:
required: true
description: File content as binary stream
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: Attachment uploaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentReference'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Azure AD OAuth 2.0 bearer token
basicAuth:
type: http
scheme: basic
description: Basic authentication using a Personal Access Token (PAT). Use any string as the username and the PAT as the password, then base64-encode the result.
parameters:
ApiVersion:
name: api-version
in: query
required: true
description: Azure DevOps REST API version. Use 7.1 for the latest stable version.
schema:
type: string
default: '7.1'
enum: ['7.1', '7.0', '6.0']
responses:
BadRequest:
description: Bad request - invalid parameters or request body
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Unauthorized:
description: Unauthorized - missing or invalid authentication credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Forbidden:
description: Forbidden - insufficient permissions to perform this operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
NotFound:
description: Not found - the requested resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
schemas:
WorkItem:
type: object
description: An Azure DevOps work item (Bug, Task, User Story, etc.)
properties:
id:
type: integer
description: Unique numeric identifier of the work item
example: 42
rev:
type: integer
description: Revision number of the work item (increments on each update)
example: 3
fields:
type: object
description: >
Dynamic map of field reference names to values. Common fields include
System.Title, System.State, System.AssignedTo, System.Description,
System.WorkItemType, System.AreaPath, System.IterationPath, etc.
additionalProperties: true
example:
System.Title: 'Fix login button alignment'
System.State: 'Active'
System.AssignedTo: 'User Name <[email protected]>'
System.WorkItemType: 'Bug'
System.TeamProject: 'MyProject'
System.AreaPath: 'MyProject\\Frontend'
System.IterationPath: 'MyProject\\Sprint 5'
relations:
type: array
description: Links and relations to other work items or external resources
items:
$ref: '#/components/schemas/WorkItemRelation'
_links:
type: object
description: HAL links for navigating related resources
additionalProperties:
type: object
properties:
href:
type: string
format: uri
url:
type: string
format: uri
description: URL to access this work item via the REST API
example: 'https://dev.azure.com/myorg/myproject/_apis/wit/workItems/42'
WorkItemRelation:
type: object
description: A relation between a work item and another resource
properties:
rel:
type: string
description: Relation type (e.g., System.LinkTypes.Hierarchy-Reverse, AttachedFile)
example: 'System.LinkTypes.Hierarchy-Reverse'
url:
type: string
format: uri
description: URL of the related resource
attributes:
type: object
description: Additional attributes for the relation (e.g., comment, isLocked)
additionalProperties: true
WorkItemQueryResult:
type: object
description: Results from a WIQL query execution
properties:
queryType:
type: string
description: Type of query (flat, oneHop, tree)
enum: [flat, oneHop, tree]
queryResultType:
type: string
description: Result type (workItem, workItemLink)
enum: [workItem, workItemLink]
asOf:
type: string
format: date-time
description: Date and time when the query was executed
columns:
type: array
description: Columns returned by the query
items:
type: object
properties:
referenceName:
type: string
name:
type: string
url:
type: string
format: uri
workItems:
type: array
description: List of work item references matching the query
items:
type: object
properties:
id:
type: integer
url:
type: string
format: uri
WorkItemType:
type: object
description: Definition of a work item type
properties:
name:
type: string
description: Display name of the work item type
example: 'Bug'
referenceName:
type: string
description: Reference name used in WIQL queries
example: 'Microsoft.VSTS.WorkItemTypes.Bug'
description:
type: string
description: Description of the work item type and its intended use
color:
type: string
description: Hex color code for the work item type icon
example: 'CC293D'
icon:
type: object
description: Icon information for the work item type
properties:
id:
type: string
url:
type: string
format: uri
isDisabled:
type: boolean
description: Whether the work item type is disabled
xmlForm:
type: string
description: XML definition of the work item type form
fields:
type: array
description: Fields defined for this work item type
items:
$ref: '#/components/schemas/WorkItemTypeFieldInstance'
fieldInstances:
type: array
items:
$ref: '#/components/schemas/WorkItemTypeFieldInstance'
transitions:
type: object
description: Map of allowed state transitions
additionalProperties:
type: array
items:
type: object
properties:
to:
type: string
actions:
type: array
items:
type: string
states:
type: array
description: Valid states for this work item type
items:
type: object
properties:
name:
type: string
color:
type: string
category:
type: string
url:
type: string
format: uri
WorkItemTypeFieldInstance:
type: object
description: A field instance within a work item type
properties:
fieldName:
type: string
description: Display name of the field
field:
type: object
properties:
name:
type: string
referenceName:
type: string
url:
type: string
format: uri
referenceName:
type: string
description: Reference name (e.g., System.Title)
defaultValue:
description: Default value for the field
allowedValues:
type: array
items:
type: string
description: Allowed values for fields with a restricted set of values
helpText:
type: string
alwaysRequired:
type: boolean
readOnly:
type: boolean
WorkItemField:
type: object
description: Definition of a work item field
properties:
name:
type: string
description: Display name of the field
example: 'Assigned To'
referenceName:
type: string
description: Reference name used in WIQL and API (e.g., System.AssignedTo)
example: 'System.AssignedTo'
description:
type: string
description: Description of what the field stores
type:
type: string
description: Data type of the field
enum: [string, integer, dateTime, plainText, html, treePath, history, double, guid, boolean, identity, picklistString, picklistInteger, picklistDouble]
usage:
type: string
description: Whether the field is used for work items or work item links
enum: [none, workItem, workItemLink, tree, workItemTypeExtension]
readOnly:
type: boolean
description: Whether the field is read-only
canSortBy:
type: boolean
description: Whether work items can be sorted by this field
isQueryable:
type: boolean
description: Whether this field can be used in WIQL queries
isIdentity:
type: boolean
description: Whether this field stores an identity (user) value
isPicklist:
type: boolean
description: Whether this field has a picklist of allowed values
isPicklistSuggested:
type: boolean
description: Whether the picklist values are suggested (non-exclusive)
url:
type: string
format: uri
WorkItemComment:
type: object
description: A comment on a work item
properties:
id:
type: integer
description: Unique ID of the comment
text:
type: string
description: Comment text in HTML format
workItemId:
type: integer
description: ID of the work item this comment belongs to
version:
type: integer
description: Version number of the comment
createdDate:
type: string
format: date-time
description: Date and time the comment was created
createdBy:
$ref: '#/components/schemas/IdentityRef'
modifiedDate:
type: string
format: date-time
description: Date and time the comment was last modified
modifiedBy:
$ref: '#/components/schemas/IdentityRef'
url:
type: string
format: uri
AttachmentReference:
type: object
description: Reference to an uploaded attachment
properties:
id:
type: string
format: uuid
description: GUID identifier of the attachment
url:
type: string
format: uri
description: URL to download or reference the attachment
IdentityRef:
type: object
description: Reference to an Azure DevOps user identity
properties:
id:
type: string
format: uuid
description: Unique iden
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure-devops/refs/heads/main/openapi/azure-devops-work-items-api-openapi.yml