Azure DevOps Attachments API

openapi: 3.2.0
info:
  title: Azure DevOps Work Items Attachments 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
paths:
  /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:
  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:
    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
    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
  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.