Friends API

Endpoints for the social friends list, friend requests, and visibility metadata.

Permissions

• social:friends.read for listing friends and requests
• social:friends.write for sending requests
• social:friends.edit for accepting, declining, or editing links

If the permission node is not present in the database, the endpoint allows access by default.

Endpoints

GET /v1/social/friends

Returns the current friends list with counts.

GET /v1/social/friends/requests

Returns incoming and outgoing requests.

POST /v1/social/friends/requests

Create a new request. Requests are rejected when the recipient has disabled allowFriendRequests in profile settings.

Body:

{
  "targetId": "uuid",
  "targetName": "playerName",
  "note": "optional"
}

POST /v1/social/friends/requests/{id}/accept

Accept a friend request.

POST /v1/social/friends/requests/{id}/decline

Decline a request (recipient or sender).

DELETE /v1/social/friends/requests/{id}

Cancel or decline a request.

PATCH /v1/social/friends/{friendId}

Update metadata for the current user -> friend link.

Body:

{
  "favorite": true,
  "visibility": "DEFAULT"
}

Visibility values: DEFAULT, LIMITED, HIDDEN.

DELETE /v1/social/friends/{friendId}

Remove a friend link (both directions).

GET /v1/users/{id}/friends

Returns the friends list (including counts and requests) for a specific user id. Requires social:friends.read.

Payloads

Friend entry:

{
  "friendId": "uuid",
  "favorite": false,
  "visibility": "DEFAULT",
  "note": "optional",
  "createdAt": "2026-01-07T12:00:00Z",
  "acceptedAt": "2026-01-07T12:00:00Z",
  "updatedAt": "2026-01-07T12:00:00Z",
  "online": true,
  "partyId": "uuid",
  "name": "Player",
  "status": { "state": "ONLINE", "timestamp": "2026-01-07T12:00:00Z" },
  "player": {
    "id": "uuid",
    "name": "Player",
    "online": true,
    "status": { "state": "ONLINE", "timestamp": "2026-01-07T12:00:00Z" },
    "partyId": "uuid"
  },
  "lastSeenAt": "2026-01-07T12:00:00Z"
}

Request entry:

{
  "id": "objectId",
  "senderId": "uuid",
  "recipientId": "uuid",
  "direction": "incoming",
  "note": "optional",
  "createdAt": "2026-01-07T12:00:00Z",
  "expiresAt": "2026-01-14T12:00:00Z",
  "player": {
    "id": "uuid",
    "name": "Player",
    "online": false,
    "status": { "state": "OFFLINE", "timestamp": "2026-01-07T12:00:00Z" },
    "partyId": null
  }
}