2022-11-20 07:34:38 +01:00
---
title: suggestions API methods
description: >-
Server-generated suggestions on who to follow, based on previous positive
interactions.
menu:
docs:
weight: 120
name: suggestions
parent: methods-accounts
identifier: methods-suggestions
aliases: [
"/methods/suggestions",
"/api/methods/suggestions",
"/methods/accounts/suggestions",
]
---
< style >
#TableOfContents ul ul ul {display: none}
< / style >
## View follow suggestions (v2) {#v2}
```http
2022-12-14 22:55:30 +01:00
GET /api/v2/suggestions HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Accounts that are promoted by staff, or that the user has had past positive interactions with, but is not yet following.
**Returns:** Array of [Suggestion ]({{< relref "entities/Suggestion" >}} )\
**OAuth:** User token + `read` \
**Version history:**\
3.4.0 - added
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
limit
2022-12-14 22:55:30 +01:00
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
```json
[
{
"source": "past_interactions",
"account": {
"id": "784058",
"username": "katie",
"acct": "katie@pleroma.voidlurker.net",
// ...
},
// ...
{
"source": "global",
"account": {
"id": "108194863260762493",
"username": "thunderbird",
"acct": "thunderbird@mastodon.online",
// ...
}
]
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
---
## Remove a suggestion {#remove}
```http
2022-12-14 22:55:30 +01:00
DELETE /api/v1/suggestions/:account_id HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Remove an account from follow suggestions.
**Returns:** n/a\
**OAuth:** User token + `read` \
**Version history:**\
2.4.3 - added
#### Request
##### Path parameters
:account_id
: {{< required > }} String. The ID of the Account in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
A successful call will return an empty object. Note the call will be successful even if the account id provided is invalid or is not a suggested account.
```json
{}
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
---
## (DEPRECATED) View follow suggestions (v1) {#v1}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/suggestions HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Accounts the user has had past positive interactions with, but is not yet following.
**Returns:** Array of [Account ]({{< relref "entities/Account" >}} )\
**OAuth:** User token + `read` \
**Version history:**\
2.4.3 - added\
3.4.0 - deprecated
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
limit
2022-12-14 22:55:30 +01:00
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
```json
[
{
"id": "332766",
"username": "kaniini",
"acct": "kaniini@pleroma.site",
// ...
},
{
"id": "689455",
"username": "interneteh",
"acct": "interneteh@sunbeam.city",
// ...
},
{
"id": "764276",
"username": "Dee",
"acct": "Dee@fedi.underscore.world",
// ...
},
// ...
]
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
---
## See also
{{< page-relref ref = "methods/accounts#follow" caption = "POST /api/v1/accounts/:id/follow" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/suggestions_controller.rb" caption = "app/controllers/api/v2/suggestions_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/suggestions_controller.rb" caption = "app/controllers/api/v1/suggestions_controller.rb" > }}