GitLab Branches API

openapi: 3.2.0
info:
  title: GitLab REST Branches API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Branches
  description: 'Use this API to manage Git branches.


    To change the branch protections configured for a project, use the protected branches API.'
  x-displayName: Branches
  externalDocs:
    url: https://docs.gitlab.com/api/branches/
paths:
  /api/v4/projects/{id}/repository/branches:
    get:
      operationId: getApiV4ProjectsIdRepositoryBranches
      summary: List all repository branches
      description: Lists all repository branches from a specified project, sorted alphabetically by name. Search by name, or use regular expressions to find specific branch patterns. Returns detailed information about the branch, including its protection status, merge status, and commit details.
      tags:
      - Branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesBranch'
        '404':
          description: 404 Project Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      - name: search
        required: false
        description: Return branches containing the search string. Use `^term` to find branches that begin with `term`, and `term$` to find branches that end with `term`.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: regex
        required: false
        description: Return branches with names matching an [RE2](https://github.com/google/re2/wiki/Syntax) regular expression. Cannot be used together with `search`.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: sort
        required: false
        description: Sort results by the specified field and direction.
        schema:
          type:
          - string
          - 'null'
          enum:
          - name_asc
          - updated_asc
          - updated_desc
          - null
        in: query
      - name: page_token
        required: false
        description: Name of the branch to start the pagination from. Used for keyset pagination.
        schema:
          type:
          - string
          - 'null'
        in: query
    post:
      operationId: postApiV4ProjectsIdRepositoryBranches
      summary: Create a repository branch
      description: Creates a branch in the repository.
      tags:
      - Branches
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBranch'
        '400':
          description: Branch already exists
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdRepositoryBranchesRequest'
  /api/v4/projects/{id}/repository/branches/{branch}:
    head:
      operationId: headApiV4ProjectsIdRepositoryBranchesBranch
      summary: Check if a branch exists
      description: Checks whether a branch exists in the repository, without returning the branch.
      tags:
      - Branches
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: branch
        required: true
        description: Name of the branch.
        schema:
          type: string
        in: path
    get:
      operationId: getApiV4ProjectsIdRepositoryBranchesBranch
      summary: Retrieve a repository branch
      description: Retrieves a specified project repository branch.
      tags:
      - Branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBranch'
        '404':
          description: Project Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: branch
        required: true
        description: Name of the branch.
        schema:
          type: string
        in: path
    delete:
      operationId: deleteApiV4ProjectsIdRepositoryBranchesBranch
      summary: Delete a repository branch
      description: Deletes a specified branch from the repository.
      tags:
      - Branches
      responses:
        '204':
          description: No Content
        '404':
          description: Branch Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: branch
        required: true
        description: Name of the branch.
        schema:
          type: string
        in: path
  /api/v4/projects/{id}/repository/branches/{branch}/protect:
    put:
      operationId: putApiV4ProjectsIdRepositoryBranchesBranchProtect
      summary: Protect a single branch
      description: Protects a single branch, or updates its protection if it is already protected. Only users with the Maintainer role can push or merge unless `developers_can_push` or `developers_can_merge` is `true`.
      tags:
      - Branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBranch'
        '404':
          description: 404 Branch Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: branch
        required: true
        description: Name of the branch.
        schema:
          type: string
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4ProjectsIdRepositoryBranchesBranchProtectRequest'
  /api/v4/projects/{id}/repository/branches/{branch}/unprotect:
    put:
      operationId: putApiV4ProjectsIdRepositoryBranchesBranchUnprotect
      summary: Unprotect a single branch
      description: Removes the protection from a single protected branch.
      tags:
      - Branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBranch'
        '404':
          description: 404 Branch Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: branch
        required: true
        description: Name of the branch.
        schema:
          type: string
        in: path
  /api/v4/projects/{id}/repository/merged_branches:
    delete:
      operationId: deleteApiV4ProjectsIdRepositoryMergedBranches
      summary: Delete all merged branches
      description: Deletes all branches that are merged into the default branch for a project.
      tags:
      - Branches
      responses:
        '202':
          description: 202 Accepted
        '404':
          description: 404 Project Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
components:
  schemas:
    APIEntitiesCommit:
      type: object
      properties:
        id:
          type: string
          example: 2695effb5807a22ff3d138d593fd856244e155e7
        short_id:
          type: string
          example: 2695effb
        created_at:
          type: string
          format: date-time
          example: '2017-07-26T11:08:53.000+02:00'
        parent_ids:
          type: array
          example:
          - 2a4b78934375d7f53875269ffd4f45fd83a84ebe
          items:
            type: string
        title:
          type: string
          example: Initial commit
        message:
          type: string
          example: Initial commit
        author_name:
          type: string
          example: John Smith
        author_email:
          type: string
          example: john@example.com
        authored_date:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        committer_name:
          type: string
          example: Jack Smith
        committer_email:
          type: string
          example: jack@example.com
        committed_date:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        trailers:
          type: object
          example:
            Merged-By: Jane Doe janedoe@gitlab.com
        extended_trailers:
          type: object
          example:
            Signed-off-by:
            - John Doe <johndoe@gitlab.com>
            - Jane Doe <janedoe@gitlab.com>
        web_url:
          type: string
          example: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
    APIEntitiesBranch:
      type: object
      properties:
        name:
          type: string
          example: master
        commit:
          $ref: '#/components/schemas/APIEntitiesCommit'
        merged:
          type: boolean
          example: true
        protected:
          type: boolean
          example: true
        developers_can_push:
          type: boolean
          example: true
        developers_can_merge:
          type: boolean
          example: true
        can_push:
          type: boolean
          example: true
        default:
          type: boolean
          example: true
        web_url:
          type: string
          example: https://gitlab.example.com/Commit921/the-dude/-/tree/master
    postApiV4ProjectsIdRepositoryBranchesRequest:
      type: object
      properties:
        branch:
          type:
          - string
          - 'null'
          description: Name of the branch.
        ref:
          type:
          - string
          - 'null'
          description: Branch name or commit SHA to create the branch from.
      required:
      - branch
      - ref
    putApiV4ProjectsIdRepositoryBranchesBranchProtectRequest:
      type: object
      properties:
        developers_can_push:
          type:
          - boolean
          - 'null'
          description: If `true`, allows developers to push to the branch.
        developers_can_merge:
          type:
          - boolean
          - 'null'
          description: If `true`, allows developers to merge to the branch.
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header