Skip to content

Follow a user

POST
/users/{ref}/follow

Follows the account ref as you. The follow takes effect at once, with no approval step, and the answer is 204 whether or not you already followed it.

Any signed-in account can follow; no capability is needed. Without a session cookie or bearer token that identifies you, the answer is 401, whether or not public mode is on. A ref that isn’t a whole number gets a plain-text 400 before sign-in is checked. Following yourself gets 400, and a ref with no account gets 404. The account’s status isn’t checked, so a pending, disabled or archived account can be followed.

If either of you has blocked the other, the answer is 403. That check can use a cached answer and runs just before the follow is saved rather than in the same step, so a block made at the same moment, or one this server hasn’t caught up with, may not stop the follow, and the follow then stays in place beside the block.

A follow lets you read the person’s published posts shared with followers only, and the following feed of GET /posts includes their posts, still within the read rule. Nothing else you can or can’t read changes.

Each successful request, a repeat included, records the follow in the activity log in the same step as the save. Afterwards the server tries to give the person an in-app notification that you followed them. One is written only if their settings for new followers include in-app notifications and the same cached block check finds no block between you; if writing it fails, the follow still succeeds. A repeat follow can create another notification, since duplicates aren’t removed. Server errors get a plain-text 500.

ref
required
integer format: int64

The account’s ref.

The follow request succeeded, also when you already followed the account.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed