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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The account’s ref.
Request Body
Section titled “Request Body ”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
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.
Responses
Section titled “ Responses ”The block request succeeded, also when you had already blocked the account.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completed