Azure DevOps Build Definitions API

openapi: 3.2.0
info:
  title: Azure DevOps Builds Build Definitions API
  description: 'REST API for managing build definitions (pipelines), queuing builds, monitoring build status, accessing build logs, timelines, and artifacts. Supports the full lifecycle of continuous integration builds in Azure DevOps.

    '
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://dev.azure.com/{organization}/{project}/_apis
  description: Azure DevOps Build 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: 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:
    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
        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
    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
    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
    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
    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
    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.