Merge branch 'docs-api-merge-new-2' into 'master'

Update api docs to finish aligning EE and CE docs

See merge request gitlab-org/gitlab-ce!29852

doc/api/group_boards.md

@@ -61,6 +61,59 @@ Example response:
 ]
 ```
 
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
+different parameters, due to the ability to have multiple group boards. Refer to the table
+above to see what enpoint(s) belong to each tier.
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+]
+```
+
 ## Single board
 
 Gets a single board.
@@ -116,6 +169,206 @@ Example response:
   }
 ```
 
+Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
+different parameters, due to the ability to have multiple group boards:
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "name:": "group issue board",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+```
+
+## Create a Group Issue Board **[PREMIUM]**
+
+Creates a Group Issue Board.
+
+```
+POST /groups/:id/boards
+```
+
+| 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 |
+| `name` | string | yes | The name of the new board |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards?name=newboard
+```
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "name": "newboard",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone":   {
+      "id": 12
+      "title": "10.0"
+    },
+    "lists" : [
+      {
+        "id" : 1,
+        "label" : {
+          "name" : "Testing",
+          "color" : "#F0AD4E",
+          "description" : null
+        },
+        "position" : 1
+      },
+      {
+        "id" : 2,
+        "label" : {
+          "name" : "Ready",
+          "color" : "#FF0000",
+          "description" : null
+        },
+        "position" : 2
+      },
+      {
+        "id" : 3,
+        "label" : {
+          "name" : "Production",
+          "color" : "#FF5F00",
+          "description" : null
+        },
+        "position" : 3
+      }
+    ]
+  }
+```
+
+## Update a Group Issue Board **[PREMIUM]**
+
+> [Introduced][ee-5954] in GitLab 11.1.
+
+Updates a Group Issue Board.
+
+```
+PUT /groups/:id/boards/:board_id
+```
+
+| 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 |
+| `board_id`          | integer        | yes      | The ID of a board |
+| `name`              | string         | no       | The new name of the board |
+| `assignee_id`       | integer        | no       | The assignee the board should be scoped to |
+| `milestone_id`      | integer        | no       | The milestone the board should be scoped to |
+| `labels`            | string         | no       | Comma-separated list of label names which the board should be scoped to |
+| `weight`            | integer        | no       | The weight range from 0 to 9, to which the board should be scoped to |
+
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1?name=new_name&milestone_id=44&assignee_id=1&labels=GroupLabel&weight=4
+```
+
+Example response:
+
+```json
+  {
+    "id": 1,
+    "project": null,
+    "lists": [],
+    "name": "new_name",
+    "group": {
+      "id": 5,
+      "name": "Documentcloud",
+      "web_url": "http://example.com/groups/documentcloud"
+    },
+    "milestone": {
+      "id": 44,
+      "iid": 1,
+      "group_id": 5,
+      "title": "Group Milestone",
+      "description": "Group Milestone Desc",
+      "state": "active",
+      "created_at": "2018-07-03T07:15:19.271Z",
+      "updated_at": "2018-07-03T07:15:19.271Z",
+      "due_date": null,
+      "start_date": null,
+      "web_url": "http://example.com/groups/documentcloud/-/milestones/1"
+    },
+    "assignee": {
+      "id": 1,
+      "name": "Administrator",
+      "username": "root",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+      "web_url": "http://example.com/root"
+    },
+    "labels": [{
+      "id": 11,
+      "name": "GroupLabel",
+      "color": "#428BCA",
+      "description": ""
+    }],
+    "weight": 4
+  }
+```
+
+## Delete a Group Issue Board **[PREMIUM]**
+
+Deletes a Group Issue Board.
+
+```
+DELETE /groups/:id/boards/:board_id
+```
+
+| 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 |
+| `board_id` | integer | yes | The ID of a board |
+
+```bash
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1
+```
+
 ## List board lists
 
 Get a list of the board's lists.
@@ -282,3 +535,5 @@ DELETE /groups/:id/boards/:board_id/lists/:list_id
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1
 ```
+
+[ee-5954]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5954

doc/api/group_milestones.md

@@ -136,3 +136,18 @@ Parameters:
 - `milestone_id` (required) - The ID of a group milestone
 
 [ce-12819]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12819
+
+## Get all burndown chart events for a single milestone **[STARTER]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1
+
+Get all burndown chart events for a single milestone.
+
+```
+GET /groups/:id/milestones/:milestone_id/burndown_events
+```
+
+Parameters:
+
+- `id` (required) - The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user
+- `milestone_id` (required) - The ID of a group milestone

doc/api/groups.md

