Friends

The Friends API handles sending, accepting, and managing friend relationships.

List Friends

Get all your current friends.

GET /v1/friends
Authorization: Bearer {token}

Response:

[
  {
    "user_id": "12345",
    "display_name": "FriendName",
    "friends_since": 1703520000
  }
]

Send Friend Request

Send a friend request to another user.

POST /v1/friends/request
Authorization: Bearer {token}

{
  "user_id": "67890"
}

Response (201 Created):

{
  "message": "Friend request sent",
  "target_user": "67890",
  "display_name": "TargetUser"
}

Error Codes:

Code	Description
SOCIAL_CANNOT_FRIEND_SELF	Can't friend yourself
SOCIAL_ALREADY_FRIENDS	Already friends
SOCIAL_REQUEST_ALREADY_PENDING	Request already sent
SOCIAL_USER_BLOCKED	User is blocked

Accept Friend Request

Accept an incoming friend request.

POST /v1/friends/accept
Authorization: Bearer {token}

{
  "user_id": "67890"
}

Response:

{
  "message": "Friend request accepted"
}

Decline Friend Request

Decline an incoming request or cancel an outgoing request.

POST /v1/friends/decline
Authorization: Bearer {token}

{
  "user_id": "67890"
}

Response: 204 No Content

Remove Friend

Remove an existing friend.

DELETE /v1/friends/{userID}
Authorization: Bearer {token}

Response: 204 No Content

List Pending Requests

Get both incoming and outgoing friend requests.

GET /v1/friends/requests
Authorization: Bearer {token}

Response:

{
  "incoming": [
    {
      "user_id": "11111",
      "display_name": "SomeUser",
      "requested_at": 1703520000,
      "is_incoming": true
    }
  ],
  "outgoing": [
    {
      "user_id": "22222",
      "display_name": "AnotherUser",
      "requested_at": 1703510000,
      "is_incoming": false
    }
  ]
}

Notifications

When friend requests are sent or accepted, notifications are automatically created for the recipient. See Notifications API.