# Change a list

`PUT /api/v1/vaults/{vault}/knowledge/lists/{list}`

Change the title, the description or the folder of a list.

A field left out keeps its value. A title left empty keeps the one the list had, and a description sent as null or empty clears it.

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.
- `list` (uuid, required): The id of the list. A list of another vault or of another account answers 404.
- `title` (string, optional): The new title, up to 255 characters.
- `description` (string, optional): What the list is for, in Markdown, up to 5,000 characters.
- `folder_id` (uuid, optional): The folder to move the list to. The id of a folder of the vault, as the knowledge folders endpoints give it. A folder of another vault answers 404.

## Returns

The knowledge list object as it now reads. A list of another vault or of another account answers 404.

- `data` (object): The knowledge list.
- `data.type` (string): Always knowledge_list. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.title` (string): The title of the list.
- `data.attributes.description` (string): What the list is for, in Markdown as written, or null.
- `data.attributes.folder` (object): The folder the list sits in.
- `data.attributes.folder.id` (uuid): The id of the folder, as the knowledge folders endpoints give it.
- `data.attributes.folder.name` (string): What the folder is called.
- `data.attributes.created_at` (timestamp): When the list was started, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it, one of its columns or one of its items last changed, as a count of seconds, or null.
- `data.attributes.columns` (array): The columns of the list, in their order. A list always has at least one.
- `data.attributes.columns[]` (object): One column.
- `data.attributes.columns[].id` (uuid): The id of the column, which the columns endpoints and the cells of an item take.
- `data.attributes.columns[].name` (string): What the column is called.
- `data.attributes.columns[].position` (integer): Where the column stands, from 1.
- `data.attributes.items` (array): The items of the list, in their order.
- `data.attributes.items[]` (object): One item.
- `data.attributes.items[].id` (uuid): The id of the item, which the items endpoints take.
- `data.attributes.items[].position` (integer): Where the item stands, from 1.
- `data.attributes.items[].cells` (object): The texts of the item in Markdown, keyed by the id of their column. A blank cell is left out.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.
- `data.links.web` (string): The list in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

## 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/lists/e94b1c37-6a28-4d50-8b3f-2c7e9a4d1f68 \
  -X PUT \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "Who buys from the **Scranton** branch."
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/knowledge/lists/e94b1c37-6a28-4d50-8b3f-2c7e9a4d1f68', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    description: 'Who buys from the **Scranton** branch.',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/knowledge/lists/e94b1c37-6a28-4d50-8b3f-2c7e9a4d1f68', [
    'description' => 'Who buys from the **Scranton** branch.',
]);
```

## Response

`200`

```json
{
    "data": {
        "type": "knowledge_list",
        "id": "e94b1c37-6a28-4d50-8b3f-2c7e9a4d1f68",
        "attributes": {
            "title": "Paper clients",
            "description": "Who buys from the **Scranton** branch.",
            "folder": {
                "id": "2b7e4c91-0d5a-4f38-9c16-8e3a7f1b5d24",
                "name": "Office"
            },
            "columns": [
                {
                    "id": "5d3a8f12-7c49-4e60-b2a1-9f6e3c8d4b75",
                    "name": "Name",
                    "position": 1
                },
                {
                    "id": "a18c6e43-2f97-4b5d-8e01-7c3b9a6f2d84",
                    "name": "City",
                    "position": 2
                },
                {
                    "id": "0f7b2d95-3e61-4a8c-9d47-6b1e8c5a3f29",
                    "name": "Note",
                    "position": 3
                }
            ],
            "items": [
                {
                    "id": "8e4f1a76-5c23-4d9b-a0e8-2b7d6f3c1e54",
                    "position": 1,
                    "cells": {
                        "5d3a8f12-7c49-4e60-b2a1-9f6e3c8d4b75": "Blue Cross of Pennsylvania",
                        "a18c6e43-2f97-4b5d-8e01-7c3b9a6f2d84": "Scranton"
                    }
                },
                {
                    "id": "3c9d7b28-1f54-4e8a-b6c0-5a2e9d4f7b13",
                    "position": 2,
                    "cells": {
                        "5d3a8f12-7c49-4e60-b2a1-9f6e3c8d4b75": "Harper Collins",
                        "0f7b2d95-3e61-4a8c-9d47-6b1e8c5a3f29": "Lost to Prince Family Paper, won back"
                    }
                }
            ],
            "created_at": 1773331200,
            "updated_at": 1773417600
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/knowledge/lists/e94b1c37-6a28-4d50-8b3f-2c7e9a4d1f68",
            "web": "https://my.monicahq.com/vaults/dunder-mifflin/knowledge/lists/e94b1c37-6a28-4d50-8b3f-2c7e9a4d1f68"
        }
    }
}
```