@@ -70,8 +70,8 @@ GET /groups?statistics=true
       "repository_size" : 33,
       "wiki_size" : 100,
       "lfs_objects_size" : 123,
-      "job_artifacts_size" : 57
-
+      "job_artifacts_size" : 57,
+      "packages_size": 0
     }
   }
 ]
@@ -375,6 +375,16 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters:
+
+Additional response parameters: **[STARTER]**
+
+```json
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+```
+
 When adding the parameter `with_projects=false`, projects will not be returned.
 
 ```bash
@@ -412,13 +422,15 @@ Parameters:
 
 | 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. |
-| `parent_id` | integer | no | The parent group id for creating nested group. |
+| `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. |
+| `parent_id`                          | integer | no  | The parent group ID for creating nested group. |
+| `shared_runners_minutes_limit`       | integer | no  | **[STARTER ONLY]** Pipeline minutes quota for this group. |
+| `extra_shared_runners_minutes_limit` | integer | no  | **[STARTER ONLY]** Extra pipeline minutes quota for this group. |
 
 ## Transfer project to group
 
@@ -445,14 +457,18 @@ 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 |
-| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. |
-| `lfs_enabled` (optional) | 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. |
-| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from |
+| `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 |
+| `membership_lock`                    | boolean | no  | **[STARTER]** Prevent adding new members to project membership within this group |
+| `share_with_group_lock`              | boolean | no  | Prevent sharing a project with another group within this group |
+| `visibility`                         | string  | no  | The visibility level of the group. Can be `private`, `internal`, or `public`. |
+| `lfs_enabled` (optional)             | 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. |
+| `file_template_project_id`           | integer | no  | **[PREMIUM]** The ID of a project to load custom file templates from |
+| `shared_runners_minutes_limit`       | integer | no  | **[STARTER ONLY]** Pipeline minutes quota for this group |
+| `extra_shared_runners_minutes_limit` | integer | no  | **[STARTER ONLY]** Extra pipeline minutes quota for this group |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
@@ -520,7 +536,7 @@ Example response:
 
 ## Remove group
 
-Removes group with all projects inside.
+Removes group with all projects inside. Only available to group owners and administrators.
 
 ```
 DELETE /groups/:id
@@ -552,10 +568,62 @@ GET /groups?search=foobar
 ]
 ```
 
+## Sync group with LDAP **[CORE ONLY]**
+
+Syncs the group with its linked LDAP group. Only available to group owners and administrators.
+
+```
+POST /groups/:id/ldap_sync
+```
+
+Parameters:
+
+- `id` (required) - The ID or path of a user group
+
 ## Group members
 
 Please consult the [Group Members](members.md) documentation.
 
+### Add LDAP group link **[CORE ONLY]**
+
+Adds an LDAP group link.
+
+```
+POST /groups/:id/ldap_group_links
+```
+
+Parameters:
+
+- `id` (required) - The ID of a group
+- `cn` (required) - The CN of a LDAP group
+- `group_access` (required) - Minimum access level for members of the LDAP group
+- `provider` (required) - LDAP provider for the LDAP group
+
+### Delete LDAP group link **[CORE ONLY]**
+
+Deletes an LDAP group link.
+
+```
+DELETE /groups/:id/ldap_group_links/:cn
+```
+
+Parameters:
+
+- `id` (required) - The ID of a group
+- `cn` (required) - The CN of a LDAP group
+
+Deletes a LDAP group link for a specific LDAP provider
+
+```
+DELETE /groups/:id/ldap_group_links/:provider/:cn
+```
+
+Parameters:
+
+- `id` (required) - The ID of a group
+- `cn` (required) - The CN of a LDAP group
+- `provider` (required) - Name of a LDAP provider
+
 ## Namespaces in groups
 
 By default, groups only get 20 namespaces at a time because the API results are paginated.

doc/api/milestones.md

@@ -147,3 +147,18 @@ Parameters:
 
 - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
 - `milestone_id` (required) - The ID of a project milestone
+
+## Get all burndown chart events for a single milestone **[STARTER]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1
+
+Gets all burndown chart events for a single milestone.
+
+```
+GET /projects/:id/milestones/:milestone_id/burndown_events
+```
+
+Parameters:
+
+- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
+- `milestone_id` (required) - The ID of a project milestone

doc/api/namespaces.md

@@ -54,7 +54,21 @@ Example response:
 ]
 ```
 
-**Note**: `members_count_with_descendants` are presented only for group maintainers/owners.
+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**: Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **[BRONZE ONLY]**.
 
 ## Search for namespace
 

doc/api/notification_settings.md

 # Notification settings API
 
->**Note:** This feature was [introduced][ce-5632] in GitLab 8.12.
+>**Note:** This feature was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12.
 
 **Valid notification levels**
 
