GitLab Storage moves API

openapi: 3.2.0
info:
  title: GitLab REST Storage moves 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: Storage moves
  description: 'Use this API to schedule and track repository storage moves

    for groups, projects, and snippets. Project moves cover wiki and design repositories, and group

    moves cover group wikis. Moving repositories

    can help you migrate to Gitaly Cluster (Praefect).


    To ensure data integrity, GitLab places the group, project, or snippet in a temporary read-only

    state for the duration of the move. During this time, users receive this message if they try to

    push new commits:


    ```plaintext

    The repository is temporarily read-only. Please try again later.

    ```


    This API requires you to authenticate yourself as an administrator.


    ## States


    As GitLab processes a storage move, it transitions through different states. Values of `state` are:


    - `initial`: The record has been created, but the background job has not yet been scheduled.

    - `scheduled`: The background job has been scheduled.

    - `started`: The repositories are being copied to the destination storage.

    - `replicated`: The repositories have been moved.

    - `failed`: The repositories failed to copy, or the checksums did not match.

    - `finished`: The repositories have been moved, and the repositories on the source storage have been deleted.

    - `cleanup failed`: The repositories have been moved, but the repositories on the source storage could not be deleted.'
  x-displayName: Storage moves
  externalDocs:
    url: https://docs.gitlab.com/api/group_repository_storage_moves/
