# Add folder members or change their roles

`POST /folder.addMembers`

## Description

Add up to 100 people to a folder with the same role, or change the role
of people who are already members. `admin` members can manage the folder;
`viewer` members can see it and everything filed in it. Demoting the last
`admin` to `viewer` returns `409` `conflict`.

**Access:** Organization and Personal. Personal tokens need the `admin` role
on the folder: a viewer gets `403` `access_denied`, and a folder the token's
owner does not belong to returns `404` `folder_not_found`. Organization
tokens can change every folder in the account. Members must be people in the
folder's account.

**Required scope:** `folders:write`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Folder ID. |
| `userIds` | string[] | Yes | User IDs of the people to add or update. |
| `role` | "admin" | "viewer" | No | Role to give every listed person. |

### Example Request

```json
{
  "id": "019a0000-0000-7000-8000-0000000000f1",
  "userIds": [
    "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
    "af6663d5-0f37-4105-95df-4fea20ef7c7c"
  ],
  "role": "viewer"
}
```

## Responses

### 200 - Members added or updated

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ok` | "true" | Yes | Always `true` on success. See [Responses and Errors](/docs/guides/responses-and-errors). |


#### Example Response

```json
{
  "ok": true
}
```

### 400 - Bad request. Common causes:
- Missing or invalid `id` (`missing_parameter` / `invalid_parameter`)
- Missing or empty `userIds`, more than 100 IDs, or an ID that is not a UUID (`missing_parameter` / `invalid_parameter`)
- `role` is not `admin` or `viewer` (`invalid_parameter`)
- Malformed JSON body or an unknown field (`invalid_json`)


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Common causes:
- Token is missing `folders:write` (`missing_scope`)
- Personal token whose owner is a viewer, not an admin, of the folder (`access_denied`)


### 404 - Not found. Common causes:
- Folder not found, or not visible to the caller (`folder_not_found`)
- A user ID that is not a person in the folder's account (`user_not_found` with `param: userIds`)


### 405 - An unsupported method was requested.

### 409 - The change would leave the folder without an `admin` (`conflict`).

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/folder-add-members*