@@ -17,22 +17,22 @@ custom
 
 If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized:
 
-```
-new_note
-new_issue
-reopen_issue
-close_issue
-reassign_issue
-issue_due
-new_merge_request
-push_to_merge_request
-reopen_merge_request
-close_merge_request
-reassign_merge_request
-merge_merge_request
-failed_pipeline
-success_pipeline
-```
+- `new_note`
+- `new_issue`
+- `reopen_issue`
+- `close_issue`
+- `reassign_issue`
+- `issue_due`
+- `new_merge_request`
+- `push_to_merge_request`
+- `reopen_merge_request`
+- `close_merge_request`
+- `reassign_merge_request`
+- `merge_merge_request`
+- `failed_pipeline`
+- `success_pipeline`
+- `new_epic` **[ULTIMATE]**
+
 
 ## Global notification settings
 
@@ -85,6 +85,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
 | `merge_merge_request` | boolean | no | Enable/disable this notification |
 | `failed_pipeline` | boolean | no | Enable/disable this notification |
 | `success_pipeline` | boolean | no | Enable/disable this notification |
+| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** |
 
 Example response:
 
@@ -153,6 +154,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
 | `merge_merge_request` | boolean | no | Enable/disable this notification |
 | `failed_pipeline` | boolean | no | Enable/disable this notification |
 | `success_pipeline` | boolean | no | Enable/disable this notification |
+| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** |
 
 Example responses:
 
@@ -182,4 +184,17 @@ Example responses:
 }
 ```
 
-[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632
+Users on GitLab [Ultimate or Gold](https://about.gitlab.com/pricing/) will also see
+the `new_epic` parameter:
+
+```json
+{
+  "level": "custom",
+  "events": {
+    "new_note": true,
+    "new_issue": false,
+    "new_epic": false,
+    ...
+  }
+}
+```

doc/api/protected_branches.md

@@ -10,6 +10,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels`
 0  => No access
 30 => Developer access
 40 => Maintainer access
