Namespaces API
Usernames and groupnames fall under a special category called namespaces.
For users and groups supported API calls see the users and groups documentation respectively.
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
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"
},
{
"id": 2,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
"parent_id": null,
"members_count_with_descendants": 2
},
{
"id": 3,
"name": "bar",
"path": "bar",
"kind": "group",
"full_path": "foo/bar",
"parent_id": 9,
"members_count_with_descendants": 5
}
]
Users on GitLab.com Bronze or higher may also see
the plan
parameter associated with a namespace:
[
{
"id": 1,
"name": "user1",
"plan": "bronze",
...
}
]
Note: Only group maintainers/owners are presented with
members_count_with_descendants
, as well as plan
.Search for namespace
Get all namespaces that match a string in their name or path.
GET /namespaces?search=foobar
Attribute | Type | Required | Description |
---|---|---|---|
search
| string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces?search=twitter
Example response:
[
{
"id": 4,
"name": "twitter",
"path": "twitter",
"kind": "group",
"full_path": "twitter",
"parent_id": null,
"members_count_with_descendants": 2
}
]
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,
"members_count_with_descendants": 2
}
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,
"members_count_with_descendants": 2
}
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc