User Blocking API

Blocking one user from another. A block is platform-wide, not a chat setting: it severs messaging, connection requests, follows, and visibility across the feed, search, suggestions and profiles.

Base URL: /api/v1
Auth: every endpoint requires Authorization: Bearer {token} (Sanctum).
Content type: application/json

Response envelope (all endpoints):

// Success                                  // Error
{                                           {
  "status": "success",                        "status": "error",
  "message": "…",                             "message": "…",
  "data": { }                                 "data": { }
}                                           }

The one rule that matters

A block is stored one-directional but enforced in both directions.

If A blocks B, then B cannot reach A either — B cannot message A, request a connection, see A's posts, or open A's profile. The block list itself stays private: B is never told, and there is no "you have been blocked" response anywhere. Every blocked surface reads as absent, not as forbidden — a blocked profile returns 404, not 403.

Only A can lift A's block. If both sides have blocked each other, one unblocking leaves the other block standing and contact stays severed.

What a block does

Surface	Effect
Chat — send	`POST /chat/threads/{id}/messages` and `POST /chat/users/{user}/messages` return `422`, both directions.
Chat — inbox	The thread disappears from `GET /chat/threads` for both users. Existing messages are not deleted.
Connections	Any existing connection or pending request is deleted at block time. New requests return `422`, both directions.
Follows	Any follow is deleted at block time, in both directions. New follows return `422`, both directions.
Feed	The other user's posts vanish from the timeline, permalinks, hashtag results and post search.
Search	The other user stops appearing in people search.
Suggestions	The other user stops appearing in `GET /feed/suggestions`.
Profile	`GET /feed/users/{username}` returns `404`, both directions.

Blocking does not delete messages, posts, or historical data. It cuts off reach, not history.

Endpoints

Block a user

POST /api/v1/users/{user}/block

No body. {user} is the target user's id. Idempotent — blocking an already-blocked user is a success, not a duplicate. Tears down any connection edge between the two as a side effect.

Response 201

{ "status": "success", "message": "User blocked.", "data": {} }

Code	When
404	No such user
422	You tried to block yourself

Unblock a user

DELETE /api/v1/users/{user}/block

No body. Idempotent. Lifts your block only — a block the other user placed on you is untouched.

Unblocking restores messaging and visibility, but does not restore the connection that blocking removed; that has to be requested again.

Response 200

{ "status": "success", "message": "User unblocked.", "data": {} }

Code	When
404	No such user

List blocked users

GET /api/v1/blocks?per_page=15

The users you have blocked, most recently blocked first. Users who blocked you are never listed — you are not told about them.

Query param	Notes
`per_page`	Optional, default 15.

Response 200

{
  "status": "success",
  "message": "Blocked users retrieved successfully.",
  "data": {
    "users": {
      "data": [
        {
          "id": "9c3f…",
          "name": "Jane Doe",
          "username": "jane",
          "avatar_url": null,
          "blocked_at": "2026-08-17T09:14:00+00:00"
        }
      ],
      "links": { "first": "…", "last": "…", "prev": null, "next": null },
      "meta": { "current_page": 1, "per_page": 15, "total": 1, "…": "…" }
    }
  }
}

Client notes

Don't pre-check. There is no "am I blocked" endpoint by design. Send the request and handle the 422 / 404; anything else leaks the block back to the blocked user.
Refresh the inbox after blocking. The thread is gone from GET /chat/threads immediately, but an open thread screen still holds its own state — navigate away from it.
Blocking is not reporting. Reporting a message (POST /chat/messages/{message}/report) sends content to moderation; blocking is a private, personal cut-off. They are independent — a user can do either, both, or neither.