groups.md 18.1 KB
Newer Older
1
# Groups API
2 3 4

## List groups

5 6
Get a list of visible groups for the authenticated user. When accessed without
authentication, only public groups are returned.
7 8 9

Parameters:

Sean McGivern's avatar
Sean McGivern committed
10 11
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
12
| `skip_groups` | array of integers | no | Skip the group IDs passed |
13
| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
14
| `search` | string | no | Return the list of authorized groups matching the search criteria |
15
| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` |
Sean McGivern's avatar
Sean McGivern committed
16
| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` |
Markus Koller's avatar
Markus Koller committed
17
| `statistics` | boolean | no | Include group statistics (admins only) |
18
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
19 20
| `owned` | boolean | no | Limit to groups explicitly owned by the current user |
| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) |
21 22 23 24 25 26 27 28 29 30 31

```
GET /groups
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
32
    "description": "An interesting group",
33
    "visibility": "public",
34 35 36 37 38
    "lfs_enabled": true,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
39
    "full_path": "foo-bar",
40
    "file_template_project_id": 1,
41
    "parent_id": null
42 43 44 45
  }
]
```

46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
When adding the parameter `statistics=true` and the authenticated user is an admin, additional group statistics are returned.

```
GET /groups?statistics=true
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "lfs_enabled": true,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
66
    "file_template_project_id": 1,
67 68 69 70 71 72 73 74 75 76 77 78
    "parent_id": null,
    "statistics": {
      "storage_size" : 212,
      "repository_size" : 33,
      "lfs_objects_size" : 123,
      "job_artifacts_size" : 57

    }
  }
]
```

79 80
You can search for groups by name or path, see below.

81 82 83 84 85 86
You can filter by [custom attributes](custom_attributes.md) with:

```
GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

JJ's avatar
JJ committed
87
## List a group's subgroups
88

89 90
> [Introduced][ce-15142] in GitLab 10.3.

91 92 93 94 95 96 97 98 99
Get a list of visible direct subgroups in this group.
When accessed without authentication, only public groups are returned.

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the parent group |
| `skip_groups` | array of integers | no | Skip the group IDs passed |
100
| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
101
| `search` | string | no | Return the list of authorized groups matching the search criteria |
102
| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` |
103 104
| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` |
| `statistics` | boolean | no | Include group statistics (admins only) |
105
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
106 107
| `owned` | boolean | no | Limit to groups explicitly owned by the current user |
| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) |
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126

```
GET /groups/:id/subgroups
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "lfs_enabled": true,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://gitlab.example.com/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
127
    "file_template_project_id": 1,
128 129 130 131 132
    "parent_id": 123
  }
]
```

133 134
## List a group's projects

135 136
Get a list of projects in this group. When accessed without authentication, only
public projects are returned.
137 138 139 140 141 142 143

```
GET /groups/:id/projects
```

Parameters:

144 145
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
146
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
147 148 149 150 151 152
| `archived` | boolean | no | Limit by archived status |
| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Return list of authorized projects matching the search criteria |
| `simple` | boolean | no | Return only the ID, URL, name, and path of each project |
153 154
| `owned` | boolean | no | Limit by projects owned by the current user |
| `starred` | boolean | no | Limit by projects starred by the current user |
Heinrich Lee Yu's avatar
Heinrich Lee Yu committed
155 156 157 158
| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` |
| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` |
| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` |
| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` |
159
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
160 161

Example response:
162 163 164 165 166 167 168 169 170

```json
[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "master",
    "tag_list": [],
    "archived": false,
171
    "visibility": "internal",
172 173 174 175 176 177 178 179 180 181
    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
182
    "jobs_enabled": true,
183 184 185 186 187 188 189 190 191
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
192
      "kind": "group"
193 194 195 196 197
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
198
    "public_jobs": true,
199 200
    "shared_with_groups": [],
    "request_access_enabled": false
201 202 203 204 205 206
  }
]
```

## Details of a group

207 208
Get all details of a group. This endpoint can be accessed without authentication
if the group is publicly accessible.
209 210 211 212 213 214 215 216 217

```
GET /groups/:id
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
218
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
219
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
220
| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). |
221 222

```bash
223
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4
224 225 226 227 228 229 230 231 232 233
```

Example response:

