Azure Pipelines Build REST API

naftiko: 1.0.0-alpha2
info:
  label: Azure Pipelines Build REST 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.
  tags:
  - Microsoft
  - Azure
  - Pipelines
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: microsoft-azure-pipelines
    baseUri: https://dev.azure.com/myorganization/myproject/_apis
    description: Azure Pipelines Build REST API HTTP API.
    authentication:
      type: bearer
      token: '{{MICROSOFT_AZURE_PIPELINES_TOKEN}}'
    resources:
    - name: build-builds
      path: /build/builds
      operations:
      - name: listbuilds
        method: GET
        description: Azure Pipelines List builds
        inputParameters:
        - name: definitions
          in: query
          type: string
          description: Comma-delimited list of definition IDs to filter by
        - name: queues
          in: query
          type: string
          description: Comma-delimited list of queue IDs to filter by
        - name: buildNumber
          in: query
          type: string
          description: Filter by build number. Append asterisk for prefix matching.
        - name: minTime
          in: query
          type: string
          description: Filter to builds after this date based on the query order
        - name: maxTime
          in: query
          type: string
          description: Filter to builds before this date based on the query order
        - name: requestedFor
          in: query
          type: string
          description: Filter to builds requested by this user
        - name: reasonFilter
          in: query
          type: string
          description: Filter by the reason the build was created
        - name: statusFilter
          in: query
          type: string
          description: Filter by current build status
        - name: resultFilter
          in: query
          type: string
          description: Filter by build result
        - name: tagFilters
          in: query
          type: string
          description: Comma-delimited list of tags to filter by
        - name: $top
          in: query
          type: integer
          description: Maximum number of builds to return
        - name: continuationToken
          in: query
          type: string
          description: Continuation token for paginated results
        - name: maxBuildsPerDefinition
          in: query
          type: integer
          description: Maximum number of builds to return per definition
        - name: deletedFilter
          in: query
          type: string
          description: Filter for deleted builds
        - name: queryOrder
          in: query
          type: string
          description: Sort order for the results
        - name: branchName
          in: query
          type: string
          description: Filter to builds from this branch
        - name: buildIds
          in: query
          type: string
          description: Comma-delimited list of build IDs to retrieve
        - name: repositoryId
          in: query
          type: string
          description: Filter to builds from this repository
        - name: repositoryType
          in: query
          type: string
          description: Filter to builds from repositories of this type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-builds-buildid
      path: /build/builds/{buildId}
      operations:
      - name: getbuild
        method: GET
        description: Azure Pipelines Get a build
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatebuild
        method: PATCH
        description: Azure Pipelines Update a build
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletebuild
        method: DELETE
        description: Azure Pipelines Delete a build
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-builds-buildid-artifacts
      path: /build/builds/{buildId}/artifacts
      operations:
      - name: listbuildartifacts
        method: GET
        description: Azure Pipelines List build artifacts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-builds-buildid-artifacts-artifactname
      path: /build/builds/{buildId}/artifacts/{artifactName}
      operations:
      - name: getbuildartifact
        method: GET
        description: Azure Pipelines Get a specific build artifact
        inputParameters:
        - name: artifactName
          in: path
          type: string
          required: true
          description: Name of the artifact to retrieve
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-builds-buildid-tags
      path: /build/builds/{buildId}/tags
      operations:
      - name: listbuildtags
        method: GET
        description: Azure Pipelines List build tags
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-builds-buildid-tags-tag
      path: /build/builds/{buildId}/tags/{tag}
      operations:
      - name: addbuildtag
        method: PUT
        description: Azure Pipelines Add a tag to a build
        inputParameters:
        - name: tag
          in: path
          type: string
          required: true
          description: Tag to add to the build
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletebuildtag
        method: DELETE
        description: Azure Pipelines Remove a tag from a build
        inputParameters:
        - name: tag
          in: path
          type: string
          required: true
          description: Tag to remove from the build
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-definitions
      path: /build/definitions
      operations:
      - name: listbuilddefinitions
        method: GET
        description: Azure Pipelines List build definitions
        inputParameters:
        - name: name
          in: query
          type: string
          description: Filter by definition name (supports prefix match with asterisk)
        - name: repositoryId
          in: query
          type: string
          description: Filter to definitions using this repository
        - name: repositoryType
          in: query
          type: string
          description: Filter by repository type
        - name: queryOrder
          in: query
          type: string
          description: Sort order for results
        - name: $top
          in: query
          type: integer
          description: Maximum number of definitions to return
        - name: continuationToken
          in: query
          type: string
          description: Continuation token for paginated results
        - name: path
          in: query
          type: string
          description: Filter by folder path
        - name: builtAfter
          in: query
          type: string
          description: Filter to definitions with builds after this date
        - name: notBuiltAfter
          in: query
          type: string
          description: Filter to definitions without builds after this date
        - name: includeAllProperties
          in: query
          type: boolean
          description: Include all properties of the definition
        - name: includeLatestBuilds
          in: query
          type: boolean
          description: Include the latest build for each definition
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: build-definitions-definitionid
      path: /build/definitions/{definitionId}
      operations:
      - name: getbuilddefinition
        method: GET
        description: Azure Pipelines Get a build definition
        inputParameters:
        - name: definitionId
          in: path
          type: integer
          required: true
          description: Numeric ID of the build definition
        - name: revision
          in: query
          type: integer
          description: Specific revision of the definition to retrieve
        - name: includeLatestBuilds
          in: query
          type: boolean
          description: Include the latest build for the definition
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: microsoft-azure-pipelines-rest
    description: REST adapter for Azure Pipelines Build REST API.
    resources:
    - path: /build/builds
      name: listbuilds
      operations:
      - method: GET
        name: listbuilds
        description: Azure Pipelines List builds
        call: microsoft-azure-pipelines.listbuilds
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}
      name: getbuild
      operations:
      - method: GET
        name: getbuild
        description: Azure Pipelines Get a build
        call: microsoft-azure-pipelines.getbuild
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}
      name: updatebuild
      operations:
      - method: PATCH
        name: updatebuild
        description: Azure Pipelines Update a build
        call: microsoft-azure-pipelines.updatebuild
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}
      name: deletebuild
      operations:
      - method: DELETE
        name: deletebuild
        description: Azure Pipelines Delete a build
        call: microsoft-azure-pipelines.deletebuild
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}/artifacts
      name: listbuildartifacts
      operations:
      - method: GET
        name: listbuildartifacts
        description: Azure Pipelines List build artifacts
        call: microsoft-azure-pipelines.listbuildartifacts
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}/artifacts/{artifactName}
      name: getbuildartifact
      operations:
      - method: GET
        name: getbuildartifact
        description: Azure Pipelines Get a specific build artifact
        call: microsoft-azure-pipelines.getbuildartifact
        with:
          artifactName: rest.artifactName
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}/tags
      name: listbuildtags
      operations:
      - method: GET
        name: listbuildtags
        description: Azure Pipelines List build tags
        call: microsoft-azure-pipelines.listbuildtags
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}/tags/{tag}
      name: addbuildtag
      operations:
      - method: PUT
        name: addbuildtag
        description: Azure Pipelines Add a tag to a build
        call: microsoft-azure-pipelines.addbuildtag
        with:
          tag: rest.tag
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/builds/{buildId}/tags/{tag}
      name: deletebuildtag
      operations:
      - method: DELETE
        name: deletebuildtag
        description: Azure Pipelines Remove a tag from a build
        call: microsoft-azure-pipelines.deletebuildtag
        with:
          tag: rest.tag
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/definitions
      name: listbuilddefinitions
      operations:
      - method: GET
        name: listbuilddefinitions
        description: Azure Pipelines List build definitions
        call: microsoft-azure-pipelines.listbuilddefinitions
        outputParameters:
        - type: object
          mapping: $.
    - path: /build/definitions/{definitionId}
      name: getbuilddefinition
      operations:
      - method: GET
        name: getbuilddefinition
        description: Azure Pipelines Get a build definition
        call: microsoft-azure-pipelines.getbuilddefinition
        with:
          definitionId: rest.definitionId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: microsoft-azure-pipelines-mcp
    transport: http
    description: MCP adapter for Azure Pipelines Build REST API for AI agent use.
    tools:
    - name: listbuilds
      description: Azure Pipelines List builds
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.listbuilds
      with:
        definitions: tools.definitions
        queues: tools.queues
        buildNumber: tools.buildNumber
        minTime: tools.minTime
        maxTime: tools.maxTime
        requestedFor: tools.requestedFor
        reasonFilter: tools.reasonFilter
        statusFilter: tools.statusFilter
        resultFilter: tools.resultFilter
        tagFilters: tools.tagFilters
        $top: tools.$top
        continuationToken: tools.continuationToken
        maxBuildsPerDefinition: tools.maxBuildsPerDefinition
        deletedFilter: tools.deletedFilter
        queryOrder: tools.queryOrder
        branchName: tools.branchName
        buildIds: tools.buildIds
        repositoryId: tools.repositoryId
        repositoryType: tools.repositoryType
      inputParameters:
      - name: definitions
        type: string
        description: Comma-delimited list of definition IDs to filter by
      - name: queues
        type: string
        description: Comma-delimited list of queue IDs to filter by
      - name: buildNumber
        type: string
        description: Filter by build number. Append asterisk for prefix matching.
      - name: minTime
        type: string
        description: Filter to builds after this date based on the query order
      - name: maxTime
        type: string
        description: Filter to builds before this date based on the query order
      - name: requestedFor
        type: string
        description: Filter to builds requested by this user
      - name: reasonFilter
        type: string
        description: Filter by the reason the build was created
      - name: statusFilter
        type: string
        description: Filter by current build status
      - name: resultFilter
        type: string
        description: Filter by build result
      - name: tagFilters
        type: string
        description: Comma-delimited list of tags to filter by
      - name: $top
        type: integer
        description: Maximum number of builds to return
      - name: continuationToken
        type: string
        description: Continuation token for paginated results
      - name: maxBuildsPerDefinition
        type: integer
        description: Maximum number of builds to return per definition
      - name: deletedFilter
        type: string
        description: Filter for deleted builds
      - name: queryOrder
        type: string
        description: Sort order for the results
      - name: branchName
        type: string
        description: Filter to builds from this branch
      - name: buildIds
        type: string
        description: Comma-delimited list of build IDs to retrieve
      - name: repositoryId
        type: string
        description: Filter to builds from this repository
      - name: repositoryType
        type: string
        description: Filter to builds from repositories of this type
      outputParameters:
      - type: object
        mapping: $.
    - name: getbuild
      description: Azure Pipelines Get a build
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.getbuild
      outputParameters:
      - type: object
        mapping: $.
    - name: updatebuild
      description: Azure Pipelines Update a build
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: microsoft-azure-pipelines.updatebuild
      outputParameters:
      - type: object
        mapping: $.
    - name: deletebuild
      description: Azure Pipelines Delete a build
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: microsoft-azure-pipelines.deletebuild
      outputParameters:
      - type: object
        mapping: $.
    - name: listbuildartifacts
      description: Azure Pipelines List build artifacts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.listbuildartifacts
      outputParameters:
      - type: object
        mapping: $.
    - name: getbuildartifact
      description: Azure Pipelines Get a specific build artifact
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.getbuildartifact
      with:
        artifactName: tools.artifactName
      inputParameters:
      - name: artifactName
        type: string
        description: Name of the artifact to retrieve
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listbuildtags
      description: Azure Pipelines List build tags
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.listbuildtags
      outputParameters:
      - type: object
        mapping: $.
    - name: addbuildtag
      description: Azure Pipelines Add a tag to a build
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.addbuildtag
      with:
        tag: tools.tag
      inputParameters:
      - name: tag
        type: string
        description: Tag to add to the build
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: deletebuildtag
      description: Azure Pipelines Remove a tag from a build
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: microsoft-azure-pipelines.deletebuildtag
      with:
        tag: tools.tag
      inputParameters:
      - name: tag
        type: string
        description: Tag to remove from the build
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listbuilddefinitions
      description: Azure Pipelines List build definitions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.listbuilddefinitions
      with:
        name: tools.name
        repositoryId: tools.repositoryId
        repositoryType: tools.repositoryType
        queryOrder: tools.queryOrder
        $top: tools.$top
        continuationToken: tools.continuationToken
        path: tools.path
        builtAfter: tools.builtAfter
        notBuiltAfter: tools.notBuiltAfter
        includeAllProperties: tools.includeAllProperties
        includeLatestBuilds: tools.includeLatestBuilds
      inputParameters:
      - name: name
        type: string
        description: Filter by definition name (supports prefix match with asterisk)
      - name: repositoryId
        type: string
        description: Filter to definitions using this repository
      - name: repositoryType
        type: string
        description: Filter by repository type
      - name: queryOrder
        type: string
        description: Sort order for results
      - name: $top
        type: integer
        description: Maximum number of definitions to return
      - name: continuationToken
        type: string
        description: Continuation token for paginated results
      - name: path
        type: string
        description: Filter by folder path
      - name: builtAfter
        type: string
        description: Filter to definitions with builds after this date
      - name: notBuiltAfter
        type: string
        description: Filter to definitions without builds after this date
      - name: includeAllProperties
        type: boolean
        description: Include all properties of the definition
      - name: includeLatestBuilds
        type: boolean
        description: Include the latest build for each definition
      outputParameters:
      - type: object
        mapping: $.
    - name: getbuilddefinition
      description: Azure Pipelines Get a build definition
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: microsoft-azure-pipelines.getbuilddefinition
      with:
        definitionId: tools.definitionId
        revision: tools.revision
        includeLatestBuilds: tools.includeLatestBuilds
      inputParameters:
      - name: definitionId
        type: integer
        description: Numeric ID of the build definition
        required: true
      - name: revision
        type: integer
        description: Specific revision of the definition to retrieve
      - name: includeLatestBuilds
        type: boolean
        description: Include the latest build for the definition
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    MICROSOFT_AZURE_PIPELINES_TOKEN: MICROSOFT_AZURE_PIPELINES_TOKEN