# Add a folder

`POST /api/v1/vaults/{vault}/knowledge/folders`

Add a folder to a vault's Knowledge, after the folders already there.

The change is written to the account log.

## Parameters

- `vault` (string, required): The vault, named either by the readable name it reports as slug or by its id. A vault of another account answers 404.
- `name` (string, required): What the folder is called, up to 255 characters. Markup is stripped, and a name left empty once it is stripped is refused with “Give the folder a name.”

## Returns

The knowledge folder object that was added.

- `data` (object): The knowledge folder, which holds nothing yet, so its notes and lists are empty.
- `data.type` (string): Always knowledge_folder.
- `data.id` (string): The id of the folder, which every address naming it takes.
- `data.attributes` (object): Everything the folder holds.
- `data.attributes.name` (string): What the folder is called.
- `data.attributes.position` (integer): Where the folder stands among the folders of the vault, from 1.
- `data.attributes.note_count` (integer): How many notes the folder holds.
- `data.attributes.list_count` (integer): How many lists the folder holds.
- `data.attributes.notes` (array): The notes the folder holds.
- `data.attributes.lists` (array): The lists the folder holds.
- `data.attributes.created_at` (timestamp): When the folder was added, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds, or null.
- `data.links` (object): Where to find the folder. A folder is not read on its own, so it has no address of its own.
- `data.links.web` (string): The Knowledge screen of the vault in the application, which opens for somebody signed in rather than for a key.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/knowledge/folders \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Warehouse"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/knowledge/folders', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Warehouse',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/knowledge/folders', [
    'name' => 'Warehouse',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "knowledge_folder",
        "id": "c6f13a58-4e92-4b07-a1d3-5f8e2c9b7a60",
        "attributes": {
            "name": "Warehouse",
            "position": 2,
            "note_count": 0,
            "list_count": 0,
            "notes": [],
            "lists": [],
            "created_at": 1773417600,
            "updated_at": 1773417600
        },
        "links": {
            "web": "https://my.monicahq.com/vaults/dunder-mifflin/knowledge"
        }
    }
}
```
