namespaces.md 2.67 KB
Newer Older
1
# Namespaces API
2

3 4 5 6
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.
7 8 9

[Pagination](README.md#pagination) is used.

10 11
## List namespaces

12 13
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.
14 15 16 17 18

```
GET /namespaces
```

19 20
Example request:

21
```bash
22
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces
23 24
```

25 26
Example response:

27 28 29 30
```json
[
  {
    "id": 1,
EmilienMottet's avatar
EmilienMottet committed
31
    "name": "user1",
32
    "path": "user1",
33
    "kind": "user",
34
    "full_path": "user1"
35 36 37
  },
  {
    "id": 2,
EmilienMottet's avatar
EmilienMottet committed
38
    "name": "group1",
39
    "path": "group1",
40 41
    "kind": "group",
    "full_path": "group1",
42
    "parent_id": null,
43
    "members_count_with_descendants": 2
44 45 46
  },
  {
    "id": 3,
EmilienMottet's avatar
EmilienMottet committed
47
    "name": "bar",
48 49 50
    "path": "bar",
    "kind": "group",
    "full_path": "foo/bar",
51
    "parent_id": 9,
52
    "members_count_with_descendants": 5
53 54 55 56
  }
]
```

Mark Chao's avatar
doc  
Mark Chao committed
57
**Note**: `members_count_with_descendants` are presented only for group maintainers/owners.
58

59 60
## Search for namespace

61
Get all namespaces that match a string in their name or path.
62 63 64 65 66

```
GET /namespaces?search=foobar
```

67 68 69 70
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `search`  | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |

71 72
Example request:

73
```bash
74
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces?search=twitter
75 76
```

77 78
Example response:

79 80 81
```json
[
  {
82
    "id": 4,
EmilienMottet's avatar
EmilienMottet committed
83
    "name": "twitter",
84
    "path": "twitter",
85 86
    "kind": "group",
    "full_path": "twitter",
87
    "parent_id": null,
88
    "members_count_with_descendants": 2
89 90 91
  }
]
```
92 93 94 95 96 97 98 99 100 101 102

## Get namespace by ID

Get a namespace by ID.

```
GET /namespaces/:id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
103
| `id`      | integer/string | yes | ID or path of the namespace |
104 105 106 107

Example request:

```bash
108
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces/2
109 110 111 112 113 114 115 116 117 118 119
```

Example response:

```json
{
  "id": 2,
  "name": "group1",
  "path": "group1",
  "kind": "group",
  "full_path": "group1",
120
  "parent_id": null,
121 122 123
  "members_count_with_descendants": 2
}
```
124 125 126 127

Example request:

```bash
128
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces/group1
129 130 131 132 133 134 135 136 137 138 139
```

Example response:

```json
{
  "id": 2,
  "name": "group1",
  "path": "group1",
  "kind": "group",
  "full_path": "group1",
140
  "parent_id": null,
141 142 143
  "members_count_with_descendants": 2
}
```