Azure DevOps Comments API

openapi: 3.2.0
info:
  title: Azure DevOps Work Items Comments 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: Comments
  description: Operations for work item comments
paths:
  /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'
components:
  responses:
    BadRequest:
      description: Bad request - invalid parameters or request body
      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'
    Forbidden:
      description: Forbidden - insufficient permissions to perform this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    IdentityRef:
      type: object
      description: Reference to an Azure DevOps user identity
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the user
        displayName:
          type: string
          description: Display name of the user
          example: John Doe
        uniqueName:
          type: string
          description: Unique name (usually email address)
          example: john.doe@example.com
        url:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
          description: URL of the user's profile image
        descriptor:
          type: string
          description: Subject descriptor for the identity
    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
    ApiError:
      type: object
      description: Error response from the Azure DevOps API
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the error instance
        innerException:
          type: object
          nullable: true
          description: Inner exception details if applicable
        message:
          type: string
          description: Human-readable error message
        typeName:
          type: string
          description: Type name of the exception
        typeKey:
          type: string
          description: Short type key for the error
        errorCode:
          type: integer
          description: Numeric error code
        eventId:
          type: integer
          description: Event ID for logging and tracing
  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'
  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.