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