lists.md 2.74 KB
Newer Older
Eugen Rochko's avatar
Eugen Rochko committed
1
---
Eugen Rochko's avatar
Eugen Rochko committed
2
title: Lists
Eugen Rochko's avatar
Eugen Rochko committed
3 4
menu:
  docs:
Eugen Rochko's avatar
Eugen Rochko committed
5
    parent: rest-api
Eugen Rochko's avatar
Eugen Rochko committed
6 7
    weight: 10
---
Eugen Rochko's avatar
Eugen Rochko committed
8 9 10 11 12 13 14 15 16

## GET /api/v1/lists

User's lists.

Returns array of [List]({{< relref "entities.md#list" >}})

### Resource information

17
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
18 19 20 21 22 23 24 25 26

## GET /api/v1/accounts/:id/lists

User's lists that a given account is part of.

Returns array of [List]({{< relref "entities.md#list" >}})

### Resource information

27
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
28 29 30 31 32 33 34 35 36

## GET /api/v1/lists/:id/accounts

Accounts that are in a given list.

Returns array of [Account]({{< relref "entities.md#account" >}})

### Resource information

37
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |

### Pagination

>If you specify a `limit` of `0` in the query, all accounts will be returned without pagination. Otherwise, standard account pagination rules apply.

{{< api_pagination >}}

## GET /api/v1/lists/:id

Returns [List]({{< relref "entities.md#list" >}})

### Resource information

57
{{< api_method_info auth="Yes" user="Yes" scope="read read:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
58 59 60 61 62 63 64 65 66

## POST /api/v1/lists

Create a new list.

Returns [List]({{< relref "entities.md#list" >}})

### Resource information

67
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
68 69 70

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
71 72 73
|Name|Description|Required|
|----|-----------|:------:|
| `title` | The title of the list | Required |
Eugen Rochko's avatar
Eugen Rochko committed
74 75 76 77 78 79 80 81 82

## PUT /api/v1/lists/:id

Update a list.

Returns [List]({{< relref "entities.md#list" >}})

### Resource information

83
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
84 85 86

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
87 88 89
|Name|Description|Required|
|----|-----------|:------:|
| `title` | The title of the list | Required |
Eugen Rochko's avatar
Eugen Rochko committed
90 91 92 93 94 95 96

## DELETE /api/v1/lists/:id

Remove a list.

### Resource information

97
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
98 99 100 101 102 103 104 105 106

## POST /api/v1/lists/:id/accounts

Add accounts to a list.

> Only accounts already followed by the user can be added to a list.

### Resource information

107
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
108 109 110

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
111 112 113
|Name|Description|Required|
|----|-----------|:------:|
| `account_ids` | Array of account IDs | Required |
Eugen Rochko's avatar
Eugen Rochko committed
114 115 116 117 118 119 120

## DELETE /api/v1/lists/:id/accounts

Remove accounts from a list.

### Resource information

121
{{< api_method_info auth="Yes" user="Yes" scope="write write:lists" version="2.1.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
122 123 124

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
125 126 127
|Name|Description|Required|
|----|-----------|:------:|
| `account_ids` | Array of account IDs | Required |