2020-10-28 15:08:49 +00:00
---
2021-04-23 15:09:37 +00:00
stage: Manage
2022-01-27 03:14:06 +00:00
group: Authentication and Authorization
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-28 15:08:49 +00:00
---
2021-12-07 06:13:51 +00:00
# Namespaces API **(FREE)**
2015-05-25 20:51:37 +00:00
2021-07-26 15:08:30 +00:00
Usernames and group names fall under a special category called
2022-08-02 03:09:33 +00:00
[namespaces ](../user/namespace/index.md ).
2016-01-24 18:28:24 +00:00
For users and groups supported API calls see the [users ](users.md ) and
[groups ](groups.md ) documentation respectively.
2016-01-18 08:42:44 +00:00
2021-06-28 15:08:03 +00:00
[Pagination ](index.md#pagination ) is used.
2016-01-18 08:42:44 +00:00
2015-05-25 20:51:37 +00:00
## List namespaces
2016-01-24 18:28:24 +00:00
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.
2015-05-25 20:51:37 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2015-05-25 20:51:37 +00:00
GET /namespaces
2021-07-29 21:10:10 +00:00
GET /namespaces?search=foobar
GET /namespaces?owned_only=true
2015-05-25 20:51:37 +00:00
```
2021-07-29 21:10:10 +00:00
| 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 | In GitLab 14.2 and later, returns a list of owned namespaces only |
2016-01-24 18:28:24 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/namespaces"
2016-01-18 08:42:44 +00:00
```
2016-01-24 18:28:24 +00:00
Example response:
2015-05-25 20:51:37 +00:00
```json
[
{
"id": 1,
2017-08-25 13:17:04 +00:00
"name": "user1",
2015-05-25 20:51:37 +00:00
"path": "user1",
2017-06-27 20:35:35 +00:00
"kind": "user",
2020-08-12 06:09:53 +00:00
"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",
"trial_ends_on": null,
"trial": false
2015-05-25 20:51:37 +00:00
},
{
"id": 2,
2017-08-25 13:17:04 +00:00
"name": "group1",
2015-05-25 20:51:37 +00:00
"path": "group1",
2017-06-27 20:35:35 +00:00
"kind": "group",
"full_path": "group1",
2018-02-13 10:44:05 +00:00
"parent_id": null,
2020-08-12 06:09:53 +00:00
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
"plan": "default",
"trial_ends_on": null,
"trial": false
2017-02-14 13:34:36 +00:00
},
{
"id": 3,
2017-08-25 13:17:04 +00:00
"name": "bar",
2017-02-14 13:34:36 +00:00
"path": "bar",
"kind": "group",
"full_path": "foo/bar",
2018-02-13 10:44:05 +00:00
"parent_id": 9,
2020-08-12 06:09:53 +00:00
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/foo/bar",
"members_count_with_descendants": 5,
"billable_members_count": 5,
"plan": "default",
"trial_ends_on": null,
"trial": false
2015-05-25 20:51:37 +00:00
}
]
```
2021-07-05 00:07:09 +00:00
Owners also see the `plan` property associated with a namespace:
2019-07-03 09:32:54 +00:00
```json
[
{
"id": 1,
"name": "user1",
2021-07-05 00:07:09 +00:00
"plan": "silver",
2019-07-03 09:32:54 +00:00
...
}
]
```
2020-11-19 21:09:07 +00:00
Users on GitLab.com also see `max_seats_used` and `seats_in_use` parameters.
2020-10-16 18:09:04 +00:00
`max_seats_used` is the highest number of users the group had. `seats_in_use` is
the number of license seats currently being used. Both values are updated
once a day.
2020-09-25 09:09:40 +00:00
2020-11-19 21:09:07 +00:00
`max_seats_used` and `seats_in_use` are non-zero only for namespaces on paid plans.
2020-09-25 09:09:40 +00:00
```json
[
{
"id": 1,
"name": "user1",
"billable_members_count": 2,
"max_seats_used": 3,
2020-10-16 18:09:04 +00:00
"seats_in_use": 2,
2020-09-25 09:09:40 +00:00
...
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-07-05 00:07:09 +00:00
Only group owners are presented with `members_count_with_descendants` and `plan` .
2017-06-28 20:27:01 +00:00
2017-11-17 01:43:55 +00:00
## Get namespace by ID
Get a namespace by ID.
2020-02-27 09:09:01 +00:00
```plaintext
2017-11-17 01:43:55 +00:00
GET /namespaces/:id
```
2019-03-15 09:55:20 +00:00
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | ID or [URL-encoded path of the namespace ](index.md#namespaced-path-encoding ) |
2017-11-17 01:43:55 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/namespaces/2"
2017-11-17 01:43:55 +00:00
```
Example response:
```json
{
"id": 2,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
2018-02-13 10:44:05 +00:00
"parent_id": null,
2020-08-12 06:09:53 +00:00
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
2020-09-25 09:09:40 +00:00
"max_seats_used": 0,
2020-10-16 18:09:04 +00:00
"seats_in_use": 0,
2020-08-12 06:09:53 +00:00
"plan": "default",
"trial_ends_on": null,
"trial": false
2017-11-17 01:43:55 +00:00
}
```
2017-11-23 13:32:16 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/namespaces/group1"
2017-11-23 13:32:16 +00:00
```
Example response:
```json
{
"id": 2,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
2018-02-13 10:44:05 +00:00
"parent_id": null,
2020-08-12 06:09:53 +00:00
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
2020-09-25 09:09:40 +00:00
"max_seats_used": 0,
2020-10-16 18:09:04 +00:00
"seats_in_use": 0,
2020-08-12 06:09:53 +00:00
"plan": "default",
"trial_ends_on": null,
"trial": false
2017-11-23 13:32:16 +00:00
}
```
2021-04-19 18:09:09 +00:00
## Get existence of a namespace
Get existence of a namespace by path. Suggests a new namespace path that does not already exist.
```plaintext
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:
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/namespaces/my-group/exists?parent_id=1"
```
Example response:
```json
{
"exists": true,
"suggests": [
"my-group1"
]
}
```