bcf77cb795
* add identifier for troubleshooting pages * mention mutes can be temporary now * bell for notifications * convert images to jpg and rename them * suspensions now reversible * unread notifications * suspended: true * mutes expiry * replies_policy, type of notification * notify * featuredTags AP representation * new env vars * accounts merge * maintenance cli * list replies * suspended flag * follower sync * minor formatting * add note about idempotency of follow action * account featured tags, min_id and max_id, plus normalization * follow marcin and nightpool's suggestion * bearcaps * replies_policy update * featuredtags now have a url
16 KiB
| title | description | menu | ||||||
|---|---|---|---|---|---|---|---|---|
| lists | View and manage lists. See also: /api/v1/timelines/list/id for loading a list timeline. |
|
{{< 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",
"replies_policy": "followed"
},
{
"id": "13585",
"title": "test",
"replies_policy": "list"
}
]
{{< 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, and which replies to show within that 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",
"replies_policy": "followed"
}
{{< 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
3.3.0 - added replies_policy
{{< 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 >}}
{{< api-method-parameter name="replies_policy" type="string" required=false >}}
Enumerable oneOf followed list none. Defaults to 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 >}}
A list was created successfully with title=test {{< endapi-method-response-example-description >}}
{
"id": "13585",
"title": "test",
"replies_policy": "list"
}
{{< 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, or which replies to show.
Returns: List
OAuth: User token + write:lists
Version history:
2.1.0 - added
3.3.0 - added replies_policy
{{< 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=false >}}
The title of the list to be updated.
{{< endapi-method-parameter >}}
{{< api-method-parameter name="replies_policy" type="string" required=false >}}
Enumerable oneOf followed list none.
{{< 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",
"replies_policy": "list"
}
{{< 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 >}}