+60 => Admin access
 ```
 
 ## List protected branches
@@ -51,6 +52,36 @@ Example response:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
+
+Example response:
+
+```json
+[
+  {
+    "name": "master",
+    "push_access_levels": [
+      {
+        "access_level": 40,
+        "user_id": null,
+        "group_id": null,
+        "access_level_description": "Maintainers"
+      }
+    ],
+    "merge_access_levels": [
+      {
+        "access_level": null,
+        "user_id": null,
+        "group_id": 1234,
+        "access_level_description": "Example Merge Group"
+      }
+    ]
+  },
+  ...
+]
+```
+
 ## Get a single protected branch or wildcard protected branch
 
 Gets a single protected branch or wildcard protected branch.
@@ -88,6 +119,33 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
+
+Example response:
+
+```json
+{
+  "name": "master",
+  "push_access_levels": [
+    {
+      "access_level": 40,
+      "user_id": null,
+      "group_id": null,
+      "access_level_description": "Maintainers"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level": null,
+      "user_id": null,
+      "group_id": 1234,
+      "access_level_description": "Example Merge Group"
+    }
+  ]
+}
+```
+
 ## Protect repository branches
 
 Protects a single repository branch or several project repository
@@ -98,15 +156,47 @@ POST /projects/:id/protected_branches
 ```
 
 ```bash
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30'
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40'
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `name` | string | yes | The name of the branch or wildcard |
-| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) |
-| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) |
+| `id`                     | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `name`                   | string         | yes | The name of the branch or wildcard |
+| `push_access_level`      | string         | no  | Access levels allowed to push (defaults: `40`, maintainer access level) |
+| `merge_access_level`     | string         | no  | Access levels allowed to merge (defaults: `40`, maintainer access level) |
+| `unprotect_access_level` | string         | no  | Access levels allowed to unprotect (defaults: `40`, maintainer access level) |
+| `allowed_to_push`        | array          | no  | **[STARTER]** Array of access levels allowed to push, with each described by a hash |
+| `allowed_to_merge`       | array          | no  | **[STARTER]** Array of access levels allowed to merge, with each described by a hash |
+| `allowed_to_unprotect`   | array          | no  | **[STARTER]**Array of access levels allowed to unprotect, with each described by a hash |
+
+Example response:
+
+```json
+{
+  "name": "*-stable",
+  "push_access_levels": [
+    {
+      "access_level": 30,
+      "access_level_description": "Developers + Maintainers"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level": 30,
+      "access_level_description": "Developers + Maintainers"
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level": 40,
+      "access_level_description": "Maintainers"
+    }
+  ]
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `user_id` and `group_id` parameters:
 
 Example response:
 
@@ -116,13 +206,65 @@ Example response:
   "push_access_levels": [
     {
       "access_level": 30,
+      "user_id": null,
+      "group_id": null,
       "access_level_description": "Developers + Maintainers"
     }
   ],
   "merge_access_levels": [
     {
       "access_level": 30,
+      "user_id": null,
+      "group_id": null,
       "access_level_description": "Developers + Maintainers"
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level": 40,
+      "user_id": null,
+      "group_id": null,
+      "access_level_description": "Maintainers"
+    }
+  ]
+}
+```
+
+### Example with user / group level access **[STARTER]**
+
+Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
+form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE.
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1'
+```
+
+Example response:
+
+```json
+{
+  "name":"*-stable",
+  "push_access_levels": [
+    {
+      "access_level":null,
+      "user_id":1,
+      "group_id":null,
+      "access_level_description":"Administrator"
+    }
+  ],
+  "merge_access_levels": [
+    {
+      "access_level":40,
+      "user_id":null,
+      "group_id":null,
+      "access_level_description":"Maintainers"
+    }
+  ],
+  "unprotect_access_levels": [
+    {
+      "access_level":40,
+      "user_id":null,
+      "group_id":null,
+      "access_level_description":"Maintainers"
     }
   ]
 }
@@ -144,3 +286,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name` | string | yes | The name of the branch |
+
+[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity"

doc/api/users.md

@@ -223,6 +223,8 @@ Parameters:
 
 - `id` (required) - The ID of a user
 
+Example Responses:
+
 ```json
 {
   "id": 1,
@@ -264,6 +266,19 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: **[STARTER]**
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133
+  ...
+}
+```
+
 You can include the user's [custom attributes](custom_attributes.md) in the response with:
 
 ```
@@ -287,32 +302,30 @@ POST /users
 
 Parameters:
 
-- `email` (required)                 - Email
-- `password` (optional)              - Password
-- `reset_password` (optional)        - Send user password reset link - true or false (default)
-- `force_random_password` (optional) - Set user password to a random value - true or false (default)
-- `username` (required)              - Username
-- `name` (required)                  - Name
-- `skype` (optional)                 - Skype ID
-- `linkedin` (optional)              - LinkedIn
-- `twitter` (optional)               - Twitter account
-- `website_url` (optional)           - Website URL
-- `organization` (optional)          - Organization name
-- `projects_limit` (optional)        - Number of projects user can create
-- `extern_uid` (optional)            - External UID
-- `provider` (optional)              - External provider name
-- `group_id_for_saml` (optional)     - ID of group where SAML has been configured
-- `bio` (optional)                   - User's biography
-- `location` (optional)              - User's location
-- `public_email` (optional)          - The public email of the user
-- `admin` (optional)                 - User is admin - true or false (default)
-- `can_create_group` (optional)      - User can create groups - true or false
-- `skip_confirmation` (optional)     - Skip confirmation - true or false (default)
-- `external` (optional)              - Flags the user as external - true or false(default)
-- `avatar` (optional)                - Image file for user's avatar
-- `private_profile` (optional)       - User's profile is private - true or false
-- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
-- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
+- `email` (required)             - Email
+- `password` (optional)          - Password
+- `reset_password` (optional)    - Send user password reset link - true or false(default)
+- `username` (required)          - Username
+- `name` (required)              - Name
+- `skype` (optional)             - Skype ID
+- `linkedin` (optional)          - LinkedIn
+- `twitter` (optional)           - Twitter account
+- `website_url` (optional)       - Website URL
+- `organization` (optional)      - Organization name
+- `projects_limit` (optional)    - Number of projects user can create
+- `extern_uid` (optional)        - External UID
+- `provider` (optional)          - External provider name
+- `bio` (optional)               - User's biography
+- `location` (optional)          - User's location
+- `public_email` (optional)      - The public email of the user
+- `admin` (optional)             - User is admin - true or false (default)
+- `can_create_group` (optional)  - User can create groups - true or false
+- `skip_confirmation` (optional) - Skip confirmation - true or false (default)
+- `external` (optional)          - Flags the user as external - true or false(default)
+- `avatar` (optional)            - Image file for user's avatar
+- `private_profile` (optional)   - User's profile is private - true or false
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **[STARTER]**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]**
 
 ## User modification
 
@@ -348,6 +361,8 @@ Parameters:
 - `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
 - `avatar` (optional)              - Image file for user's avatar
 - `private_profile` (optional)     - User's profile is private - true or false
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **[STARTER]**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]**
 
 On password update, user will be forced to change it upon next login.
 Note, at the moment this method does only return a `404` error,