lists

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

Show user's lists

GET 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>

200 Use id as a parameter for related API calls.

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

401 Invalid or missing Authorization header

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

Show a single list

GET 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>

200 The list 12249 exists and is owned by you

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

401 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Create a list

POST 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.

200 A list was created successfully with title=test

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

401 Invalid or missing Authorization header

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

Update a list

PUT 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.

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

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

401 Invalid or missing Authorization header

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

422 If the title is blank

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

Delete a list

DELETE 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>

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

{}

401 Invalid or missing Authorization header

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

404 ID does not exist or is not owned by you

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

Accounts in a list

View accounts in list

GET 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>

200

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

401 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Add accounts to list

POST 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.

200

{}

401

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

404 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 Account is already in list

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

Remove accounts from list

DELETE 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.

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

{}

401 Invalid or missing Authorization header

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

404 List ID is not owned by you or does not exist

{
  "error": "Record not found"
}