Azure DevOps WorkItems API

openapi: 3.1.0
info:
  title: Azure DevOps Pipelines Fields WorkItems API
  description: The Azure DevOps Pipelines API provides REST endpoints for managing CI/CD build and release pipelines. APIs support pipeline creation, triggering builds, retrieving build results, managing release definitions, and automating deployment workflows across Azure DevOps organizations.
  version: '7.2'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/
servers:
- url: https://dev.azure.com/{organization}
  description: Azure DevOps Services
  variables:
    organization:
      description: Azure DevOps organization name
      default: my-org
security:
- personalAccessToken: []
- oauth2: []
tags:
- name: WorkItems
  description: Work item CRUD and management
paths:
  /{project}/_apis/wit/workitems/{id}:
    get:
      operationId: getWorkItem
      summary: Get Work Item by Id
      description: Returns a single work item by its numeric ID. Supports field selection and expansion of related entities.
      tags:
      - WorkItems
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: project
        in: path
        required: true
        description: Project name or ID
        schema:
          type: string
        example: example_value
      - name: id
        in: path
        required: true
        description: Work item ID
        schema:
          type: integer
        example: abc123
      - name: $expand
        in: query
        description: Expand related entities (all, fields, relations, links, none)
        schema:
          type: string
          enum:
          - all
          - fields
          - relations
          - links
          - none
        example: all
      - name: $select
        in: query
        description: Comma-separated list of fields to return
        schema:
          type: string
        example: example_value
      - name: api-version
        in: query
        required: true
        schema:
          type: string
          default: 7.2-preview.3
        example: example_value
      responses:
        '200':
          description: Work item details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
              examples:
                Getworkitem200Example:
                  summary: Default getWorkItem 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    rev: 10
                    fields:
                      System.Id: '500123'
                      System.Title: example_value
                      System.WorkItemType: example_value
                      System.State: example_value
                      System.Reason: example_value
                      System.AssignedTo:
                        displayName: example_value
                        id: abc123
                        uniqueName: example_value
                      System.CreatedDate: '2026-01-15T10:30:00Z'
                      System.CreatedBy:
                        displayName: example_value
                      System.ChangedDate: '2026-01-15T10:30:00Z'
                      System.TeamProject: example_value
                      System.AreaPath: example_value
                      System.IterationPath: example_value
                      System.Description: example_value
                      System.Tags: example_value
                      Microsoft.VSTS.Common.Priority: 10
                      Microsoft.VSTS.Common.Severity: example_value
                    relations:
                    - rel: example_value
                      url: https://www.example.com
                      attributes: {}
                    url: https://www.example.com
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateWorkItem
      summary: Update Work Item
      description: Updates a work item using JSON Patch operations. Supports updating fields, adding/removing links, and attaching files.
      tags:
      - WorkItems
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: project
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: abc123
      - name: api-version
        in: query
        required: true
        schema:
          type: string
          default: 7.2-preview.3
        example: example_value
      - name: suppressNotifications
        in: query
        schema:
          type: boolean
        example: true
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/JsonPatchOperation'
            examples:
              UpdateworkitemRequestExample:
                summary: Default updateWorkItem request
                x-microcks-default: true
                value:
                - op: add
                  path: example_value
                  value: example_value
                  from: example_value
      responses:
        '200':
          description: Updated work item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
              examples:
                Updateworkitem200Example:
                  summary: Default updateWorkItem 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    rev: 10
                    fields:
                      System.Id: '500123'
                      System.Title: example_value
                      System.WorkItemType: example_value
                      System.State: example_value
                      System.Reason: example_value
                      System.AssignedTo:
                        displayName: example_value
                        id: abc123
                        uniqueName: example_value
                      System.CreatedDate: '2026-01-15T10:30:00Z'
                      System.CreatedBy:
                        displayName: example_value
                      System.ChangedDate: '2026-01-15T10:30:00Z'
                      System.TeamProject: example_value
                      System.AreaPath: example_value
                      System.IterationPath: example_value
                      System.Description: example_value
                      System.Tags: example_value
                      Microsoft.VSTS.Common.Priority: 10
                      Microsoft.VSTS.Common.Severity: example_value
                    relations:
                    - rel: example_value
                      url: https://www.example.com
                      attributes: {}
                    url: https://www.example.com
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{project}/_apis/wit/workitems/${type}:
    post:
      operationId: createWorkItem
      summary: Create a New Work Item
      description: Creates a new work item of the specified type. Uses JSON Patch to set field values.
      tags:
      - WorkItems
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: project
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: type
        in: path
        required: true
        description: Work item type (e.g., Bug, Task, User Story, Epic, Feature)
        schema:
          type: string
        example: example_value
      - name: api-version
        in: query
        required: true
        schema:
          type: string
          default: 7.2-preview.3
        example: example_value
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/JsonPatchOperation'
            examples:
              createBug:
                summary: Create a Bug work item
                value:
                - op: add
                  path: /fields/System.Title
                  value: Fix login button on mobile
                - op: add
                  path: /fields/Microsoft.VSTS.TCM.ReproSteps
                  value: '1. Open app on mobile

                    2. Tap login button

                    3. Nothing happens'
                - op: add
                  path: /fields/System.AreaPath
                  value: MyProject\Frontend
      responses:
        '200':
          description: Created work item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
              examples:
                Createworkitem200Example:
                  summary: Default createWorkItem 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    rev: 10
                    fields:
                      System.Id: '500123'
                      System.Title: example_value
                      System.WorkItemType: example_value
                      System.State: example_value
                      System.Reason: example_value
                      System.AssignedTo:
                        displayName: example_value
                        id: abc123
                        uniqueName: example_value
                      System.CreatedDate: '2026-01-15T10:30:00Z'
                      System.CreatedBy:
                        displayName: example_value
                      System.ChangedDate: '2026-01-15T10:30:00Z'
                      System.TeamProject: example_value
                      System.AreaPath: example_value
                      System.IterationPath: example_value
                      System.Description: example_value
                      System.Tags: example_value
                      Microsoft.VSTS.Common.Priority: 10
                      Microsoft.VSTS.Common.Severity: example_value
                    relations:
                    - rel: example_value
                      url: https://www.example.com
                      attributes: {}
                    url: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{project}/_apis/wit/workitems:
    get:
      operationId: getWorkItemsBatch
      summary: Get Work Items by Ids
      description: Returns multiple work items by a list of IDs.
      tags:
      - WorkItems
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: project
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: ids
        in: query
        required: true
        description: Comma-separated list of work item IDs (max 200)
        schema:
          type: string
        example: example_value
      - name: $expand
        in: query
        schema:
          type: string
        example: example_value
      - name: api-version
        in: query
        required: true
        schema:
          type: string
          default: 7.2-preview.3
        example: example_value
      responses:
        '200':
          description: List of work items
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkItem'
              examples:
                Getworkitemsbatch200Example:
                  summary: Default getWorkItemsBatch 200 response
                  x-microcks-default: true
                  value:
                    count: 10
                    value:
                    - id: abc123
                      rev: 10
                      fields:
                        System.Id: '500123'
                        System.Title: example_value
                        System.WorkItemType: example_value
                        System.State: example_value
                        System.Reason: example_value
                        System.AssignedTo: {}
                        System.CreatedDate: '2026-01-15T10:30:00Z'
                        System.CreatedBy: {}
                        System.ChangedDate: '2026-01-15T10:30:00Z'
                        System.TeamProject: example_value
                        System.AreaPath: example_value
                        System.IterationPath: example_value
                        System.Description: example_value
                        System.Tags: example_value
                        Microsoft.VSTS.Common.Priority: 10
                        Microsoft.VSTS.Common.Severity: example_value
                      relations:
                      - {}
                      url: https://www.example.com
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    WorkItemRelation:
      type: object
      properties:
        rel:
          type: string
          description: Relation type (e.g., System.LinkTypes.Hierarchy-Forward, System.LinkTypes.Related)
          example: example_value
        url:
          type: string
          format: uri
          example: https://www.example.com
        attributes:
          type: object
          properties:
            name:
              type: string
            comment:
              type: string
          example: example_value
    JsonPatchOperation:
      type: object
      required:
      - op
      - path
      properties:
        op:
          type: string
          enum:
          - add
          - remove
          - replace
          - copy
          - move
          - test
          example: add
        path:
          type: string
          description: JSON Pointer path to the field
          example: example_value
        value:
          description: New value for add/replace operations
          example: example_value
        from:
          type: string
          description: Source path for copy/move operations
          example: example_value
    WorkItem:
      type: object
      description: Azure DevOps work item
      properties:
        id:
          type: integer
          description: Work item ID
          example: abc123
        rev:
          type: integer
          description: Revision number
          example: 10
        fields:
          type: object
          description: Work item field values
          additionalProperties: true
          properties:
            System.Id:
              type: integer
            System.Title:
              type: string
            System.WorkItemType:
              type: string
            System.State:
              type: string
            System.Reason:
              type: string
            System.AssignedTo:
              type: object
              properties:
                displayName:
                  type: string
                id:
                  type: string
                uniqueName:
                  type: string
            System.CreatedDate:
              type: string
              format: date-time
            System.CreatedBy:
              type: object
              properties:
                displayName:
                  type: string
            System.ChangedDate:
              type: string
              format: date-time
            System.TeamProject:
              type: string
            System.AreaPath:
              type: string
            System.IterationPath:
              type: string
            System.Description:
              type: string
            System.Tags:
              type: string
            Microsoft.VSTS.Common.Priority:
              type: integer
              minimum: 1
              maximum: 4
            Microsoft.VSTS.Common.Severity:
              type: string
          example: example_value
        relations:
          type: array
          items:
            $ref: '#/components/schemas/WorkItemRelation'
          example: []
        url:
          type: string
          format: uri
          example: https://www.example.com
    Error:
      type: object
      properties:
        id:
          type: string
          example: abc123
        innerException:
          type: object
          example: example_value
        message:
          type: string
          example: example_value
        typeName:
          type: string
          example: example_value
        typeKey:
          type: string
          example: example_value
        errorCode:
          type: integer
          example: 10
        eventId:
          type: integer
          example: '500123'
  securitySchemes:
    personalAccessToken:
      type: http
      scheme: basic
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.vssps.visualstudio.com/oauth2/authorize
          tokenUrl: https://app.vssps.visualstudio.com/oauth2/token
          scopes:
            vso.build: Read build data
            vso.build_execute: Queue and manage builds