openapi: 3.1.0
info:
  title: Azure Build REST Artifacts Pipelines API
  description: REST API for managing build definitions, queuing builds, and retrieving build results, artifacts, tags, and logs in Azure DevOps. Supports the full lifecycle of continuous integration builds including creating and updating build definitions, listing and filtering builds by status and result, tagging builds for identification, and downloading build artifacts.
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/
  termsOfService: https://azure.microsoft.com/en-us/support/legal/
servers:
- url: https://dev.azure.com/{organization}/{project}/_apis
  description: Azure DevOps Services
  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: Pipelines
  description: Operations for managing YAML-based pipeline definitions including creating, listing, and retrieving pipeline configurations.
paths:
  /pipelines:
    get:
      operationId: listPipelines
      summary: Azure Pipelines List pipelines
      description: Returns a list of pipeline definitions in the project. Pipelines are YAML-based CI/CD definitions stored in source repositories. Supports ordering and pagination through query parameters.
      tags:
      - Pipelines
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: orderBy
        in: query
        required: false
        description: Sort order for pipelines (e.g., name asc, createdDate desc)
        schema:
          type: string
      - name: $top
        in: query
        required: false
        description: Maximum number of pipelines to return
        schema:
          type: integer
      - name: continuationToken
        in: query
        required: false
        description: Continuation token for paginated results returned by a previous call
        schema:
          type: string
      responses:
        '200':
          description: List of pipelines returned successfully
          headers:
            x-ms-continuationtoken:
              description: Token for retrieving the next page of results
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of pipelines in this response
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pipeline'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createPipeline
      summary: Azure Pipelines Create a pipeline
      description: Creates a new pipeline definition in the project. The pipeline references a YAML file in a source repository. After creation the pipeline can be triggered manually or automatically by code changes, schedules, or other pipeline completions.
      tags:
      - Pipelines
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        description: Pipeline creation parameters specifying name, folder, and YAML configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePipelineParameters'
      responses:
        '200':
          description: Pipeline created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /pipelines/{pipelineId}:
    get:
      operationId: getPipeline
      summary: Azure Pipelines Get a pipeline
      description: Returns detailed information about a specific pipeline definition including its configuration, repository source, folder path, and revision number. Optionally retrieves a specific version of the pipeline definition.
      tags:
      - Pipelines
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/PipelineId'
      - name: pipelineVersion
        in: query
        required: false
        description: Specific version of the pipeline definition to retrieve
        schema:
          type: integer
      responses:
        '200':
          description: Pipeline returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
        '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:
    PipelineConfiguration:
      type: object
      description: Configuration details specifying how a pipeline is defined including the type, YAML file path, and source repository.
      properties:
        type:
          type: string
          description: Pipeline configuration type
          enum:
          - unknown
          - yaml
          - designerJson
          - justInTime
          - designerHyphenJson
        path:
          type: string
          description: Path to the YAML pipeline file in the repository
        repository:
          $ref: '#/components/schemas/BuildRepository'
    ReferenceLinks:
      type: object
      description: HAL links for navigating to related resources
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              format: uri
        web:
          type: object
          properties:
            href:
              type: string
              format: uri
        pipeline:
          type: object
          properties:
            href:
              type: string
              format: uri
        pipeline.web:
          type: object
          properties:
            href:
              type: string
              format: uri
    CreatePipelineParameters:
      type: object
      description: Parameters for creating a new pipeline definition
      required:
      - name
      - configuration
      properties:
        name:
          type: string
          description: Display name for the new pipeline
        folder:
          type: string
          description: Folder path where the pipeline will be organized
          default: \
        configuration:
          type: object
          description: Pipeline configuration specifying the YAML file and repository
          required:
          - type
          - path
          - repository
          properties:
            type:
              type: string
              description: Configuration type (use yaml for YAML-based pipelines)
              enum:
              - unknown
              - yaml
              - designerJson
              - justInTime
              - designerHyphenJson
            path:
              type: string
              description: Path to the YAML file in the repository
            repository:
              type: object
              description: Repository where the pipeline YAML file is located
              required:
              - id
              - type
              properties:
                id:
                  type: string
                  description: Repository GUID for Azure Repos or full name for GitHub
                type:
                  type: string
                  description: Source repository type
                  enum:
                  - unknown
                  - azureReposGit
                  - gitHub
                  - azureReposGitHyphenated
                name:
                  type: string
                  description: Repository name (required for GitHub repositories)
    BuildRepository:
      type: object
      description: Repository configuration for a pipeline
      properties:
        id:
          type: string
          description: Repository identifier
        name:
          type: string
          description: Repository name
        type:
          type: string
          description: Repository type
          enum:
          - TfsGit
          - TfsVersionControl
          - GitHub
          - Bitbucket
          - GitHubEnterprise
        url:
          type: string
          format: uri
          description: Repository URL
        defaultBranch:
          type: string
          description: Default branch for the repository
    ApiError:
      type: object
      description: Error response from the Azure DevOps API
      properties:
        id:
          type: string
          format: uuid
          description: Unique error instance identifier
        message:
          type: string
          description: Human-readable error message
        typeName:
          type: string
          description: Full type name of the error
        typeKey:
          type: string
          description: Error type key
        errorCode:
          type: integer
          description: Numeric error code
        eventId:
          type: integer
          description: Event identifier for tracking
    Pipeline:
      type: object
      description: An Azure DevOps pipeline definition representing a YAML-based CI/CD workflow stored in a source repository.
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the pipeline
        name:
          type: string
          description: Display name of the pipeline
        folder:
          type: string
          description: Folder path for organizing pipelines in the project
        revision:
          type: integer
          description: Current revision number of the pipeline definition
        url:
          type: string
          format: uri
          description: REST API URL to access this pipeline
        _links:
          $ref: '#/components/schemas/ReferenceLinks'
        configuration:
          $ref: '#/components/schemas/PipelineConfiguration'
  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'
    PipelineId:
      name: pipelineId
      in: path
      required: true
      description: Numeric ID of the pipeline definition
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Azure AD OAuth 2.0 bearer token with vso.build scope
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Personal Access Token (PAT)
externalDocs:
  description: Azure DevOps Build REST API Documentation
  url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/