openapi: 3.1.0
info:
title: Azure DevOps Git Repositories API
description: >
REST API for managing Git repositories, branches, commits, pull requests,
and pushes in Azure Repos. Supports full programmatic control over source code
hosted in Azure DevOps, including creating and reviewing pull requests,
managing branches, and browsing repository content.
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
servers:
- url: https://dev.azure.com/{organization}/{project}/_apis
description: Azure DevOps Git 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: Commits
description: Operations for accessing commits and commit history
- name: Pull Requests
description: Operations for creating and managing pull requests
- name: Pushes
description: Operations for managing pushes and commits
- name: Refs
description: Operations for managing branches and tags (refs)
- name: Repositories
description: Operations for managing Git repositories
paths:
/git/repositories:
get:
operationId: repositories_list
summary: Azure DevOps List repositories
description: >
Returns a list of Git repositories in the project. Each repository includes
its ID, name, default branch, clone URL, and remote URL.
tags:
- Repositories
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: includeLinks
in: query
required: false
description: Whether to include _links in the response
schema:
type: boolean
- name: includeAllUrls
in: query
required: false
description: Whether to include all remote URLs (fetch and push)
schema:
type: boolean
- name: includeHidden
in: query
required: false
description: Whether to include hidden repositories
schema:
type: boolean
responses:
'200':
description: List of repositories returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitRepository'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: repositories_create
summary: Azure DevOps Create a repository
description: >
Creates a new Git repository in the project. Optionally can initialize the
repository with a README and specify its visibility. After creation, the
repository is empty unless a source URL is provided.
tags:
- Repositories
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: sourceRef
in: query
required: false
description: Initial branch name for the repository
schema:
type: string
requestBody:
required: true
description: Repository creation parameters
content:
application/json:
schema:
type: object
required:
- name
- project
properties:
name:
type: string
description: Name of the new repository
example: 'my-new-repo'
project:
type: object
description: Project in which to create the repository
required:
- id
properties:
id:
type: string
format: uuid
description: Project ID
parentRepository:
type: object
description: Fork this repository from a parent (optional)
properties:
id:
type: string
format: uuid
project:
type: object
properties:
id:
type: string
format: uuid
responses:
'201':
description: Repository created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitRepository'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/git/repositories/{repositoryId}:
get:
operationId: repositories_get
summary: Azure DevOps Get a repository
description: >
Returns detailed information about a specific Git repository, including
its default branch, clone URL, and project association. The repositoryId
can be either the GUID or the repository name.
tags:
- Repositories
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: includeParent
in: query
required: false
description: Whether to include the parent repository (for forks)
schema:
type: boolean
responses:
'200':
description: Repository returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitRepository'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: repositories_update
summary: Azure DevOps Update a repository
description: >
Updates properties of a repository such as its name or default branch.
Only the fields provided in the request body will be changed.
tags:
- Repositories
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
requestBody:
required: true
description: Repository properties to update
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: New name for the repository
defaultBranch:
type: string
description: New default branch (e.g., refs/heads/main)
isDisabled:
type: boolean
description: Whether to disable the repository
responses:
'200':
description: Repository updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitRepository'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: repositories_delete
summary: Azure DevOps Delete a repository
description: >
Permanently deletes a repository and all its contents. This action cannot
be undone. The repository and all pull requests, branches, and history
will be permanently removed.
tags:
- Repositories
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
responses:
'204':
description: Repository deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/refs:
get:
operationId: refs_list
summary: Azure DevOps List branches and refs
description: >
Returns a list of refs (branches and tags) for a repository. Supports
filtering by a prefix string (e.g., "heads/" for branches, "tags/" for tags).
tags:
- Refs
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: filter
in: query
required: false
description: Prefix filter for ref names (e.g., 'heads/' returns branches)
schema:
type: string
example: 'heads/'
- name: includeLinks
in: query
required: false
description: Whether to include _links
schema:
type: boolean
- name: includeStatuses
in: query
required: false
description: Whether to include commit status information
schema:
type: boolean
- name: includeMyBranches
in: query
required: false
description: Whether to prioritize branches created by the current user
schema:
type: boolean
- name: latestStatusesOnly
in: query
required: false
description: Return only the latest status for each ref
schema:
type: boolean
- name: $top
in: query
required: false
description: Maximum number of refs to return
schema:
type: integer
- name: continuationToken
in: query
required: false
description: Continuation token for paging
schema:
type: string
responses:
'200':
description: List of refs returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitRef'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/commits:
get:
operationId: commits_list
summary: Azure DevOps List commits
description: >
Returns a list of commits in a repository. Supports filtering by branch,
author, date range, file path, and commit message text. Results are
sorted by commit date (newest first by default).
tags:
- Commits
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: searchCriteria.itemVersion.version
in: query
required: false
description: Branch, tag, or commit SHA to start listing from
schema:
type: string
- name: searchCriteria.author
in: query
required: false
description: Filter by commit author name or email
schema:
type: string
- name: searchCriteria.fromDate
in: query
required: false
description: Return commits after this date
schema:
type: string
format: date-time
- name: searchCriteria.toDate
in: query
required: false
description: Return commits before this date
schema:
type: string
format: date-time
- name: searchCriteria.itemPath
in: query
required: false
description: Filter commits that touched this file or folder path
schema:
type: string
- name: searchCriteria.$top
in: query
required: false
description: Maximum number of commits to return
schema:
type: integer
- name: searchCriteria.$skip
in: query
required: false
description: Number of commits to skip (for pagination)
schema:
type: integer
responses:
'200':
description: List of commits returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitCommitRef'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/items:
get:
operationId: items_list
summary: Azure DevOps List repository items
description: >
Returns a list of items (files and folders) in the repository at a specified
path and version. Use this to browse the repository tree and download file
contents.
tags:
- Repositories
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: scopePath
in: query
required: false
description: Path to the folder or file to list
schema:
type: string
example: '/src'
- name: recursionLevel
in: query
required: false
description: How deep to recurse into subfolders
schema:
type: string
enum: [none, oneLevel, oneLevelPlusNestedEmptyFolders, full]
- name: includeContentMetadata
in: query
required: false
description: Whether to include content metadata (size, encoding) for files
schema:
type: boolean
- name: latestProcessedChange
in: query
required: false
description: Whether to include the latest commit that changed each item
schema:
type: boolean
- name: download
in: query
required: false
description: Whether to return file content as a download
schema:
type: boolean
- name: versionDescriptor.version
in: query
required: false
description: Branch, tag, or commit to retrieve items at
schema:
type: string
responses:
'200':
description: Repository items returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitItem'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/pullrequests:
get:
operationId: pullRequests_list
summary: Azure DevOps List pull requests
description: >
Returns a list of pull requests in a repository. Supports filtering by
status, target branch, source branch, creator, and reviewer.
tags:
- Pull Requests
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: searchCriteria.status
in: query
required: false
description: Filter pull requests by status
schema:
type: string
enum: [notSet, active, abandoned, completed, all]
- name: searchCriteria.targetRefName
in: query
required: false
description: Filter by target branch (e.g., refs/heads/main)
schema:
type: string
- name: searchCriteria.sourceRefName
in: query
required: false
description: Filter by source branch
schema:
type: string
- name: searchCriteria.creatorId
in: query
required: false
description: Filter pull requests by creator's user ID
schema:
type: string
format: uuid
- name: searchCriteria.reviewerId
in: query
required: false
description: Filter pull requests by reviewer's user ID
schema:
type: string
format: uuid
- name: $top
in: query
required: false
description: Maximum number of pull requests to return
schema:
type: integer
- name: $skip
in: query
required: false
description: Number of pull requests to skip (for pagination)
schema:
type: integer
responses:
'200':
description: List of pull requests returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitPullRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: pullRequests_create
summary: Azure DevOps Create a pull request
description: >
Creates a new pull request to merge changes from a source branch into a
target branch. Supports specifying reviewers, work item links, labels,
and whether to complete the PR automatically on all approvals.
tags:
- Pull Requests
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: supportsIterations
in: query
required: false
description: Whether the PR should support iterations (diff views)
schema:
type: boolean
requestBody:
required: true
description: Pull request creation parameters
content:
application/json:
schema:
$ref: '#/components/schemas/GitPullRequestCreateRequest'
example:
title: 'Add new login feature'
description: 'This PR adds the new OAuth 2.0 login flow'
sourceRefName: 'refs/heads/feature/login'
targetRefName: 'refs/heads/main'
reviewers:
- id: '8c8c7d32-6b1b-47f4-b2e9-30209d6d62be'
responses:
'201':
description: Pull request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitPullRequest'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/pullrequests/{pullRequestId}:
get:
operationId: pullRequests_get
summary: Azure DevOps Get a pull request
description: >
Returns detailed information about a specific pull request, including
its status, reviewers, commits, merge status, and associated work items.
tags:
- Pull Requests
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: pullRequestId
in: path
required: true
description: Numeric ID of the pull request
schema:
type: integer
- name: maxCommentLength
in: query
required: false
description: Maximum character count in returned comments
schema:
type: integer
- name: $skip
in: query
required: false
description: Number of items to skip in collections
schema:
type: integer
- name: $top
in: query
required: false
description: Maximum number of items in collections
schema:
type: integer
- name: includeCommits
in: query
required: false
description: Whether to include commit details
schema:
type: boolean
- name: includeWorkItemRefs
in: query
required: false
description: Whether to include linked work item references
schema:
type: boolean
responses:
'200':
description: Pull request returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitPullRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: pullRequests_update
summary: Azure DevOps Update a pull request
description: >
Updates a pull request. Use this to change the title, description, status
(abandon or complete), target branch, and auto-complete settings. To complete
a PR, set status to 'completed' and provide a lastMergeSourceCommit.
tags:
- Pull Requests
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: pullRequestId
in: path
required: true
description: Numeric ID of the pull request to update
schema:
type: integer
requestBody:
required: true
description: Pull request fields to update
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: New title for the pull request
description:
type: string
description: New description for the pull request
status:
type: string
description: New status for the pull request
enum: [notSet, active, abandoned, completed]
autoCompleteSetBy:
$ref: '#/components/schemas/IdentityRef'
targetRefName:
type: string
description: New target branch (only if not yet completed)
lastMergeSourceCommit:
type: object
description: Required when completing the PR - the head commit of the source branch
properties:
commitId:
type: string
completionOptions:
type: object
description: Options for completing the PR
properties:
deleteSourceBranch:
type: boolean
squashMerge:
type: boolean
mergeStrategy:
type: string
enum: [noFastForward, squash, rebase, rebaseMerge]
transitionWorkItems:
type: boolean
responses:
'200':
description: Pull request updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitPullRequest'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/pullrequests/{pullRequestId}/threads:
get:
operationId: pullRequests_listThreads
summary: Azure DevOps Get pull request threads
description: >
Returns all comment threads on a pull request, including code review comments
tied to specific file positions and general conversation threads.
tags:
- Pull Requests
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: pullRequestId
in: path
required: true
description: Numeric ID of the pull request
schema:
type: integer
- name: $top
in: query
required: false
description: Maximum number of threads to return
schema:
type: integer
- name: $skip
in: query
required: false
description: Number of threads to skip
schema:
type: integer
responses:
'200':
description: Pull request threads returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitPullRequestCommentThread'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: pullRequests_addComment
summary: Azure DevOps Add a pull request comment thread
description: >
Adds a new comment thread to a pull request. Threads can be general
comments or code review comments tied to a specific file and line number.
tags:
- Pull Requests
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: pullRequestId
in: path
required: true
description: Numeric ID of the pull request
schema:
type: integer
requestBody:
required: true
description: Comment thread to add to the pull request
content:
application/json:
schema:
$ref: '#/components/schemas/GitPullRequestCommentThreadCreateRequest'
example:
comments:
- parentCommentId: 0
content: 'Please add unit tests for this change'
commentType: text
status: active
responses:
'200':
description: Comment thread created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitPullRequestCommentThread'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/git/repositories/{repositoryId}/pushes:
get:
operationId: pushes_list
summary: Azure DevOps List pushes
description: >
Returns a list of pushes in a repository. Each push contains references
to the commits pushed and the branch or tag updated. Supports filtering
by date range and branch.
tags:
- Pushes
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
- name: $top
in: query
required: false
description: Maximum number of pushes to return
schema:
type: integer
- name: $skip
in: query
required: false
description: Number of pushes to skip
schema:
type: integer
- name: searchCriteria.fromDate
in: query
required: false
description: Return pushes from after this date
schema:
type: string
format: date-time
- name: searchCriteria.toDate
in: query
required: false
description: Return pushes before this date
schema:
type: string
format: date-time
- name: searchCriteria.refName
in: query
required: false
description: Filter by branch or ref name
schema:
type: string
- name: searchCriteria.pusherId
in: query
required: false
description: Filter pushes by user who pushed
schema:
type: string
format: uuid
responses:
'200':
description: List of pushes returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/GitPush'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: pushes_create
summary: Azure DevOps Create a push
description: >
Creates a new push to the repository. This can be used to create commits,
update branches, and modify repository contents programmatically. Requires
specifying the ref updates and commits with file changes.
tags:
- Pushes
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/RepositoryId'
requestBody:
required: true
description: Push data including commits and ref updates
content:
application/json:
schema:
$ref: '#/components/schemas/GitPushCreateRequest'
responses:
'201':
description: Push created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GitPush'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
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.
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']
RepositoryId:
name: repositoryId
in: path
required: true
description: GUID or name of the repository
schema:
type: string
responses:
BadRequest:
description: Bad request - invalid parameters or request body
content:
applicatio
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure-devops/refs/heads/main/openapi/azure-devops-git-api-openapi.yml