Organizations API

Use this API to interact with GitLab organizations. For more information, see organization.

Create an organization

Creates an organization.

This endpoint is an experiment and might be changed or removed without notice.

POST /organizations

Parameters:

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "name=New Organization" \
  --form "path=new-org" \
  --form "description=A new organization" \
  --form "avatar=@/path/to/avatar.png" \
  --url "https://gitlab.example.com/api/v4/organizations"

Example response:

{
  "id": 42,
  "uuid": "0192f8c2-1a2b-7cde-89ab-0123456789ab",
  "name": "New Organization",
  "path": "new-org",
  "description": "A new organization",
  "created_at": "2024-09-18T02:35:15.371Z",
  "updated_at": "2024-09-18T02:35:15.371Z",
  "web_url": "https://gitlab.example.com/o/new-org/-/overview",
  "avatar_url": "https://gitlab.example.com/uploads/-/system/organizations/organization_detail/avatar/42/avatar.png"
}

Restore an organization

Restores a soft-deleted organization.

Prerequisites:

• You must be an administrator.

POST /organizations/:id/restore

Supported attributes:

If successful, returns 201 Created and the following response attributes:

If the organization is not soft-deleted, returns 400 Bad Request.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/organizations/42/restore"

Example response:

{
  "id": 42,
  "uuid": "0192f8c2-1a2b-7cde-89ab-0123456789ab",
  "name": "New Organization",
  "path": "new-org",
  "description": "A new organization",
  "visibility": "private",
  "created_at": "2024-09-18T02:35:15.371Z",
  "updated_at": "2024-09-20T10:12:45.118Z",
  "web_url": "https://gitlab.example.com/o/new-org/-/overview",
  "avatar_url": null
}

Transfer users to an organization

Transfers ownership of users to an organization, including their personal namespaces and projects. This is a change of ownership, not organization membership. The transfer runs in the background.

Prerequisites:

• You must be an administrator.
• All users must belong to the same organization.
• No user can be an internal user, such as the ghost user or a bot like support_bot or admin_bot. Service accounts and project access token bots can be transferred.

POST /organizations/:id/transfer_users

Parameters:

If successful, returns 202 Accepted and the IDs of the users being transferred.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "user_ids[]=5" \
  --data "user_ids[]=6" \
  --url "https://gitlab.example.com/api/v4/organizations/42/transfer_users"

Example response:

{
  "organization_id": 42,
  "user_ids": [5, 6]
}

List organization users

Lists the users of an organization.

Prerequisites:

• Instance or organization administrator access.

GET /organizations/:id/users

Supported attributes:

This endpoint supports only keyset pagination. Keyset pagination is used by default, and the page parameter is not supported.

If successful, returns 200 OK and the following response attributes:

Example request:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/organizations/42/users"

Example response:

[
  {
    "id": 1001,
    "username": "jsmith",
    "bot": false,
    "access_level": "default"
  }
]

Add a user to an organization

Adds a user to an organization.

Prerequisites:

• Instance or organization administrator access.

POST /organizations/:id/users

Supported attributes:

If successful, returns 201 Created and the attributes listed in List organization users.

If the user does not exist or is already a member, returns 400 Bad Request. To change the access level of an existing member, use Update an organization user.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "username=jsmith" \
  --data "access_level=owner" \
  --url "https://gitlab.example.com/api/v4/organizations/42/users"

Example response:

{
  "id": 1001,
  "username": "jsmith",
  "bot": false,
  "access_level": "owner"
}

Update an organization user

Changes the access level of a user in an organization. For example, you can make a member an organization administrator.

Prerequisites:

• Instance or organization administrator access.

PUT /organizations/:id/users/:user_id

Supported attributes:

If successful, returns 200 OK and the attributes listed in List organization users.

Returns 400 Bad Request if the change would leave the organization without an active organization administrator.

Returns 404 Not Found if the user is not a member of the organization.

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "access_level=owner" \
  --url "https://gitlab.example.com/api/v4/organizations/42/users/1001"

Example response:

{
  "id": 1001,
  "username": "jsmith",
  "bot": false,
  "access_level": "owner"
}

Remove a user from an organization

Removes a user from an organization. Removal from an organization also removes the user as a member from any groups or projects managed by the organization.

Prerequisites:

• Instance or organization administrator access, unless you are removing yourself.

DELETE /organizations/:id/users/:user_id

Supported attributes:

If successful, returns 204 No Content.

Returns 400 Bad Request if:

• The user is the last active organization administrator.
• The organization is the user’s home organization, which is the organization that the user belongs to by default.
• The user would no longer belong to any organization.

Returns 403 Forbidden if you do not have permission to remove the user.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/organizations/42/users/5"