paths:
  /api/v4/group_repository_storage_moves:
    get:
      operationId: getApiV4GroupRepositoryStorageMoves
      summary: List all group repository storage moves
      description: Lists all group repository storage moves for an instance.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesGroupsRepositoryStorageMove'
        '400':
          description: Bad Request
      parameters:
      - 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
      x-gitlab-tier: premium
    post:
      operationId: postApiV4GroupRepositoryStorageMoves
      summary: Create group repository storage moves for a storage shard
      description: Creates repository storage moves for all groups on a specified storage shard.
      tags:
      - Storage moves
      responses:
        '202':
          description: 202 Accepted
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GroupRepositoryStorageMovesRequest'
      x-gitlab-tier: premium
  /api/v4/group_repository_storage_moves/{repository_storage_move_id}:
    get:
      operationId: getApiV4GroupRepositoryStorageMovesRepositoryStorageMoveId
      summary: Retrieve a group repository storage move
      description: Retrieves a specified group repository storage move. This feature was introduced in GitLab 13.9.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGroupsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: repository_storage_move_id
        required: true
        description: ID of the group repository storage move.
        schema:
          type: integer
        in: path
      x-gitlab-tier: premium
  /api/v4/groups/{id}/repository_storage_moves:
    get:
      operationId: getApiV4GroupsIdRepositoryStorageMoves
      summary: List all repository storage moves for a group
      description: Lists all repository storage moves for a specified group.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesGroupsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        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
      x-gitlab-tier: premium
    post:
      operationId: postApiV4GroupsIdRepositoryStorageMoves
      summary: Create a group repository storage move
      description: Creates a group repository storage move for a specified group. This operation moves only group wiki repositories and does not move repositories for projects in a group.
      tags:
      - Storage moves
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGroupsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GroupsIdRepositoryStorageMovesRequest'
      x-gitlab-tier: premium
  /api/v4/groups/{id}/repository_storage_moves/{repository_storage_move_id}:
    get:
      operationId: getApiV4GroupsIdRepositoryStorageMovesRepositoryStorageMoveId
      summary: Retrieve a repository storage move for a group
      description: Retrieves a specified repository storage move for a group. This feature was introduced in GitLab 13.9.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGroupsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: repository_storage_move_id
        required: true
        description: ID of the group repository storage move.
        schema:
          type: integer
        in: path
      x-gitlab-tier: premium
  /api/v4/snippet_repository_storage_moves:
    get:
      operationId: getApiV4SnippetRepositoryStorageMoves
      summary: List all snippet repository storage moves
      description: Lists all snippet repository storage moves. By default, `GET` requests return 20 results at a time because the API results are paginated.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesSnippetsRepositoryStorageMove'
        '400':
          description: Bad Request
      parameters:
      - 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
    post:
      operationId: postApiV4SnippetRepositoryStorageMoves
      summary: Schedule repository storage moves for all snippets on a storage shard
      description: Schedules repository storage moves for each snippet repository stored on the source storage shard. This endpoint migrates all snippets at once.
      tags:
      - Storage moves
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4SnippetRepositoryStorageMovesRequest'
  /api/v4/snippet_repository_storage_moves/{repository_storage_move_id}:
    get:
      operationId: getApiV4SnippetRepositoryStorageMovesRepositoryStorageMoveId
      summary: Retrieve a snippet repository storage move
      description: Retrieves a specified snippet repository storage move.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSnippetsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: repository_storage_move_id
        required: true
        description: ID of the snippet repository storage move.
        schema:
          type: integer
        in: path
  /api/v4/snippets/{id}/repository_storage_moves:
    get:
      operationId: getApiV4SnippetsIdRepositoryStorageMoves
      summary: List all repository storage moves for a snippet
      description: Lists all repository storage moves for a specified snippet. By default, `GET` requests return 20 results at a time because the API results are paginated.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesSnippetsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the snippet.
        schema:
          type: string
        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
    post:
      operationId: postApiV4SnippetsIdRepositoryStorageMoves
      summary: Schedule a repository storage move for a snippet
      description: Schedules a repository storage move for a specified snippet.
      tags:
      - Storage moves
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSnippetsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the snippet.
        schema:
          type: string
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4SnippetsIdRepositoryStorageMovesRequest'
  /api/v4/snippets/{id}/repository_storage_moves/{repository_storage_move_id}:
    get:
      operationId: getApiV4SnippetsIdRepositoryStorageMovesRepositoryStorageMoveId
      summary: Retrieve a repository storage move for a snippet
      description: Retrieves a repository storage move for a specified snippet.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSnippetsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the snippet.
        schema:
          type: string
        in: path
      - name: repository_storage_move_id
        required: true
        description: ID of the snippet repository storage move.
        schema:
          type: integer
        in: path
  /api/v4/project_repository_storage_moves:
    get:
      operationId: getApiV4ProjectRepositoryStorageMoves
      summary: List all project repository storage moves
      description: Lists all project repository storage moves.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesProjectsRepositoryStorageMove'
        '400':
          description: Bad Request
      parameters:
      - 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
    post:
      operationId: postApiV4ProjectRepositoryStorageMoves
      summary: Create repository storage moves for all projects on a storage shard
      description: Creates repository storage moves for each project repository stored on the source storage shard. This endpoint migrates all projects at once.
      tags:
      - Storage moves
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectRepositoryStorageMovesRequest'
  /api/v4/project_repository_storage_moves/{repository_storage_move_id}:
    get:
      operationId: getApiV4ProjectRepositoryStorageMovesRepositoryStorageMoveId
      summary: Retrieve a project repository storage move
      description: Retrieves a specified project repository storage move.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesProjectsRepositoryStorageMove'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: repository_storage_move_id
        required: true
        description: ID of the project repository storage move.
        schema:
          type: integer
        in: path
  /api/v4/projects/{id}/repository_storage_moves:
    get:
      operationId: getApiV4ProjectsIdRepositoryStorageMoves
      summary: List all repository storage moves for a project
      description: Lists all repository storage moves for a project.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesProjectsRepositoryStorageMove'
        '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: 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
    post:
      operationId: postApiV4ProjectsIdRepositoryStorageMoves
      summary: Create a repository storage move for a project
      description: Creates a repository storage move for a specified project.
      tags:
      - Storage moves
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesProjectsRepositoryStorageMove'
        '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
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdRepositoryStorageMovesRequest'
  /api/v4/projects/{id}/repository_storage_moves/{repository_storage_move_id}:
    get:
      operationId: getApiV4ProjectsIdRepositoryStorageMovesRepositoryStorageMoveId
      summary: Retrieve a repository storage move for a project
      description: Retrieves a specified repository storage move for a project.
      tags:
      - Storage moves
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesProjectsRepositoryStorageMove'
        '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: repository_storage_move_id
        required: true
        description: ID of the project repository storage move.
        schema:
          type: integer
        in: path
components:
  schemas:
    APIEntitiesBasicSnippet:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        title:
          type: string
          example: test
        description:
          type: string
          example: Ruby test snippet
        visibility:
          type: string
          example: public
        author:
          $ref: '#/components/schemas/APIEntitiesUserBasic'
        created_at:
          type: string
          format: date-time
          example: '2012-06-28T10:52:04Z'
        updated_at:
          type: string
          format: date-time
          example: '2012-06-28T10:52:04Z'
        project_id:
          type: integer
          format: int64
          example: 1
        web_url:
          type: string
          example: http://example.com/example/example/snippets/1
        raw_url:
          type: string
          example: http://example.com/example/example/snippets/1/raw
        ssh_url_to_repo:
          type: string
          example: ssh://user@gitlab.example.com/snippets/65.git
        http_url_to_repo:
          type: string
          example: https://gitlab.example.com/snippets/65.git
    APIEntitiesSnippetsRepositoryStorageMove:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        created_at:
          type: string
          format: date-time
          example: '2020-05-07T04:27:17.234Z'
        state:
          type: string
          example: scheduled
        source_storage_name:
          type: string
          example: default
        destination_storage_name:
          type: string
          example: storage1
        error_message:
          type: string
          example: Failed to move repository
        snippet:
          $ref: '#/components/schemas/APIEntitiesBasicSnippet'
    postApiV4ProjectRepositoryStorageMovesRequest:
      type: object
      properties:
        source_storage_name:
          type: string
          description: Name of the source storage shard.
          minLength: 1
        destination_storage_name:
          type:
          - string
          - 'null'
          description: Name of the destination storage shard. If not provided, the storage is selected [automatically based on storage weights](https://docs.gitlab.com/administration/repository_storage_paths/#configure-where-new-repositories-are-stored).
      required:
      - source_storage_name
    APIEntitiesCustomAttribute:
      type: object
      properties:
        key:
          type: string
          example: foo
        value:
          type: string
          example: bar
    APIEntitiesBasicGroupDetails:
      type: object
      properties:
        id:
          type: integer
          format: int64
        web_url:
          type: string
          example: http://gitlab.example.com/groups/diaspora
        name:
          type: string
          example: Diaspora
    postApiV4ProjectsIdRepositoryStorageMovesRequest:
      type: object
      properties:
        destination_storage_name:
          type:
          - string
          - 'null'
          description: Name of the destination storage shard. If not provided, the storage is selected [automatically based on storage weights](https://docs.gitlab.com/administration/repository_storage_paths/#configure-where-new-repositories-are-stored).
    postApiV4SnippetsIdRepositoryStorageMovesRequest:
      type: object
      properties:
        destination_storage_name:
          type:
          - string
          - 'null'
          description: Name of the destination storage shard. If not provided, the storage is selected [automatically based on storage weights](https://docs.gitlab.com/administration/repository_storage_paths/#configure-where-new-repositories-are-stored).
    postApiV4GroupsIdRepositoryStorageMovesRequest:
      type: object
      properties:
        destination_storage_name:
          type:
          - string
          - 'null'
          description: Name of the destination storage shard. If omitted, the storage is selected [automatically based on storage weights](https://docs.gitlab.com/administration/repository_storage_paths/#configure-where-new-repositories-are-stored).
    APIEntitiesProjectsRepositoryStorageMove:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        created_at:
          type: string
          format: date-time
          example: '2020-05-07T04:27:17.234Z'
        state:
          type: string
          example: scheduled
        source_storage_name:
          type: string
          example: default
        destination_storage_name:
          type: string
          example: storage1
        error_message:
          type: string
          example: Failed to move repository
        project:
          $ref: '#/components/schemas/APIEntitiesProjectIdentity'
    postApiV4GroupRepositoryStorageMovesRequest:
      type: object
      properties:
        source_storage_name:
          type: string
          description: Name of the source storage shard.
          minLength: 1
        destination_storage_name:
          type:
          - string
          - 'null'
          description: Name of the destination storage shard. If omitted, the storage is selected [automatically based on storage weights](https://docs.gitlab.com/administration/repository_storage_paths/#configure-where-new-repositories-are-stored).
      required:
      - source_storage_name
    APIEntitiesGroupsRepositoryStorageMove:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        created_at:
          type: string
          format: date-time
          example: '2020-05-07T04:27:17.234Z'
        state:
          type: string
          example: scheduled
        source_storage_name:
          type: string
          example: default
        destination_storage_name:
          type: string
          example: storage1
        error_message:
          type: string
          example: Failed to move repository
        group:
          $ref: '#/components/schemas/APIEntitiesBasicGroupDetails'
    postApiV4SnippetRepositoryStorageMovesRequest:
      type: object
      properties:
        source_storage_name:
          type: string
          description: Name of the source storage shard.
          minLength: 1
        destination_storage_name:
          type:
          - string
          - 'null'
          description: Name of the destination storage shard. If not provided, the storage is selected [automatically based on storage weights](https://docs.gitlab.com/administration/repository_storage_paths/#configure-where-new-repositories-are-stored).
      required:
      - source_storage_name
    APIEntitiesUserBasic:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        username:
          type: string
          example: admin
        public_email:
          type: string
          example: john@example.com
        name:
          type: string
          example: Administrator
        state:
          type: string
          example: active
        locked:
          type: boolean
        avatar_url:
          type: string
          example: https://gravatar.com/avatar/1
        avatar_path:
          type: string
          example: /user/avatar/28/The-Big-Lebowski-400-400.png
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesCustomAttribute'
        web_url:
          type: string
          example: https://gitlab.example.com/root
    APIEntitiesProjectIdentity:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        description:
          type: string
          example: desc
        name:
          type: string
          example: project1
        name_with_namespace:
          type: string
          example: John Doe / project1
        path:
          type: string
          example: project1
        path_with_namespace:
          type: string
          example: namespace1/project1
        created_at:
          type: string
          format: date-time
          example: '2020-05-07T04:27:17.016Z'
  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