73c6477b7e
Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800
157 lines
3 KiB
Markdown
157 lines
3 KiB
Markdown
# Namespaces API
|
|
|
|
Usernames and groupnames fall under a special category called namespaces.
|
|
|
|
For users and groups supported API calls see the [users](users.md) and
|
|
[groups](groups.md) documentation respectively.
|
|
|
|
[Pagination](README.md#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:
|
|
|
|
```bash
|
|
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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](https://about.gitlab.com/pricing/#gitlab-com) may also see
|
|
the `plan` parameter associated with a namespace:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "user1",
|
|
"plan": "bronze",
|
|
...
|
|
}
|
|
]
|
|
```
|
|
|
|
NOTE: **Note:** Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **(BRONZE ONLY)**.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces?search=twitter
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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](README.md#namespaced-path-encoding) |
|
|
|
|
Example request:
|
|
|
|
```bash
|
|
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces/2
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"id": 2,
|
|
"name": "group1",
|
|
"path": "group1",
|
|
"kind": "group",
|
|
"full_path": "group1",
|
|
"parent_id": null,
|
|
"members_count_with_descendants": 2
|
|
}
|
|
```
|
|
|
|
Example request:
|
|
|
|
```bash
|
|
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces/group1
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"id": 2,
|
|
"name": "group1",
|
|
"path": "group1",
|
|
"kind": "group",
|
|
"full_path": "group1",
|
|
"parent_id": null,
|
|
"members_count_with_descendants": 2
|
|
}
|
|
```
|