openapi: 3.1.0
info:
  title: Azure Repos Git Commits Pull Requests API
  description: REST API for managing Git repositories, branches, commits, pull requests, pushes, and items in Azure Repos. Provides full programmatic control over Git-based source code hosted in Azure DevOps, including creating and reviewing pull requests, managing branches and tags, browsing repository content, and pushing commits.
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  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: The name of the Azure DevOps organization
      default: myorganization
    project:
      description: Project ID or project name
      default: myproject
security:
- oauth2: []
- basicAuth: []
tags:
- name: Pull Requests
  description: Operations for creating, retrieving, updating, and completing pull requests. Includes managing reviewers, labels, and merge options.
paths:
  /git/repositories/{repositoryId}/pullrequests:
    get:
      operationId: pullRequests_list
      summary: Azure Repos List pull requests
      description: Retrieve all pull requests matching specified criteria for a repository. Supports filtering by status, creator, reviewer, source branch, target branch, and time range. The description field is truncated to 400 characters in the result.
      tags:
      - Pull Requests
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      - name: searchCriteria.status
        in: query
        description: Filter by pull request status. Defaults to active if unset.
        schema:
          type: string
          enum:
          - active
          - abandoned
          - completed
          - all
          - notSet
      - name: searchCriteria.creatorId
        in: query
        description: Filter by the identity ID of the pull request creator
        schema:
          type: string
          format: uuid
      - name: searchCriteria.reviewerId
        in: query
        description: Filter by the identity ID of a reviewer
        schema:
          type: string
          format: uuid
      - name: searchCriteria.sourceRefName
        in: query
        description: Filter by source branch name (e.g., refs/heads/feature)
        schema:
          type: string
      - name: searchCriteria.targetRefName
        in: query
        description: Filter by target branch name (e.g., refs/heads/main)
        schema:
          type: string
      - name: searchCriteria.repositoryId
        in: query
        description: Filter by target repository ID
        schema:
          type: string
          format: uuid
      - name: searchCriteria.sourceRepositoryId
        in: query
        description: Filter by source repository ID
        schema:
          type: string
          format: uuid
      - name: searchCriteria.includeLinks
        in: query
        description: Whether to include the _links field on shallow references
        schema:
          type: boolean
      - name: searchCriteria.minTime
        in: query
        description: Filter pull requests created or closed after this date based on queryTimeRangeType
        schema:
          type: string
          format: date-time
      - name: searchCriteria.maxTime
        in: query
        description: Filter pull requests created or closed before this date based on queryTimeRangeType
        schema:
          type: string
          format: date-time
      - name: searchCriteria.queryTimeRangeType
        in: query
        description: The type of time range for minTime and maxTime. Defaults to created if unset.
        schema:
          type: string
          enum:
          - created
          - closed
      - name: $top
        in: query
        description: Number of pull requests to retrieve
        schema:
          type: integer
          format: int32
      - name: $skip
        in: query
        description: Number of pull requests to skip
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successfully retrieved list of pull requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of pull requests returned
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/GitPullRequest'
        '401':
          description: Unauthorized
        '404':
          description: Repository not found
    post:
      operationId: pullRequests_create
      summary: Azure Repos Create a pull request
      description: Create a new pull request in the specified repository. Requires source and target branch references, a title, and optionally a description, reviewers, and work item references.
      tags:
      - Pull Requests
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceRefName
              - targetRefName
              - title
              properties:
                sourceRefName:
                  type: string
                  description: Source branch reference (e.g., refs/heads/feature-branch)
                targetRefName:
                  type: string
                  description: Target branch reference (e.g., refs/heads/main)
                title:
                  type: string
                  description: Title of the pull request
                description:
                  type: string
                  description: Description of the pull request
                isDraft:
                  type: boolean
                  description: Whether this is a draft pull request
                reviewers:
                  type: array
                  description: List of reviewers to add
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Identity ID of the reviewer
                workItemRefs:
                  type: array
                  description: Work items to link to the pull request
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Work item ID
                      url:
                        type: string
                        description: Work item URL
      responses:
        '201':
          description: Pull request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitPullRequest'
        '400':
          description: Bad request - invalid branch names or parameters
        '401':
          description: Unauthorized
        '404':
          description: Repository not found
        '409':
          description: Conflict - an active pull request already exists for the same source and target branches
  /git/repositories/{repositoryId}/pullrequests/{pullRequestId}:
    get:
      operationId: pullRequests_get
      summary: Azure Repos Get a pull request
      description: Retrieve a specific pull request by its ID. Returns full pull request details including status, reviewers, merge status, source and target branches, and linked work items.
      tags:
      - Pull Requests
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      - $ref: '#/components/parameters/pullRequestId'
      responses:
        '200':
          description: Successfully retrieved pull request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitPullRequest'
        '401':
          description: Unauthorized
        '404':
          description: Pull request or repository not found
    patch:
      operationId: pullRequests_update
      summary: Azure Repos Update a pull request
      description: Update properties of an existing pull request such as title, description, status (to abandon or reactivate), auto-complete settings, and completion options including merge strategy.
      tags:
      - Pull Requests
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      - $ref: '#/components/parameters/pullRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Updated title
                description:
                  type: string
                  description: Updated description
                status:
                  type: string
                  enum:
                  - active
                  - abandoned
                  - completed
                  description: Set to abandoned to close, completed to merge, or active to reactivate
                targetRefName:
                  type: string
                  description: Updated target branch
                autoCompleteSetBy:
                  type: object
                  description: Set to enable auto-complete. Set to empty object to disable.
                  properties:
                    id:
                      type: string
                      format: uuid
                completionOptions:
                  $ref: '#/components/schemas/GitPullRequestCompletionOptions'
      responses:
        '200':
          description: Pull request updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitPullRequest'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Pull request or repository not found
        '409':
          description: Conflict - merge conflicts exist
  /git/repositories/{repositoryId}/pullrequests/{pullRequestId}/commits:
    get:
      operationId: pullRequestCommits_list
      summary: Azure Repos List pull request commits
      description: Retrieve the list of commits associated with a pull request. Returns commits from the source branch that are not yet in the target branch.
      tags:
      - Pull Requests
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      - $ref: '#/components/parameters/pullRequestId'
      responses:
        '200':
          description: Successfully retrieved commits
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/GitCommitRef'
        '401':
          description: Unauthorized
        '404':
          description: Pull request or repository not found
components:
  schemas:
    GitRepository:
      type: object
      description: Represents a Git repository in Azure DevOps, including its metadata, URLs, project reference, and configuration such as default branch.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the repository
        name:
          type: string
          description: Name of the repository
        url:
          type: string
          format: uri
          description: REST API URL for the repository
        project:
          $ref: '#/components/schemas/TeamProjectReference'
        defaultBranch:
          type: string
          description: Default branch reference (e.g., refs/heads/main)
        remoteUrl:
          type: string
          format: uri
          description: HTTPS clone URL for the repository
        sshUrl:
          type: string
          description: SSH clone URL for the repository
        webUrl:
          type: string
          format: uri
          description: Web URL to browse the repository in the Azure DevOps portal
        size:
          type: integer
          format: int64
          description: Compressed size of the repository in bytes
        isFork:
          type: boolean
          description: True if the repository was created as a fork
        isDisabled:
          type: boolean
          description: True if the repository is disabled
        isInMaintenance:
          type: boolean
          description: True if the repository is in maintenance mode
        parentRepository:
          $ref: '#/components/schemas/GitRepositoryRef'
        _links:
          type: object
          description: HAL reference links
          additionalProperties: true
    TeamProjectReference:
      type: object
      description: Shallow reference to an Azure DevOps team project
      properties:
        id:
          type: string
          format: uuid
          description: Project ID
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description
        url:
          type: string
          format: uri
          description: REST API URL for the project
        state:
          type: string
          enum:
          - deleting
          - new
          - wellFormed
          - createPending
          - all
          - unchanged
          - deleted
          description: Current state of the project
        visibility:
          type: string
          enum:
          - private
          - public
          description: Visibility of the project
        revision:
          type: integer
          format: int64
          description: Project revision number
        lastUpdateTime:
          type: string
          format: date-time
          description: Last update time
    GitPullRequest:
      type: object
      description: Represents all the data associated with a pull request including status, branches, reviewers, merge state, and linked work items.
      properties:
        pullRequestId:
          type: integer
          format: int32
          description: Unique ID of the pull request
        codeReviewId:
          type: integer
          format: int32
          description: Code review ID used internally
        status:
          type: string
          enum:
          - notSet
          - active
          - abandoned
          - completed
          - all
          description: Current status of the pull request
        title:
          type: string
          description: Title of the pull request
        description:
          type: string
          description: Description of the pull request
        sourceRefName:
          type: string
          description: Name of the source branch (e.g., refs/heads/feature-branch)
        targetRefName:
          type: string
          description: Name of the target branch (e.g., refs/heads/main)
        createdBy:
          $ref: '#/components/schemas/IdentityRef'
        creationDate:
          type: string
          format: date-time
          description: Date the pull request was created
        closedDate:
          type: string
          format: date-time
          description: Date the pull request was closed
        closedBy:
          $ref: '#/components/schemas/IdentityRef'
        isDraft:
          type: boolean
          description: Whether this is a draft pull request
        mergeStatus:
          type: string
          enum:
          - notSet
          - queued
          - conflicts
          - succeeded
          - rejectedByPolicy
          - failure
          description: Current merge status
        mergeId:
          type: string
          format: uuid
          description: ID of the merge job
        mergeFailureMessage:
          type: string
          description: Message describing merge failure if applicable
        mergeFailureType:
          type: string
          enum:
          - none
          - unknown
          - caseSensitive
          - objectTooLarge
          description: Type of merge failure
        lastMergeSourceCommit:
          $ref: '#/components/schemas/GitCommitRef'
        lastMergeTargetCommit:
          $ref: '#/components/schemas/GitCommitRef'
        lastMergeCommit:
          $ref: '#/components/schemas/GitCommitRef'
        reviewers:
          type: array
          items:
            $ref: '#/components/schemas/IdentityRefWithVote'
          description: List of reviewers with their vote status
        repository:
          $ref: '#/components/schemas/GitRepository'
        commits:
          type: array
          items:
            $ref: '#/components/schemas/GitCommitRef'
          description: Commits included in the pull request
        completionOptions:
          $ref: '#/components/schemas/GitPullRequestCompletionOptions'
        completionQueueTime:
          type: string
          format: date-time
          description: Time the PR entered the completion queue
        autoCompleteSetBy:
          $ref: '#/components/schemas/IdentityRef'
        supportsIterations:
          type: boolean
          description: Whether the PR supports multiple iterations
        forkSource:
          $ref: '#/components/schemas/GitRepositoryRef'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/WebApiTagDefinition'
          description: Labels associated with the pull request
        workItemRefs:
          type: array
          items:
            $ref: '#/components/schemas/ResourceRef'
          description: Linked work items
        url:
          type: string
          format: uri
          description: REST API URL for this pull request
        artifactId:
          type: string
          description: Artifact ID in format vstfs:///Git/PullRequestId/{projectId}/{repoId}/{prId}
        _links:
          type: object
          additionalProperties: true
    GitUserDate:
      type: object
      description: User info and date for Git operations
      properties:
        name:
          type: string
          description: Name of the user
        email:
          type: string
          format: email
          description: Email address of the user
        date:
          type: string
          format: date-time
          description: Date of the Git operation
        imageUrl:
          type: string
          format: uri
          description: Avatar URL for the user
    GitStatus:
      type: object
      description: Status metadata posted by a service or extension against a commit or pull request, such as build results or policy checks.
      properties:
        id:
          type: integer
          format: int32
          description: Status identifier
        state:
          type: string
          enum:
          - notSet
          - pending
          - succeeded
          - failed
          - error
          - notApplicable
          description: State of the status
        description:
          type: string
          description: Status description
        context:
          type: object
          properties:
            name:
              type: string
              description: Name of the status context
            genre:
              type: string
              description: Genre of the status
        targetUrl:
          type: string
          format: uri
          description: URL with status details
        createdBy:
          $ref: '#/components/schemas/IdentityRef'
        creationDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
    WebApiTagDefinition:
      type: object
      description: Tag definition for pull request labels
      properties:
        id:
          type: string
          format: uuid
          description: Tag ID
        name:
          type: string
          description: Tag name
        active:
          type: boolean
          description: Whether the tag is active
        url:
          type: string
          format: uri
          description: REST API URL for the tag
    GitRepositoryRef:
      type: object
      description: Shallow reference to a Git repository
      properties:
        id:
          type: string
          format: uuid
          description: Repository ID
        name:
          type: string
          description: Repository name
        url:
          type: string
          format: uri
          description: REST API URL
        project:
          $ref: '#/components/schemas/TeamProjectReference'
        isFork:
          type: boolean
          description: True if the repository was created as a fork
        remoteUrl:
          type: string
          description: HTTPS clone URL
        sshUrl:
          type: string
          description: SSH clone URL
        collection:
          $ref: '#/components/schemas/TeamProjectCollectionReference'
    IdentityRefWithVote:
      type: object
      description: Identity information including a vote on a pull request. Vote values are 10 (approved), 5 (approved with suggestions), 0 (no vote), -5 (waiting for author), -10 (rejected).
      allOf:
      - $ref: '#/components/schemas/IdentityRef'
      - type: object
        properties:
          vote:
            type: integer
            format: int16
            description: 'Vote value: 10=approved, 5=approved with suggestions, 0=no vote, -5=waiting for author, -10=rejected'
          reviewerUrl:
            type: string
            format: uri
            description: URL to retrieve reviewer information
          hasDeclined:
            type: boolean
            description: Whether the reviewer has declined to review
          isFlagged:
            type: boolean
            description: Whether the reviewer is flagged for attention
          isRequired:
            type: boolean
            description: Whether this is a required reviewer
          votedFor:
            type: array
            items:
              $ref: '#/components/schemas/IdentityRefWithVote'
            description: Groups or teams this reviewer contributed to
    GitPullRequestCompletionOptions:
      type: object
      description: Options that control how the pull request is completed and merged.
      properties:
        mergeCommitMessage:
          type: string
          description: Commit message for the merge commit
        mergeStrategy:
          type: string
          enum:
          - noFastForward
          - squash
          - rebase
          - rebaseMerge
          description: Merge strategy to use. NoFastForward creates a merge commit, squash creates a single commit, rebase replays commits.
        deleteSourceBranch:
          type: boolean
          description: Delete the source branch after merge
        bypassPolicy:
          type: boolean
          description: Bypass branch policies during completion
        bypassReason:
          type: string
          description: Reason for bypassing policies
        transitionWorkItems:
          type: boolean
          description: Transition linked work items to the next state on completion
        squashMerge:
          type: boolean
          description: Deprecated. Use mergeStrategy instead.
        autoCompleteIgnoreConfigIds:
          type: array
          items:
            type: integer
            format: int32
          description: Policy configuration IDs that auto-complete should not wait for
    GitChange:
      type: object
      description: Represents a change to an item in a commit
      properties:
        changeId:
          type: integer
          format: int32
          description: ID of the change within the group
        changeType:
          type: string
          enum:
          - add
          - edit
          - delete
          - rename
          - merge
          - lock
          - branch
          - rollback
          - none
          description: Type of change made to the item
        item:
          type: object
          description: The affected item
          properties:
            objectId:
              type: string
            originalObjectId:
              type: string
            gitObjectType:
              type: string
            commitId:
              type: string
            path:
              type: string
            url:
              type: string
        originalPath:
          type: string
          description: Original path if the item was renamed
        url:
          type: string
          description: URL to retrieve the item
    TeamProjectCollectionReference:
      type: object
      description: Reference to a Team Project Collection
      properties:
        id:
          type: string
          format: uuid
          description: Collection ID
        name:
          type: string
          description: Collection name
        url:
          type: string
          format: uri
          description: REST API URL for the collection
    IdentityRef:
      type: object
      description: Reference to an Azure DevOps identity (user or group)
      properties:
        id:
          type: string
          format: uuid
          description: Unique identity ID
        displayName:
          type: string
          description: Display name of the identity
        uniqueName:
          type: string
          description: Unique name (typically email)
        url:
          type: string
          format: uri
          description: REST API URL for this identity
        imageUrl:
          type: string
          format: uri
          description: URL to the identity's avatar image
        descriptor:
          type: string
          description: Graph descriptor for the identity
        isContainer:
          type: boolean
          description: Whether this identity is a group
    ResourceRef:
      type: object
      description: Generic reference to a resource
      properties:
        id:
          type: string
          description: Resource ID
        url:
          type: string
          format: uri
          description: Resource URL
    GitCommitRef:
      type: object
      description: Properties describing a Git commit and associated metadata including author, committer, message, and related resources.
      properties:
        commitId:
          type: string
          description: SHA-1 hash of the commit
        author:
          $ref: '#/components/schemas/GitUserDate'
        committer:
          $ref: '#/components/schemas/GitUserDate'
        comment:
          type: string
          description: Commit message
        commentTruncated:
          type: boolean
          description: Whether the comment was truncated
        changeCounts:
          type: object
          description: Counts of change types in the commit
          additionalProperties:
            type: integer
        changes:
          type: array
          items:
            $ref: '#/components/schemas/GitChange'
          description: List of changes in the commit
        parents:
          type: array
          items:
            type: string
          description: SHA-1 hashes of parent commits
        url:
          type: string
          format: uri
          description: REST API URL for this commit
        remoteUrl:
          type: string
          format: uri
          description: Web URL to view the commit
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/GitStatus'
          description: Status checks posted against this commit
        workItems:
          type: array
          items:
            $ref: '#/components/schemas/ResourceRef'
          description: Linked work items
        push:
          type: object
          description: Push that included this commit
          properties:
            pushId:
              type: integer
              format: int32
            date:
              type: string
              format: date-time
            pushedBy:
              $ref: '#/components/schemas/IdentityRef'
            url:
              type: string
              format: uri
  parameters:
    repositoryId:
      name: repositoryId
      in: path
      required: true
      description: The ID or name of the repository
      schema:
        type: string
    pullRequestId:
      name: pullRequestId
      in: path
      required: true
      description: ID of the pull request
      schema:
        type: integer
        format: int32
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow for Azure DevOps Services. Requires the vso.code scope for read operations and vso.code_write for write operations.
      flows:
        authorizationCode:
          authorizationUrl: https://app.vssps.visualstudio.com/oauth2/authorize
          tokenUrl: https://app.vssps.visualstudio.com/oauth2/token
          scopes:
            vso.code: Read source code and metadata about commits, changesets, branches, and other version control artifacts
            vso.code_write: Read, create, and manage pull requests and code
            vso.code_manage: Read, create, manage, and delete repositories and branches
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using a Personal Access Token (PAT). Use any string for the username and the PAT as the password.
externalDocs:
  description: Azure DevOps Git REST API Reference
  url: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/?view=azure-devops-rest-7.1