> For the complete documentation index, see [llms.txt](https://mastodon.gitbook.io/mastodon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mastodon.gitbook.io/mastodon/jp/methods/timelines/lists.md).

# lists

View and manage lists. See also: /api/v1/timelines/list/id for loading a list timeline.

## Show user's lists

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/lists`

Fetch all lists that the user owns.\
\
**Returns:** Array of List\
**OAuth:** User token + `read:lists`\
**Version history:**\
2.1.0 - added

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Use id as a parameter for related API calls." %}

```javascript
[
  {
    "id": "12249",
    "title": "Friends"
  }
]
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Show a single list

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/lists/:id`

Fetch the list with the given ID. Used for verifying the title of a list.\
\
**Returns:** List\
**OAuth:** User token + `read:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the list in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 The list 12249 exists and is owned by you" %}

```javascript
{
  "id": "12249",
  "title": "Friends"
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="404 If the ID does not exist or is not owned by you" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}
{% endtabs %}

## Create a list

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/lists`

Create a new list.\
\
**Returns:** List\
**OAuth:** User token + `write:lists`\
**Version history:**\
2.1.0 - added

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name  | Type   | Description                          |
| ----- | ------ | ------------------------------------ |
| title | string | The title of the list to be created. |

{% tabs %}
{% tab title="200 A list was created successfully with title=test" %}

```javascript
{
  "id": "13585",
  "title": "test"
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Update a list

<mark style="color:orange;">`PUT`</mark> `https://mastodon.example/api/v1/lists/:id`

Change the title of a list.\
\
**Returns:** List\
**OAuth:** User token + `write:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the list in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name  | Type   | Description                          |
| ----- | ------ | ------------------------------------ |
| title | string | The title of the list to be updated. |

{% tabs %}
{% tab title="200 The title of list 13585 was successfully updated to title=testing" %}

```javascript
{
  "id": "13585",
  "title": "testing"
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="422 If the title is blank" %}

```javascript
{
  "error": "Validation failed: Title can't be blank"
}
```

{% endtab %}
{% endtabs %}

## Delete a list

<mark style="color:red;">`DELETE`</mark> `https://mastodon.example/api/v1/lists/:id`

**Returns:** empty object\
**OAuth:** User token + `write:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the list in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 An empty object will be returned if the list was successfully deleted" %}

```javascript
{}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="404 ID does not exist or is not owned by you" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Accounts in a list

## View accounts in list

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/lists/:id/accounts`

**Returns:** Array of Account\
**OAuth:** User token + `read:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the list in the database |

#### Query Parameters

| Name      | Type   | Description                                                                                                                                                |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| max\_id   | string | Internal parameter. Use HTTP Link header for pagination.                                                                                                   |
| since\_id | string | Internal parameter. Use HTTP Link header for pagination.                                                                                                   |
| limit     | number | Maximum number of results. Defaults to 40. Max 40. Set to 0 in order to get all accounts without pagination. Pagination is done with the HTTP Link header. |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "id": "952529",
    ...
  },
  {
    "id": "917388",
    ...
  },
  {
    "id": "869022",
    ...
  },
  {
    "id": "832844",
    ...
  },
  {
    "id": "482403",
    ...
  }
]
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="404 The list ID does not exist or is not owned by you" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}
{% endtabs %}

## Add accounts to list

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/lists/:id/accounts`

Add accounts to the given list. Note that the user must be following these accounts.\
\
**Returns:** empty object\
**OAuth:** User token + `write:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the list in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name         | Type  | Description                              |
| ------------ | ----- | ---------------------------------------- |
| account\_ids | array | Array of account IDs to add to the list. |

{% tabs %}
{% tab title="200 " %}

```javascript
{}
```

{% endtab %}

{% tab title="401 " %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="404 You are not following a given account ID, or you do not own the list ID, or list/account ID does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="422 Account is already in list" %}

```javascript
{
  "error": "Validation failed: Account has already been taken"
}
```

{% endtab %}
{% endtabs %}

## Remove accounts from list

<mark style="color:red;">`DELETE`</mark> `https://mastodon.example/api/v1/lists/:id/accounts`

Remove accounts from the given list.\
\
**Returns:** empty object\
**OAuth:** User token + `write:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the list in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name         | Type  | Description                                   |
| ------------ | ----- | --------------------------------------------- |
| account\_ids | array | Array of account IDs to remove from the list. |

{% tabs %}
{% tab title="200 Account was successfully removed from the list, or it was already not in the list." %}

```javascript
{}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="404 List ID is not owned by you or does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}
{% endtabs %}