How to Manage Friends, Requests, and Blocks in Clody

Friends are the foundation of private messaging in Clody. Before you can add someone to a Branch, you must be friends with them. This guide shows you how to find users, send and respond to friend requests, remove connections you no longer want, and block users who should not be able to reach you.

Find a User

POST /api/users/get Look up any registered user by their username or numeric user ID.

string

The target user’s username.

number

The target user’s numeric ID. Supply either username or id — not both.

curl -X POST https://clody.lol/api/users/get \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"username": "alex"}'

Response:

{
  "username": "alex",
  "id": 42,
  "display_name": "Alex",
  "is_friend": false,
  "is_enemy": false,
  "online": true,
  "avatar": "b2d7...4e.jpg",
  "thought": "Enjoying the sunshine ☀️",
  "color": "#e8a0f0",
  "description": "Frontend developer & coffee addict"
}

Some users set their profile to private by disabling friend requests. If you are not already friends with them, the server returns 403 Forbidden. You will not be able to view their profile or send them a request.

Send a Friend Request

POST /api/friends/send_request

string

required

The username of the person you want to add.

curl -X POST https://clody.lol/api/friends/send_request \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"to": "alex"}'

If the request is sent successfully, the target user receives a friend_request Socket.IO event:

{ "who": 7, "display_name": "Your Display Name" }

Why might a request fail?

The user has disabled friend requests (accepts_friend_requests setting).
You are on the user’s block list.
You are already friends.
You supplied your own username.

View Your Friends and Pending Requests

GET /api/friends/get Returns your current social graph in one call.

curl https://clody.lol/api/friends/get \
  -b "session=<your_session_cookie>"

Response:

{
  "friends": [42, 57, 88],
  "enemies": [13],
  "friend_requests": [101, 204]
}

array of numbers

User IDs of confirmed friends.

array of numbers

User IDs you have blocked.

array of numbers

User IDs of people who have sent you a pending friend request.

Accept or Decline a Friend Request

POST /api/friends/request

number

required

The user ID of the person who sent you the request.

number

required

1 to accept, 0 to decline.

Accept:

curl -X POST https://clody.lol/api/friends/request \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 101, "type": 1}'

When you accept, the requester receives an accept_request event: {"id": <your_user_id>}. Both users are added to each other’s friends list immediately. Decline:

curl -X POST https://clody.lol/api/friends/request \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 101, "type": 0}'

The requester receives a reject_request event: {"id": <your_user_id>}.

Remove a Friend

POST /api/friends/unfriend

number

required

The user ID of the friend you want to remove.

curl -X POST https://clody.lol/api/friends/unfriend \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 42}'

Both users are removed from each other’s friends lists. No Socket.IO event is emitted — the change is silent.

Removing a friend does not remove you from any shared Branches. Branch membership persists until a member leaves or the owner kicks them.

Block a User

POST /api/friends/set_enemy

number

required

The user ID to block or unblock.

number

required

1 to block, 0 to unblock.

Block:

curl -X POST https://clody.lol/api/friends/set_enemy \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 13, "type": 1}'

Blocking a user:

Removes them from your friends list (and removes you from theirs).
Prevents them from sending you friend requests in the future.
Stops them from viewing your profile.

Unblock:

curl -X POST https://clody.lol/api/friends/set_enemy \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 13, "type": 0}'

Unblocking removes the restriction but does not restore the friendship — you would need to send a new friend request.

Real-Time Friend Events

Friend activity arrives on the main / Socket.IO namespace. See Real-Time Events for connection details.

Event	Payload	When it fires
`friend_request`	`{who: number, display_name: string}`	Someone sent you a friend request
`accept_request`	`{id: number}`	Your friend request was accepted (`id` = your user ID)
`reject_request`	`{id: number}`	Your friend request was declined (`id` = your user ID)

Error Reference

HTTP Status	Meaning
`400`	Missing required field, or you tried to friend/block yourself
`403`	Target user has friend requests disabled, or you are on their block list; or already friends
`404`	User not found, or no pending request from that user

Get Started

Core Concepts

Guides

How to Manage Friends, Requests, and Blocks in Clody

Find a User

Send a Friend Request

View Your Friends and Pending Requests

Accept or Decline a Friend Request

Remove a Friend

Block a User

Real-Time Friend Events

Error Reference

​Find a User

​Send a Friend Request

​View Your Friends and Pending Requests

​Accept or Decline a Friend Request

​Remove a Friend

​Block a User

​Real-Time Friend Events

​Error Reference

Find a User

Send a Friend Request

View Your Friends and Pending Requests

Accept or Decline a Friend Request

Remove a Friend

Block a User

Real-Time Friend Events

Error Reference