Use this API to interact with GitLab organizations. For more information, see organizations.
Cancel maintenance on an organization (maintenance_initialization -> active)
POST /api/v4/internal/org_mover/cancel_maintenance
Aborts maintenance initialization before the organization reaches the maintenance state, returning it to active.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
organization_Required | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
204 | No Content | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
422 | Unprocessable entity | — |
Confirm maintenance on an organization (maintenance_initialization -> maintenance)
POST /api/v4/internal/org_mover/confirm_maintenance
Completes the maintenance transition once the organization is drained.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
organization_Required | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
204 | No Content | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
409 | Conflict | — |
422 | Unprocessable entity | — |
Exit maintenance on an organization (maintenance -> active)
POST /api/v4/internal/org_mover/exit_maintenance
Returns an organization from maintenance to active.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
organization_Required | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
204 | No Content | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
422 | Unprocessable entity | — |
Report cutover readiness for an organization
GET /api/v4/internal/org_mover/maintenance_readiness
Reports whether an organization is drained and safe to enter maintenance.
Parameters
| Name | Type | Description |
|---|---|---|
organization_Query, | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Report an organization’s current lifecycle state
GET /api/v4/internal/org_mover/maintenance_state
Returns the organization’s current maintenance lifecycle state.
Parameters
| Name | Type | Description |
|---|---|---|
organization_Query, | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Start maintenance on an organization (active -> maintenance_initialization)
POST /api/v4/internal/org_mover/start_maintenance
Begins the maintenance transition for an organization.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
maintenance_Required | String | The reason for entering maintenance Allowed values: migration,isolation,incident,billing,legalMinimum length: 1 |
organization_Required | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
204 | No Content | — |
400 | Bad request | — |
401 | Unauthorized | — |
404 | Not found | — |
422 | Unprocessable entity | — |
Create an organization
POST /api/v4/organizations
Creates an organization. This feature was introduced in GitLab 17.5. This feature is behind the allow_organization_creation feature flag. In GitLab 18.3, the feature flag changed to organization_switching. In GitLab 19.4, the feature flag changed to org_stage_experimental.
Request body (multipart/form-data)
| Property | Type | Description |
|---|---|---|
avatar | String (binary) | The avatar image for the organization |
description | String | The description of the organization |
nameRequired | String | The name of the organization |
pathRequired | String | The path of the organization |
visibility | String | The visibility level of the organization Allowed values: private,public |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
Soft-delete an organization
DELETE /api/v4/organizations/{id}
This feature was introduced in GitLab 19.2.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | Integer | The ID of the organization |
Responses
| Code | Description | Schema |
|---|---|---|
202 | Accepted | — |
400 | Bad request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesOrganizationsOrganization
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:https: |
created_ | String (date- | Example:2022- |
description | String | Example:My description |
id | Integer (int64) | Example:1 |
name | String | Example:Git |
path | String | Example:gitlab |
updated_ | String (date- | Example:2022- |
uuid | String | Example:0192f8c2- |
visibility | String | Example:public |
web_ | String | Example:https: |