Skip to content

Block a user

POST
/users/{ref}/block

Blocks the account ref and, in the same step, removes the follows between you in both directions. The answer is 204, also when you had already blocked them.

Any signed-in account can block; 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, and so does a body that can’t be decoded, such as one whose reason is a number; a reason of null counts as no reason. Blocking yourself gets 400, and a ref with no account gets 404. The account’s status isn’t checked.

While a block is in place, follow requests between you in either direction, direct messages between you and notifications from one of you to the other are checked against it and refused or skipped. Each of these checks can use a cached answer and runs just before its own write, so one made at the same moment as the block, or on a server that hasn’t caught up with it, can still go through. A block isn’t a content filter. It doesn’t hide posts, comments or profiles in either direction: what each of you can read stays as it was, apart from what the removed follows gave you.

The other person isn’t notified, but they can see that a block exists through getUserRelationship, and a follow request from them normally gets 403. A follow being saved at the same moment, or one a lagging block check let through (see followUser), can remain after the block; blocking again removes any follows it finds.

Blocking again replaces the saved reason, or clears it if you send none, a blank one or null, and keeps the original block time. The block, with its reason, is recorded in the activity log in the same step. Server errors get a plain-text 500.

ref
required
integer format: int64

The account’s ref.

Optional. No body, null, {} and a reason of null all block without a reason. Keys other than reason are ignored, and only the first JSON value in the body is read.

An optional private note to keep with the block.

object
reason

Your note about the block. Surrounding white space is removed, and a blank note or null saves none; the length limit shown isn’t checked. Blocking again replaces it, or clears it when you send none. listMyBlocked shows it to you, and it’s also kept in the activity log, which administrators who can read that log can see. It isn’t sent to the other person.

string
<= 500 characters

The block request succeeded, also when you had already blocked 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"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed