Azure DevOps Build Definitions API

openapi: 3.1.0
info:
  title: Azure DevOps Artifacts Attachments Build Definitions API
  description: 'REST API for managing packages, feeds, and artifact dependencies in Azure Artifacts. Supports NuGet, npm, Maven, Python, and Universal package formats in private or public feeds. Enables programmatic management of package feeds, discovery of packages and their versions, and lifecycle operations such as deprecating or deleting package versions.

    '
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/artifacts/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://feeds.dev.azure.com/{organization}/{project}/_apis
  description: Azure DevOps Artifacts API (project-scoped)
  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: Build Definitions
  description: Operations for managing build pipeline definitions
paths:
  /build/definitions:
    get:
      operationId: definitions_list
      summary: Azure DevOps List build definitions
      description: 'Returns a list of build definitions (pipelines) in the project. Supports filtering by name and path, and returns summary information for each definition.

        '
      tags:
      - Build Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: name
        in: query
        required: false
        description: Filter definitions by name (supports wildcards with *)
        schema:
          type: string
      - name: path
        in: query
        required: false
        description: Filter definitions by folder path
        schema:
          type: string
      - name: builtAfter
        in: query
        required: false
        description: Return definitions that were built after this date
        schema:
          type: string
          format: date-time
      - name: $top
        in: query
        required: false
        description: Maximum number of definitions to return
        schema:
          type: integer
      - name: continuationToken
        in: query
        required: false
        description: Continuation token for paginated results
        schema:
          type: string
      responses:
        '200':
          description: List of build definitions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuildDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: definitions_create
      summary: Azure DevOps Create a build definition
      description: 'Creates a new build definition (pipeline) in the project. The definition specifies the build steps, triggers, variables, and agent requirements.

        '
      tags:
      - Build Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionToCloneId
        in: query
        required: false
        description: ID of an existing definition to clone
        schema:
          type: integer
      - name: definitionToCloneRevision
        in: query
        required: false
        description: Revision number of the definition to clone
        schema:
          type: integer
      requestBody:
        required: true
        description: Build definition to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildDefinitionCreateRequest'
      responses:
        '200':
          description: Build definition created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /build/definitions/{definitionId}:
    get:
      operationId: definitions_get
      summary: Azure DevOps Get a build definition
      description: 'Returns detailed information about a specific build definition, including all steps, triggers, variables, and configuration. You can also request a specific revision of the definition.

        '
      tags:
      - Build Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionId
        in: path
        required: true
        description: Numeric ID of the build definition
        schema:
          type: integer
      - name: revision
        in: query
        required: false
        description: Specific revision number to retrieve
        schema:
          type: integer
      - name: minMetricsTime
        in: query
        required: false
        description: Minimum date for including build metrics
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Build definition returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: definitions_update
      summary: Azure DevOps Update a build definition
      description: 'Replaces an existing build definition with the provided definition. The revision number in the body must match the current revision to prevent concurrent modification conflicts.

        '
      tags:
      - Build Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionId
        in: path
        required: true
        description: Numeric ID of the build definition to update
        schema:
          type: integer
      - name: secretsSourceDefinitionId
        in: query
        required: false
        description: ID of the definition to clone secrets from
        schema:
          type: integer
      - name: secretsSourceDefinitionRevision
        in: query
        required: false
        description: Revision number to clone secrets from
        schema:
          type: integer
      requestBody:
        required: true
        description: Updated build definition
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildDefinition'
      responses:
        '200':
          description: Build definition updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: definitions_delete
      summary: Azure DevOps Delete a build definition
      description: 'Deletes a build definition. All associated builds must be deleted first, or you must specify deleteBuilds=true to cascade delete all associated builds.

        '
      tags:
      - Build Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionId
        in: path
        required: true
        description: Numeric ID of the build definition to delete
        schema:
          type: integer
      responses:
        '204':
          description: Build definition deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    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'
    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'
  schemas:
    TeamProjectReference:
      type: object
      description: Reference to an Azure DevOps project
      properties:
        id:
          type: string
          format: uuid
          description: Project ID
        name:
          type: string
          description: Project name
        description:
          type: string
        url:
          type: string
          format: uri
        state:
          type: string
          enum:
          - deleting
          - new
          - wellFormed
          - createPending
          - all
          - unchanged
          - deleted
        visibility:
          type: string
          enum:
          - private
          - public
        revision:
          type: integer
    BuildDefinition:
      type: object
      description: A build pipeline definition in Azure DevOps
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the definition
          example: 5
        name:
          type: string
          description: Display name of the build definition
          example: CI-Pipeline
        path:
          type: string
          description: Folder path for organizing definitions
          example: \MyFolder
        type:
          type: string
          description: Type of build definition
          enum:
          - xaml
          - build
        revision:
          type: integer
          description: Current revision number of the definition
        quality:
          type: string
          description: Quality of the definition
          enum:
          - definition
          - draft
        authoredBy:
          $ref: '#/components/schemas/IdentityRef'
        queue:
          type: object
          description: Default agent queue for this definition
          properties:
            id:
              type: integer
            name:
              type: string
            pool:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
                isHosted:
                  type: boolean
        project:
          $ref: '#/components/schemas/TeamProjectReference'
        url:
          type: string
          format: uri
        uri:
          type: string
        createdDate:
          type: string
          format: date-time
        queueStatus:
          type: string
          description: Whether new builds can be queued against this definition
          enum:
          - enabled
          - paused
          - disabled
        variables:
          type: object
          description: Map of variable names to variable definitions
          additionalProperties:
            type: object
            properties:
              value:
                type: string
              allowOverride:
                type: boolean
              isSecret:
                type: boolean
        triggers:
          type: array
          description: Triggers that automatically start this build
          items:
            type: object
            properties:
              triggerType:
                type: string
                enum:
                - none
                - continuousIntegration
                - batchedContinuousIntegration
                - schedule
                - gatedCheckIn
                - buildCompletion
                - pullRequest
        repository:
          $ref: '#/components/schemas/BuildRepository'
        process:
          type: object
          description: Build process definition (YAML or designer)
          properties:
            yamlFilename:
              type: string
              description: Path to the YAML pipeline file
            type:
              type: integer
              description: 1 = designer, 2 = YAML
    BuildRepository:
      type: object
      description: Repository configuration for a build
      properties:
        id:
          type: string
          description: Repository ID (GUID for Git, name for TFVC)
        name:
          type: string
          description: Repository name
        type:
          type: string
          description: Repository type
          enum:
          - TfsGit
          - TfsVersionControl
          - GitHub
          - Bitbucket
          - GitHubEnterprise
        url:
          type: string
          format: uri
          description: URL of the repository
        defaultBranch:
          type: string
          description: Default branch for this repository
          example: refs/heads/main
        checkoutSubmodules:
          type: boolean
          description: Whether to checkout Git submodules
        clean:
          type: string
          description: Whether to clean the working directory before each build
          enum:
          - 'true'
          - 'false'
          - null
        properties:
          type: object
          additionalProperties: true
    IdentityRef:
      type: object
      description: Reference to an Azure DevOps user identity
      properties:
        id:
          type: string
          format: uuid
        displayName:
          type: string
          example: John Doe
        uniqueName:
          type: string
          example: john.doe@example.com
        url:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
        descriptor:
          type: string
    ApiError:
      type: object
      description: Error response from the Azure DevOps API
      properties:
        id:
          type: string
          format: uuid
        message:
          type: string
        typeName:
          type: string
        typeKey:
          type: string
        errorCode:
          type: integer
        eventId:
          type: integer
    BuildDefinitionCreateRequest:
      type: object
      description: Request to create a new build definition
      required:
      - name
      - repository
      - process
      - queue
      properties:
        name:
          type: string
          description: Display name of the build definition
        path:
          type: string
          description: Folder path for the definition
          default: \
        type:
          type: string
          enum:
          - xaml
          - build
          default: build
        repository:
          $ref: '#/components/schemas/BuildRepository'
        process:
          type: object
          description: Build process configuration
          properties:
            yamlFilename:
              type: string
            type:
              type: integer
        queue:
          type: object
          properties:
            id:
              type: integer
        variables:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                type: string
              isSecret:
                type: boolean
        triggers:
          type: array
          items:
            type: object
  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.