```json
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
234
  "visibility": "public",
235 236
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
237
  "request_access_enabled": false,
238 239
  "full_name": "Twitter",
  "full_path": "twitter",
240
  "file_template_project_id": 1,
241
  "parent_id": null,
242 243 244 245 246 247 248
  "projects": [
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "master",
      "tag_list": [],
      "archived": false,
249
      "visibility": "public",
250 251 252 253 254 255 256 257 258 259
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
260
      "jobs_enabled": true,
261 262 263 264 265 266 267 268 269 270
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
271
        "kind": "group"
272 273 274 275 276
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
277
      "public_jobs": true,
278 279
      "shared_with_groups": [],
      "request_access_enabled": false
280 281 282 283 284 285 286
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "master",
      "tag_list": [],
      "archived": false,
287
      "visibility": "internal",
288 289 290 291 292 293 294 295 296 297
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
298
      "jobs_enabled": true,
299 300 301 302 303 304 305 306 307 308
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
309
        "kind": "group"
310 311 312 313 314
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
315
      "public_jobs": true,
316 317
      "shared_with_groups": [],
      "request_access_enabled": false
318 319 320 321 322 323 324 325 326
    }
  ],
  "shared_projects": [
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "master",
      "tag_list": [],
      "archived": false,
327
      "visibility": "private",
328 329 330 331 332 333 334 335 336 337
      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
338
      "jobs_enabled": true,
339 340 341 342 343 344 345 346 347 348
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
349
        "kind": "group"
350 351 352 353 354
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
355
      "public_jobs": true,
356 357 358 359
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
360
          "group_full_path": "twitter",
361 362
          "group_access_level": 30,
          "expires_at": null
363 364 365 366
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
367
          "group_full_path": "gitlab-org",
368 369
          "group_access_level": 10,
          "expires_at": "2018-08-14"
370 371 372 373 374 375 376
        }
      ]
    }
  ]
}
```

377 378 379
When adding the parameter `with_projects=false`, projects will not be returned.

```bash
380
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4?with_projects=false
381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
```

Example response:

```json
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "full_name": "Twitter",
  "full_path": "twitter",
397
  "file_template_project_id": 1,
398 399 400 401
  "parent_id": null
}
```

402 403 404 405 406 407 408 409 410 411
## New group

Creates a new project group. Available only for users who can create groups.

```
POST /groups
```

Parameters:

412 413 414 415 416 417 418 419
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `name` | string | yes | The name of the group |
| `path` | string | yes | The path of the group |
| `description` | string | no | The group's description |
| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. |
| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
| `request_access_enabled` | boolean | no | Allow users to request member access. |
Michael Lihs's avatar
Michael Lihs committed
420
| `parent_id` | integer | no | The parent group id for creating nested group. |
421 422 423 424 425 426 427 428 429 430 431

## Transfer project to group

Transfer a project to the Group namespace. Available only for admin

```
POST  /groups/:id/projects/:project_id
```

Parameters:

432 433 434 435
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450

## Update group

Updates the project group. Only available to group owners and administrators.

```
PUT /groups/:id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the group |
| `name` | string | no | The name of the group |
| `path` | string | no | The path of the group |
| `description` | string | no | The description of the group |
451
| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. |
452
| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
453
| `request_access_enabled` | boolean | no | Allow users to request member access. |
454
| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from |
455 456

```bash
457
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
458 459 460 461 462 463 464 465 466 467 468

```

Example response:

```json
{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
469
  "visibility": "internal",
470 471
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
472
  "request_access_enabled": false,
473 474
  "full_name": "Foobar Group",
  "full_path": "foo-bar",
475
  "file_template_project_id": 1,
476
  "parent_id": null,
477 478 479 480 481 482 483 484
  "projects": [
    {
      "id": 9,
      "description": "foo",
      "default_branch": "master",
      "tag_list": [],
      "public": false,
      "archived": false,
485
      "visibility": "internal",
486 487 488 489 490 491 492 493 494 495
      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
496
      "jobs_enabled": true,
497 498 499 500 501 502 503 504 505
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
506
        "kind": "group"
507 508 509 510 511
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
512
      "public_jobs": true,
513 514
      "shared_with_groups": [],
      "request_access_enabled": false
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531
    }
  ]
}
```

## Remove group

Removes group with all projects inside.

```
DELETE /groups/:id
```

Parameters:

- `id` (required) - The ID or path of a user group

Stan Hu's avatar
Stan Hu committed
532 533 534
This will queue a background job to delete all projects in the group. The
response will be a 202 Accepted if the user has authorization.

535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555
## Search for group

Get all groups that match your string in their name or path.

```
GET /groups?search=foobar
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]
```

## Group members

556
Please consult the [Group Members](members.md) documentation.
557 558 559 560 561 562 563 564 565 566 567 568 569 570

## Namespaces in groups

By default, groups only get 20 namespaces at a time because the API results are paginated.

To get more (up to 100), pass the following as an argument to the API call:
```
/groups?per_page=100
```

And to switch pages add:
```
/groups?per_page=100&page=2
```
571 572

[ce-15142]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15142
573 574 575 576

## Group badges

Read more in the [Group Badges](group_badges.md) documentation.