The Wayback Machine - https://web.archive.org/web/20220127144847/https://docs.joinmastodon.org/methods/timelines/lists/

lists

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

get
Show user's lists

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

Request

Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

Use id as a parameter for related API calls.

[
  {
    "id": "12249",
    "title": "Friends",
    "replies_policy": "followed"
  },
  {
  "id": "13585",
  "title": "test",
  "replies_policy": "list"
  }
]

401: Unauthorized

Invalid or missing Authorization header

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

get
Show a single list

https://mastodon.example/api/v1/lists/:id

Fetch the list with the given ID. Used for verifying the title of a list, and which replies to show within that list.

Returns: List
OAuth: User token + read:lists
Version history:
2.1.0 - added

Request

Path Parameters
:id
required
string
ID of the list in the database
Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

The list 12249 exists and is owned by you

{
  "id": "12249",
  "title": "Friends",
  "replies_policy": "followed"
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

If the ID does not exist or is not owned by you

{
  "error": "Record not found"
}

post
Create a list

https://mastodon.example/api/v1/lists

Create a new list.

Returns: List
OAuth: User token + write:lists
Version history:
2.1.0 - added
3.3.0 - added replies_policy

Request

Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
title
required
string
The title of the list to be created.
replies_policy
optional
string
Enumerable oneOf followed list none. Defaults to list.

Response

200: Success

A list was created successfully with title=test

{
  "id": "13585",
  "title": "test",
  "replies_policy": "list"
}

401: Unauthorized

Invalid or missing Authorization header

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

put
Update a list

https://mastodon.example/api/v1/lists/:id

Change the title of a list, or which replies to show.

Returns: List
OAuth: User token + write:lists
Version history:
2.1.0 - added
3.3.0 - added replies_policy

Request

Path Parameters
:id
required
string
ID of the list in the database
Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
title
optional
string
The title of the list to be updated.
replies_policy
optional
string
Enumerable oneOf followed list none.

Response

200: Success

The title of list 13585 was successfully updated to title=testing

{
  "id": "13585",
  "title": "testing",
  "replies_policy": "list"
}

401: Unauthorized

Invalid or missing Authorization header

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

422: Unprocessable Entity

If the title is blank

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

delete
Delete a list

https://mastodon.example/api/v1/lists/:id

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

Request

Path Parameters
:id
required
string
ID of the list in the database
Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

An empty object will be returned if the list was successfully deleted

{}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

ID does not exist or is not owned by you

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

Accounts in a list

get
View accounts in list

https://mastodon.example/api/v1/lists/:id/accounts

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

Request

Path Parameters
:id
required
string
ID of the list in the database
Headers
Authorization
required
string
Bearer <user token>
Query Parameters
max_id
optional
string
Internal parameter. Use HTTP Link header for pagination.
since_id
optional
string
Internal parameter. Use HTTP Link header for pagination.
limit
optional
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.

Response

200: Success
[
  {
    "id": "952529",
    ...
  },
  {
    "id": "917388",
    ...
  },
  {
    "id": "869022",
    ...
  },
  {
    "id": "832844",
    ...
  },
  {
    "id": "482403",
    ...
  }
]

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

The list ID does not exist or is not owned by you

{
  "error": "Record not found"
}

post
Add accounts to list

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

Request

Path Parameters
:id
required
string
ID of the list in the database
Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
account_ids
required
array
Array of account IDs to add to the list.

Response

200: Success
{}

401: Unauthorized
{
  "error": "The access token is invalid"
}

404: Not Found

You are not following a given account ID, or you do not own the list ID, or list/account ID does not exist

{
  "error": "Record not found"
}

422: Unprocessable Entity

Account is already in list

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

delete
Remove accounts from list

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

Request

Path Parameters
:id
required
string
ID of the list in the database
Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
account_ids
required
array
Array of account IDs to remove from the list.

Response

200: Success

Account was successfully removed from the list, or it was already not in the list.

{}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

List ID is not owned by you or does not exist

{
  "error": "Record not found"
}

Last updated December 27, 2020 · Improve this page