Azure Repos Repositories API

openapi: 3.1.0
info:
  title: Azure Repos Git Commits Repositories 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: Repositories
  description: Operations for managing Git repositories including creating, listing, updating, and deleting repositories within a project.
paths:
  /git/repositories:
    get:
      operationId: repositories_list
      summary: Azure Repos List repositories
      description: Retrieve all Git repositories in the specified project. Each repository includes its ID, name, default branch, remote URL, SSH URL, and web URL. Optionally include reference links and hidden repositories.
      tags:
      - Repositories
      parameters:
      - $ref: '#/components/parameters/includeLinks'
      - name: includeAllUrls
        in: query
        description: Set to true to include all remote URLs in the response. Defaults to false.
        schema:
          type: boolean
      - name: includeHidden
        in: query
        description: Set to true to include hidden repositories. Defaults to false.
        schema:
          type: boolean
      responses:
        '200':
          description: Successfully retrieved list of repositories
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of repositories returned
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/GitRepository'
        '401':
          description: Unauthorized - authentication credentials are missing or invalid
        '404':
          description: Project not found
    post:
      operationId: repositories_create
      summary: Azure Repos Create a repository
      description: Create a new Git repository in the specified project. Provide the repository name and optionally a parent repository for forking.
      tags:
      - Repositories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Name of the new repository
                project:
                  type: object
                  description: Project reference for the new repository
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: Project ID
                parentRepository:
                  type: object
                  description: Parent repository reference for creating a fork
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: ID of the parent repository to fork from
                    project:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
      responses:
        '201':
          description: Repository created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitRepository'
        '400':
          description: Bad request - invalid repository name or parameters
        '401':
          description: Unauthorized
        '409':
          description: Conflict - repository with the same name already exists
  /git/repositories/{repositoryId}:
    get:
      operationId: repositories_get
      summary: Azure Repos Get a repository
      description: Retrieve a specific Git repository by its ID or name. Returns full repository details including default branch, clone URLs, project reference, and size.
      tags:
      - Repositories
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      responses:
        '200':
          description: Successfully retrieved repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitRepository'
        '401':
          description: Unauthorized
        '404':
          description: Repository not found
    patch:
      operationId: repositories_update
      summary: Azure Repos Update a repository
      description: Update a Git repository with a new name or a new default branch. Only the fields provided in the request body are updated.
      tags:
      - Repositories
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New name for the repository
                defaultBranch:
                  type: string
                  description: New default branch reference (e.g., refs/heads/main)
      responses:
        '200':
          description: Repository updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitRepository'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Repository not found
    delete:
      operationId: repositories_delete
      summary: Azure Repos Delete a repository
      description: Delete a Git repository from the project. This operation is irreversible and removes all branches, commits, and pull requests associated with the repository.
      tags:
      - Repositories
      parameters:
      - $ref: '#/components/parameters/repositoryId'
      responses:
        '204':
          description: Repository deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: 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
    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'
    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
  parameters:
    includeLinks:
      name: includeLinks
      in: query
      description: Include reference links in the response
      schema:
        type: boolean
    repositoryId:
      name: repositoryId
      in: path
      required: true
      description: The ID or name of the repository
      schema:
        type: string
  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