GitLab Imports API

openapi: 3.2.0
info:
  title: GitLab REST Imports 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: Imports
  description: 'Use this API to migrate groups and projects by using

    direct transfer, and to

    import repositories from external sources.


    Before migrating by direct transfer, see the

    prerequisites.


    > [!note]

    > User contribution mapping is not supported when you import projects to a

    > personal namespace. All

    > contributions are assigned to the personal namespace owner and cannot be reassigned.'
  x-displayName: Imports
  externalDocs:
    url: https://docs.gitlab.com/api/bulk_imports/
paths:
  /api/v4/import/github/gists:
    post:
      operationId: postApiV4ImportGithubGists
      summary: Import GitHub gists into GitLab snippets
      description: Imports personal GitHub gists into GitLab snippets. You can import gists with up to 10 files. GitHub gists with more than 10 files are skipped. You should manually migrate these GitHub gists. If any gists cannot be imported, an email is sent with a list of gists that were not imported.
      tags:
      - Imports
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable Entity
        '429':
          description: Too Many Requests
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ImportGithubGistsRequest'
  /api/v4/bulk_imports:
    post:
      operationId: postApiV4BulkImports
      summary: Start a group or project migration
      description: Starts a group or project migration. To migrate a project, specify `entities[project_entity]`.
      tags:
      - Imports
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBulkImport'
        '401':
          description: Unauthorized
        '400':
          description: Bad request
        '404':
          description: Not found
        '422':
          description: Unprocessable entity
        '503':
          description: Service unavailable
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/postApiV4BulkImportsRequest'
    get:
      operationId: getApiV4BulkImports
      summary: List all group or project migrations
      description: Lists all group or project migrations.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesBulkImport'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '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
      - name: sort
        required: false
        description: Sort results in ascending or descending order by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        in: query
      - name: status
        required: false
        description: Filter migrations by import status.
        schema:
          type:
          - string
          - 'null'
          enum:
          - created
          - started
          - finished
          - timeout
          - failed
          - canceled
          - null
        in: query
  /api/v4/bulk_imports/entities:
    get:
      operationId: getApiV4BulkImportsEntities
      summary: List all group or project migration entities
      description: Lists all group or project migration entities.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesBulkImportsEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '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
      - name: sort
        required: false
        description: Sort results in ascending or descending order by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        in: query
      - name: status
        required: false
        description: Filter entities by import status.
        schema:
          type:
          - string
          - 'null'
          enum:
          - created
          - started
          - finished
          - timeout
          - failed
          - canceled
          - null
        in: query
  /api/v4/bulk_imports/{import_id}:
    get:
      operationId: getApiV4BulkImportsImportId
      summary: Retrieve a group or project migration
      description: Retrieves details of a group or project migration.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBulkImport'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: import_id
        required: true
        description: ID of the GitLab Migration.
        schema:
          type: integer
        in: path
  /api/v4/bulk_imports/{import_id}/entities:
    get:
      operationId: getApiV4BulkImportsImportIdEntities
      summary: List all group or project migration entities
      description: Lists all group or project migration entities for a specified migration.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesBulkImportsEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: import_id
        required: true
        description: ID of the GitLab Migration.
        schema:
          type: integer
        in: path
      - name: status
        required: false
        description: Filter entities by import status.
        schema:
          type:
          - string
          - 'null'
          enum:
          - created
          - started
          - finished
          - timeout
          - failed
          - canceled
          - null
        in: query
      - 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
  /api/v4/bulk_imports/{import_id}/entities/{entity_id}:
    get:
      operationId: getApiV4BulkImportsImportIdEntitiesEntityId
      summary: Retrieve a group or project migration entity
      description: Retrieves details of a group or project migration entity.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBulkImportsEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: import_id
        required: true
        description: ID of the GitLab Migration.
        schema:
          type: integer
        in: path
      - name: entity_id
        required: true
        description: ID of the GitLab Migration entity.
        schema:
          type: integer
        in: path
  /api/v4/bulk_imports/{import_id}/entities/{entity_id}/failures:
    get:
      operationId: getApiV4BulkImportsImportIdEntitiesEntityIdFailures
      summary: List all failed import records for a migration entity
      description: Lists all failed import records for a group or project migration entity. This feature was introduced in GitLab 16.6.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBulkImportsEntityFailure'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: import_id
        required: true
        description: ID of the GitLab Migration.
        schema:
          type: integer
        in: path
      - name: entity_id
        required: true
        description: ID of the GitLab Migration entity.
        schema:
          type: integer
        in: path
  /api/v4/bulk_imports/{import_id}/cancel:
    post:
      operationId: postApiV4BulkImportsImportIdCancel
      summary: Cancel a migration
      description: Cancels a direct transfer migration. This feature was introduced in GitLab 17.1.
      tags:
      - Imports
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBulkImport'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: import_id
        required: true
        description: ID of the GitLab Migration.
        schema:
          type: integer
        in: path
