Get Actors the authenticated Member could follow next, and say where the list came from. When the Member's account is hosted somewhere other than this deployment's own PDS, their own app.bsky.graph.follow records are read from their own repository and matched to Bivri Actors by DID; every other case, including a Member who is hosted here, a follow list this service could not read, and a follow list that matched nobody, answers with the popular-Creator fallback and names the reason instead of presenting the fallback as a Bluesky match. Matching is by DID and never by handle, so a renamed account is still matched and a recycled handle is never matched to the wrong Actor. The caller is never in its own suggestions, and an Actor the caller already follows on Bivri is never suggested.
Parameters
Output
application/jsonfallbackReason
string
Optional
Why the popular fallback was served, present only when `source` is 'popular'. 'not-bluesky-account' means the caller's repository is hosted on this deployment's own PDS, so there is no Bluesky follow list to read and none was requested. 'no-matched-follows' means the follow list was read and no account in it is a Bivri Actor this service can serve. 'follows-unavailable' means the caller's repository could not answer for its follow list after retries, which covers an outage, a rate limit, and an authorization no longer broad enough to read it.
not-bluesky-account, no-matched-follows, follows-unavailablesource
string
Required
Where this list came from. 'bluesky-follows' means every entry is an Actor the caller already follows on their own Bluesky account. 'popular' means the list is the fallback, ordered by follower count among Actors that have published Artwork, and `fallbackReason` says why the Bluesky match was not used. A client must not describe a 'popular' list as a Bluesky match.
bluesky-follows, popularsuggestions
array
Required
The suggested Actors, one entry per Actor. Empty is a real answer and never means the read failed: read `source` and `fallbackReason` for what was actually tried.
Errors
Unauthenticated
Nobody is authenticated, so there is no Member whose follows or existing Bivri follows could be read. Try It
Requests are sent directly from your browser. Some servers may block requests due to CORS.
View raw schema
{
"description": "Get Actors the authenticated Member could follow next, and say where the list came from. When the Member's account is hosted somewhere other than this deployment's own PDS, their own app.bsky.graph.follow records are read from their own repository and matched to Bivri Actors by DID; every other case, including a Member who is hosted here, a follow list this service could not read, and a follow list that matched nobody, answers with the popular-Creator fallback and names the reason instead of presenting the fallback as a Bluesky match. Matching is by DID and never by handle, so a renamed account is still matched and a recycled handle is never matched to the wrong Actor. The caller is never in its own suggestions, and an Actor the caller already follows on Bivri is never suggested.",
"errors": [
{
"description": "Nobody is authenticated, so there is no Member whose follows or existing Bivri follows could be read.",
"name": "Unauthenticated"
}
],
"output": {
"encoding": "application/json",
"schema": {
"properties": {
"fallbackReason": {
"description": "Why the popular fallback was served, present only when `source` is 'popular'. 'not-bluesky-account' means the caller's repository is hosted on this deployment's own PDS, so there is no Bluesky follow list to read and none was requested. 'no-matched-follows' means the follow list was read and no account in it is a Bivri Actor this service can serve. 'follows-unavailable' means the caller's repository could not answer for its follow list after retries, which covers an outage, a rate limit, and an authorization no longer broad enough to read it.",
"knownValues": [
"not-bluesky-account",
"no-matched-follows",
"follows-unavailable"
],
"maxLength": 64,
"type": "string"
},
"source": {
"description": "Where this list came from. 'bluesky-follows' means every entry is an Actor the caller already follows on their own Bluesky account. 'popular' means the list is the fallback, ordered by follower count among Actors that have published Artwork, and `fallbackReason` says why the Bluesky match was not used. A client must not describe a 'popular' list as a Bluesky match.",
"knownValues": [
"bluesky-follows",
"popular"
],
"maxLength": 64,
"type": "string"
},
"suggestions": {
"description": "The suggested Actors, one entry per Actor. Empty is a real answer and never means the read failed: read `source` and `fallbackReason` for what was actually tried.",
"items": {
"ref": "app.bivri.actor.defs#profileView",
"type": "ref"
},
"maxLength": 100,
"type": "array"
}
},
"required": [
"suggestions",
"source"
],
"type": "object"
}
},
"parameters": {
"properties": {
"limit": {
"default": 25,
"description": "How many suggestions to return at most. There is no cursor: this is one bounded list for a Member deciding who to follow, not a feed to page through.",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
"type": "params"
},
"type": "query"
}