GitLab Group import and export API

openapi: 3.2.0
info:
  title: GitLab REST Group import and export 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: Group import and export
  description: 'Use this API to migrate a group structure by exporting

    and importing a file. When you use it with the

    project import and export API, you can

    preserve relationships that span the group, such as connections between project issues and group

    epics. Run the group export and import first, then import the project exports into the group

    structure.


    A group export includes group milestones, boards, labels, badges, members, events, wikis (Premium

    and Ultimate only), and subgroups. Each subgroup includes all of the same data.


    To preserve the member list and permissions of an imported group, make sure those users exist on the

    destination instance before you import.


    Because of issue 405168, imported groups have

    a `private` visibility level unless you import them into a parent group. By default, groups imported

    into a parent group inherit the visibility of the parent.


    The destination instance uses the group relations export endpoints during

    group migration by direct transfer. You don''t

    usually need to call them yourself. In this context, a relation is an exportable item such as an

    epic, including any related items such as a label. These endpoints require your instance to meet certain

    prerequisites,

    and can''t be used with the file-based export and import endpoints.'
  x-displayName: Group import and export
  externalDocs:
    url: https://docs.gitlab.com/api/group_import_export/
paths:
  /api/v4/groups/import/authorize:
    post:
      operationId: postApiV4GroupsImportAuthorize
      summary: Workhorse authorize the group import upload
      description: This feature was introduced in GitLab 12.8
      tags:
      - Group import and export
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
  /api/v4/groups/import:
    post:
      operationId: postApiV4GroupsImport
      summary: Create a group import
      description: Creates a group import. The maximum import file size can be set by the Administrator on GitLab Self-Managed (defaults to `0` (unlimited)).
      tags:
      - Group import and export
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '400':
          description: Bad request
        '429':
          description: Too many requests
        '503':
          description: Service unavailable
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/postApiV4GroupsImportRequest'
  /api/v4/groups/{id}/export/download:
    get:
      operationId: getApiV4GroupsIdExportDownload
      summary: Retrieve a group export download
      description: Retrieves the exported archive for a specified group.
      tags:
      - Group import and export
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '503':
          description: Service unavailable
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
  /api/v4/groups/{id}/export:
    post:
      operationId: postApiV4GroupsIdExport
      summary: Create a group export
      description: Creates a group export for a specified group.
      tags:
      - Group import and export
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '429':
          description: Too many requests
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
  /api/v4/groups/{id}/export_relations:
    post:
      operationId: postApiV4GroupsIdExportRelations
      summary: Schedule a relations export for a group
      description: Schedules a relations export for a specified group.
      tags:
      - Group import and export
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '429':
          description: Too many requests
        '503':
          description: Service unavailable
        '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/postApiV4GroupsIdExportRelationsRequest'
  /api/v4/groups/{id}/export_relations/download:
    get:
      operationId: getApiV4GroupsIdExportRelationsDownload
      summary: Download a relations export for a group
      description: Downloads a group relations export file.
      tags:
      - Group import and export
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '429':
          description: Too many requests
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: relation
        required: true
        description: Name of the group top-level relation to download or view.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: batched
        required: false
        description: If `true`, downloads the export in batches. All or none of `batched`, `batch_number` must be provided.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: batch_number
        required: false
        description: Number of the export batch to download. All or none of `batched`, `batch_number` must be provided.
        schema:
          type:
          - integer
          - 'null'
        in: query
  /api/v4/groups/{id}/export_relations/status:
    get:
      operationId: getApiV4GroupsIdExportRelationsStatus
      summary: Retrieve the status of an relations export for a group
      description: Retrieves the status of a relations export for a group.
      tags:
      - Group import and export
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesBulkImportsExportStatus'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: relation
        required: false
        description: Name of the group top-level relation to download or view.
        schema:
          type:
          - string
          - 'null'
        in: query
components:
  schemas:
    postApiV4GroupsImportRequest:
      type: object
      properties:
        path:
          type:
          - string
          - 'null'
          description: Group path
        name:
          type:
          - string
          - 'null'
          description: Group name
        file:
          type:
          - string
          - 'null'
          format: binary
          description: The group export file to be imported
        parent_id:
          type:
          - integer
          - 'null'
          description: The ID of the parent group that the group will be imported into. Defaults to the current user's namespace.
        organization_id:
          type: integer
          description: 'The ID of the organization that the group will be part of. '
      required:
      - path
      - name
      - file
    postApiV4GroupsIdExportRelationsRequest:
      type: object
      properties:
        batched:
          type:
          - boolean
          - 'null'
          description: If `true`, exports in batches.
    APIEntitiesBulkImportsExportBatchStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - started
          - finished
          - failed
          example: started
        batch_number:
          type: integer
          example: 1
        objects_count:
          type: integer
          example: 100
        error:
          type: string
          example: Error message
        updated_at:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
    APIEntitiesBulkImportsExportStatus:
      type: object
      properties:
        relation:
          type: string
          example: issues
        status:
          type: string
          enum:
          - pending
          - started
          - finished
          - failed
          example: started
        error:
          type: string
          example: Error message
        updated_at:
          type: string
          format: date-time
          example: '2012-05-28T04:42:42-07:00'
        batched:
          type: boolean
          example: true
        batches_count:
          type: integer
          example: 2
        total_objects_count:
          type: integer
          example: 100
        batches:
          $ref: '#/components/schemas/APIEntitiesBulkImportsExportBatchStatus'
  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