components:
  schemas:
    postApiV4BulkImportsRequest:
      type: object
      properties:
        configuration:
          type:
          - object
          - 'null'
          description: The source GitLab instance configuration
          properties:
            url:
              type:
              - string
              - 'null'
              description: Source GitLab instance URL
            access_token:
              type:
              - string
              - 'null'
              description: Access token to the source GitLab instance
          required:
          - url
          - access_token
        entities:
          type:
          - array
          - 'null'
          description: List of entities to import
          items:
            type: object
            properties:
              source_type:
                type: string
                enum:
                - group_entity
                - project_entity
                description: Source entity type
                minLength: 1
              source_full_path:
                type:
                - string
                - 'null'
                description: Relative path of the source entity to import
                example: '''source/full/path'' not ''https://example.com/source/full/path'''
              destination_namespace:
                type:
                - string
                - 'null'
                description: Destination namespace for the entity
                example: '''destination_namespace'' or ''destination/namespace'''
              destination_slug:
                type:
                - string
                - 'null'
                description: Destination slug for the entity
                example: '''destination_slug'' not ''destination/slug'''
              destination_name:
                type:
                - string
                - 'null'
                description: 'Deprecated: Use :destination_slug instead. Destination slug for the entity'
                example: '''destination_slug'' not ''destination/slug'''
              migrate_projects:
                type: boolean
                description: Indicates group migration should include nested projects
                default: true
              migrate_memberships:
                type: boolean
                description: The option to migrate memberships or not
                default: true
            required:
            - source_type
            - source_full_path
            - destination_namespace
      required:
      - configuration
      - entities
    APIEntitiesBulkImportsEntity:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        bulk_import_id:
          type: integer
          format: int64
          example: 1
        status:
          type: string
          enum:
          - created
          - started
          - finished
          - timeout
          - failed
          example: created
        entity_type:
          type: string
          enum:
          - group
          - project
        source_full_path:
          type: string
          example: source_group
        destination_full_path:
          type: string
          example: some_group/source_project
        destination_name:
          type: string
          example: destination_slug
        destination_slug:
          type: string
          example: destination_slug
        destination_namespace:
          type: string
          example: destination_path
        parent_id:
          type: integer
          format: int64
          example: 1
        namespace_id:
          type: integer
          format: int64
          example: 1
        project_id:
          type: integer
          format: int64
          example: 1
        created_at:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        updated_at:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        failures:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesBulkImportsEntityFailure'
        migrate_projects:
          type: boolean
          example: true
        migrate_memberships:
          type: boolean
          example: true
        has_failures:
          type: boolean
          example: false
        stats:
          type: object
    APIEntitiesBulkImportsEntityFailure:
      type: object
      properties:
        relation:
          type: string
          example: label
        exception_message:
          type: string
          example: error message
        exception_class:
          type: string
          example: Exception
        correlation_id_value:
          type: string
          example: dfcf583058ed4508e4c7c617bd7f0edd
        source_url:
          type: string
          example: https://source.gitlab.com/group/-/epics/1
        source_title:
          type: string
          example: title
    APIEntitiesBulkImport:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        status:
          type: string
          enum:
          - created
          - started
          - finished
          - timeout
          - failed
          example: finished
        source_type:
          type: string
          example: gitlab
        source_url:
          type: string
          example: https://source.gitlab.com/
        created_at:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        updated_at:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        has_failures:
          type: boolean
          example: false
    postApiV4ImportGithubGistsRequest:
      type: object
      properties:
        personal_access_token:
          type:
          - string
          - 'null'
          description: GitHub personal access token.
      required:
      - personal_access_token
  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