Namespaces API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, Self-managed, GitLab Dedicated
Usernames and group names fall under a special category called namespaces.
You might also want to view documentation for:
Pagination is used.
List namespaces
Get a list of the namespaces of the authenticated user. If the user is an administrator, a list of all namespaces in the GitLab instance is shown.
GET /namespaces
GET /namespaces?search=foobar
GET /namespaces?owned_only=true
GET /namespaces?top_level_only=true
Attribute | Type | Required | Description |
---|---|---|---|
search |
string | no | Returns a list of namespaces the user is authorized to view based on the search criteria |
owned_only |
boolean | no | Returns a list of owned namespaces only |
top_level_only |
boolean | no | In GitLab 16.8 and later, returns a list of top level namespaces only |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces"
Example response:
[
{
"id": 1,
"name": "user1",
"path": "user1",
"kind": "user",
"full_path": "user1",
"parent_id": null,
"avatar_url": "https://secure.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "https://gitlab.example.com/user1",
"billable_members_count": 1,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100,
"projects_count": 3
},
{
"id": 2,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100,
"projects_count": 3
},
{
"id": 3,
"name": "bar",
"path": "bar",
"kind": "group",
"full_path": "foo/bar",
"parent_id": 9,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/foo/bar",
"members_count_with_descendants": 5,
"billable_members_count": 5,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100,
"projects_count": 3
}
"projects_count": 3
]
Owners also see the plan
property associated with a namespace:
[
{
"id": 1,
"name": "user1",
"plan": "silver",
...
}
]
Users on GitLab.com also see max_seats_used
, seats_in_use
and max_seats_used_changed_at
parameters.
max_seats_used
is the highest number of users the group had. seats_in_use
is
the number of license seats currently being used. max_seats_used_changed_at
shows the date when the max_seats_used
value changed. All the values are updated
once a day.
max_seats_used
and seats_in_use
are non-zero only for namespaces on paid plans.
[
{
"id": 1,
"name": "user1",
"billable_members_count": 2,
"max_seats_used": 3,
"max_seats_used_changed_at":"2023-02-13T12:00:02.000Z",
"seats_in_use": 2,
...
}
]
Only group owners are presented with members_count_with_descendants
, root_repository_size
, projects_count
and plan
.
Get namespace by ID
Get a namespace by ID.
GET /namespaces/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | ID or URL-encoded path of the namespace |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces/2"
Example response:
{
"id": 2,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
"max_seats_used": 0,
"seats_in_use": 0,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100,
"projects_count": 3
}
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces/group1"
Example response:
{
"id": 2,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
"max_seats_used": 0,
"seats_in_use": 0,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100
}
Get existence of a namespace
Get existence of a namespace by path. Suggests a new namespace path that does not already exist.
GET /namespaces/:namespace/exists
Attribute | Type | Required | Description |
---|---|---|---|
namespace |
string | yes | Namespace’s path. |
parent_id |
integer | no | The ID of the parent namespace. If no ID is specified, only top-level namespaces are considered. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces/my-group/exists?parent_id=1"
Example response:
{
"exists": true,
"suggests": [
"my-group1"
]
}
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support