zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity
documentation/content/en/methods/timelines/lists.md

15 KiB
Raw Blame History

title description menu
lists View and manage lists. See also: /api/v1/timelines/list/id for loading a list timeline.
docs
weight parent
20 methods-timelines

{{< api-method method="get" host="https://mastodon.example" path="/api/v1/lists" title="Show user's lists" >}} {{< api-method-description >}}

Fetch all lists that the user owns.

Returns: Array of List
OAuth: User token + read:lists
Version history:

  • 2.1.0 - added

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}}

Use id as a parameter for related API calls. {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} {{< api-method method="get" host="https://mastodon.example" path="/api/v1/lists/:id" title="Show a single list" >}} {{< api-method-description >}}

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

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-path-parameters >}} {{< api-method-parameter name=":id" type="string" required=true >}} ID of the list in the database {{< endapi-method-parameter >}} {{< endapi-method-path-parameters >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}}

The list 12249 exists and is owned by you {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=404 >}} {{< api-method-response-example-description >}}

If the ID does not exist or is not owned by you {{< endapi-method-response-example-description >}}

{
  "error": "Record not found"
}

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} {{< api-method method="post" host="https://mastodon.example" path="/api/v1/lists" title="Create a list" >}} {{< api-method-description >}}

Create a new list.

Returns: List
OAuth: User token + write:lists
Version history:

  • 2.1.0 - added

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< api-method-form-data-parameters >}} {{< api-method-parameter name="title" type="string" required=true >}} The title of the list to be created. {{< endapi-method-parameter >}} {{< endapi-method-form-data-parameters >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}}

A list was created successfully with title=test {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} {{< api-method method="put" host="https://mastodon.example" path="/api/v1/lists/:id" title="Update a list" >}} {{< api-method-description >}}

Change the title of a list.

Returns: List
OAuth: User token + write:lists
Version history:

  • 2.1.0 - added

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-path-parameters >}} {{< api-method-parameter name=":id" type="string" required=true >}} ID of the list in the database {{< endapi-method-parameter >}} {{< endapi-method-path-parameters >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< api-method-form-data-parameters >}} {{< api-method-parameter name="title" type="string" required=true >}} The title of the list to be updated. {{< endapi-method-parameter >}} {{< endapi-method-form-data-parameters >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}}

The title of list 13585 was successfully updated to title=testing {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=422 >}} {{< api-method-response-example-description >}}

If the title is blank {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} {{< api-method method="delete" host="https://mastodon.example" path="/api/v1/lists/:id" title="Delete a list" >}} {{< api-method-description >}}

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

  • 2.1.0 - added

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-path-parameters >}} {{< api-method-parameter name=":id" type="string" required=true >}} ID of the list in the database {{< endapi-method-parameter >}} {{< endapi-method-path-parameters >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}}

An empty object will be returned if the list was successfully deleted {{< endapi-method-response-example-description >}}

{}

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=404 >}} {{< api-method-response-example-description >}}

ID does not exist or is not owned by you {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}}

Accounts in a list

{{< api-method method="get" host="https://mastodon.example" path="/api/v1/lists/:id/accounts" title="View accounts in list" >}} {{< api-method-description >}}

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

  • 2.1.0 - added

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-path-parameters >}} {{< api-method-parameter name=":id" type="string" required=true >}} ID of the list in the database {{< endapi-method-parameter >}} {{< endapi-method-path-parameters >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< api-method-query-parameters >}} {{< api-method-parameter name="max_id" type="string" required=false >}} Internal parameter. Use HTTP Link header for pagination. {{< endapi-method-parameter >}} {{< api-method-parameter name="since_id" type="string" required=false >}} Internal parameter. Use HTTP Link header for pagination. {{< endapi-method-parameter >}} {{< api-method-parameter name="limit" type="number" required=false >}} 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. {{< endapi-method-parameter >}} {{< endapi-method-query-parameters >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}} {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=404 >}} {{< api-method-response-example-description >}}

The list ID does not exist or is not owned by you {{< endapi-method-response-example-description >}}

{
  "error": "Record not found"
}

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} {{< api-method method="post" host="https://mastodon.example" path="/api/v1/lists/:id/accounts" title="Add accounts to list" >}} {{< api-method-description >}}

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

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-path-parameters >}} {{< api-method-parameter name=":id" type="string" required=true >}} ID of the list in the database {{< endapi-method-parameter >}} {{< endapi-method-path-parameters >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< api-method-form-data-parameters >}} {{< api-method-parameter name="account_ids" type="array" required=true >}} Array of account IDs to add to the list. {{< endapi-method-parameter >}} {{< endapi-method-form-data-parameters >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}} {{< endapi-method-response-example-description >}}

{}

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}} {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=404 >}} {{< api-method-response-example-description >}}

You are not following a given account ID, or you do not own the list ID, or list/account ID does not exist {{< endapi-method-response-example-description >}}

{
  "error": "Record not found"
}

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=422 >}} {{< api-method-response-example-description >}}

Account is already in list {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} {{< api-method method="delete" host="https://mastodon.example" path="/api/v1/lists/:id/accounts" title="Remove accounts from list" >}} {{< api-method-description >}}

Remove accounts from the given list.

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

  • 2.1.0 - added

{{< endapi-method-description >}} {{< api-method-spec >}} {{< api-method-request >}} {{< api-method-path-parameters >}} {{< api-method-parameter name=":id" type="string" required=true >}} ID of the list in the database {{< endapi-method-parameter >}} {{< endapi-method-path-parameters >}} {{< api-method-headers >}} {{< api-method-parameter name="Authorization" type="string" required=true >}} Bearer <user token> {{< endapi-method-parameter >}} {{< endapi-method-headers >}} {{< api-method-form-data-parameters >}} {{< api-method-parameter name="account_ids" type="array" required=true >}} Array of account IDs to remove from the list. {{< endapi-method-parameter >}} {{< endapi-method-form-data-parameters >}} {{< endapi-method-request >}} {{< api-method-response >}} {{< api-method-response-example httpCode=200 >}} {{< api-method-response-example-description >}}

Account was successfully removed from the list, or it was already not in the list. {{< endapi-method-response-example-description >}}

{}

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=401 >}} {{< api-method-response-example-description >}}

Invalid or missing Authorization header {{< endapi-method-response-example-description >}}

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

{{< endapi-method-response-example >}} {{< api-method-response-example httpCode=404 >}} {{< api-method-response-example-description >}}

List ID is not owned by you or does not exist {{< endapi-method-response-example-description >}}

{
  "error": "Record not found"
}

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}}