Skip to content

Friends API

Older endpoint notes

Rendered from ProjectInfo/api-docs/api/friends.md on docs/encryption-modes-spec. These notes predate the REST API reference, which is canonical wherever the two overlap. They are published because they still cover endpoints the reference does not yet document — check shapes against the reference and the spec errata.

POST /api/users/{id}/friends does not exist.

Friend requests are directional. A friendship is mutual once accepted.

All endpoints require Authorization: Bearer <token>.

POST /api/users/@me/friends

Send a friend request. Supply username or user_id — at least one required.

Request: 

{ "username": "alice" }
or 
{ "user_id": "uuid" }

Response 204
Errors: 400 (self-request / neither field), 404 (user not found), 409 (already friends or pending), 403 (blocked)

GET /api/users/@me/friends

List accepted friends.

Response 200: Array of User

GET /api/users/@me/friends/pending

List incoming and outgoing pending requests.

Response 200: 

{
  "incoming": [
    { "user_id": "uuid", "username": "string", "created_at": "ISO8601" }
  ],
  "outgoing": [
    { "user_id": "uuid", "username": "string", "created_at": "ISO8601" }
  ]
}

PUT /api/users/@me/friends/{userID}

Accept an incoming friend request.

Response 204
Errors: 404 (no pending request from that user)

DELETE /api/users/@me/friends/{userID}

Decline incoming request, cancel outgoing request, or remove existing friend.

Response 204

POST /api/users/{userID}/friends

Alternative: send friend request by user ID (used when you already have the UUID).

Response 204