> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/bitwarden/server/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders API

> Organize vault items with folders

## Overview

Folders help organize personal vault items. They are user-specific and not shared across organizations.

<Info>
  Folders are only available for personal vault items, not organization items.
</Info>

## Get Folder

Retrieve a specific folder by ID.

```bash theme={null}
GET /folders/{id}
```

<ParamField path="id" type="string" required>
  The folder ID
</ParamField>

### Response

<ResponseField name="id" type="string" required>
  Folder unique identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Encrypted folder name
</ResponseField>

<ResponseField name="revisionDate" type="string" required>
  Last modification timestamp
</ResponseField>

***

## List All Folders

Retrieve all folders for the authenticated user.

```bash theme={null}
GET /folders
```

### Response

Returns a list of all folders belonging to the user.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.bitwarden.com/folders" \
    -H "Authorization: Bearer {access_token}"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.bitwarden.com/folders', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  const folders = await response.json();
  ```
</CodeGroup>

***

## Create Folder

Create a new folder.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.bitwarden.com/folders" \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "2.encrypted_folder_name"
    }'
  ```

  ```javascript JavaScript theme={null}
  const folder = await fetch('https://api.bitwarden.com/folders', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: '2.encrypted_folder_name'
    })
  });
  ```
</CodeGroup>

### Request Body

<ParamField body="name" type="string" required>
  Encrypted folder name
</ParamField>

### Response

Returns the created folder object with its generated ID.

***

## Update Folder

Update an existing folder's name.

```bash theme={null}
PUT /folders/{id}
```

<ParamField path="id" type="string" required>
  The folder ID to update
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  New encrypted folder name
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.bitwarden.com/folders/{id}" \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "2.new_encrypted_name"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://api.bitwarden.com/folders/${folderId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: '2.new_encrypted_name'
    })
  });
  ```
</CodeGroup>

***

## Delete Folder

Delete a folder permanently.

```bash theme={null}
DELETE /folders/{id}
```

<ParamField path="id" type="string" required>
  The folder ID to delete
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.bitwarden.com/folders/{id}" \
    -H "Authorization: Bearer {access_token}"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://api.bitwarden.com/folders/${folderId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  ```
</CodeGroup>

<Warning>
  Deleting a folder does not delete the items in it. Items will be moved to "No Folder".
</Warning>

***

## Delete All Folders

Delete all folders for the authenticated user.

```bash theme={null}
DELETE /folders/all
```

<Warning>
  This will delete all your folders. Items in folders will be moved to "No Folder". This action cannot be undone.
</Warning>

***

## Folder Organization

### Best Practices

1. **Use Descriptive Names**: Name folders clearly to easily find items
2. **Don't Nest**: Folders are flat - use naming conventions like "Work - Email" for logical grouping
3. **Limit Count**: Too many folders can make organization difficult
4. **Use Collections Instead**: For shared items, use organization collections

### Folders vs Collections

| Feature     | Folders               | Collections              |
| ----------- | --------------------- | ------------------------ |
| Scope       | Personal items only   | Organization items       |
| Sharing     | Not shared            | Shared with groups/users |
| Permissions | User has full control | Role-based access        |
| Visibility  | User only             | Organization members     |

***

## Encryption

<Info>
  Folder names are encrypted client-side before being sent to the server.
</Info>

The `name` field must be encrypted using the user's encryption key. The format is:

```
{encType}.{encryptedData}|{iv}|{mac}
```

Example:

```
2.abc123def456|789ghi012|345jkl678
```

***

## Moving Items to Folders

To move items into folders, use the Ciphers API:

```bash theme={null}
PUT /ciphers/{cipherId}/partial
```

With body:

```json theme={null}
{
  "folderId": "folder-guid-here"
}
```

See [Ciphers API](/api/vault/ciphers) for details.