Mantle2 Friends Endpoints

Friendship management is user-scoped. Endpoints exist for user by ID, by username, and for the current user. Paths do not include a friend ID segment; instead, PUT/DELETE accept a body with the target user.

Friendship Schema

Friendships are bidirectional relationships between users. The response includes the friend's user object:

Field	Type	Description
id	string	Friend's user ID (24-digit zero-padded)
username	string	Friend's username
email	string	Friend's email (if visible per privacy settings)
... other user fields	...	Additional user profile fields per privacy settings

By ID — /v2/users/{id}/friends

GET /v2/users/{id}/friends

List all friends for a user.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Query Parameters

Name	Type	Description
limit	int	Page size
page	int	Page index
search	string	Free-text search
sort	string	Sort expression

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000000987654321",
			"username": "friend_user",
			"email": "[email protected]"
		},
		{
			"id": "000000000000001122334455",
			"username": "another_friend",
			"email": "[email protected]"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 2
}

401 Unauthorized — authentication may be required depending on user privacy settings

404 Not Found — user does not exist

PUT /v2/users/{id}/friends

Add a friend. Creates a bidirectional friendship.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Request Body

{
	"friend": "000000000000000987654321"
}

Responses

200 OK:

{
	"id": "000000000000000987654321",
	"username": "friend_user",
	"email": "[email protected]"
}

400 Bad Request — invalid request (e.g., missing friend ID, invalid format)

401 Unauthorized — authentication required

403 Forbidden — permission denied

404 Not Found — user or friend does not exist

409 Conflict — friendship already exists

DELETE /v2/users/{id}/friends

Remove a friend. Removes the bidirectional friendship.

Path Parameters

Name	Type	Description
id	string	User ID (24-digit string)

Request Body

{
	"friend": "000000000000000987654321"
}

Responses

200 OK:

{
	"message": "Friend removed successfully"
}

400 Bad Request — invalid request

401 Unauthorized — authentication required

403 Forbidden — permission denied

404 Not Found — user, friend, or friendship does not exist

409 Conflict — friendship does not exist

By Username — /v2/users/{username}/friends

Mirrors ID-based routes using username path parameter instead of id.

GET /v2/users/{username}/friends

List all friends for a user by username.

Path Parameters

Name	Type	Description
username	string	Username

Responses

200 OK — same structure as GET by ID

400 Bad Request

404 Not Found

PUT /v2/users/{username}/friends

Add a friend using username.

Path Parameters

Name	Type	Description
username	string	Username

Request Body

{
	"friend": "000000000000000987654321"
}

Responses

200 OK; 400; 401; 403; 404; 409

DELETE /v2/users/{username}/friends

Remove a friend using username.

Path Parameters

Name	Type	Description
username	string	Username

Request Body

{
	"friend": "000000000000000987654321"
}

Responses

200 OK; 400; 401; 403; 404; 409

Current User — /v2/users/current/friends

Endpoints for the currently authenticated user's friendships.

GET /v2/users/current/friends

List all friends for the current user.

Responses

200 OK — same structure as GET by ID

401 Unauthorized — authentication required

404 Not Found

PUT /v2/users/current/friends

Add a friend for the current user.

Request Body

{
	"friend": "000000000000000987654321"
}

Responses

200 OK; 400; 401; 403; 404; 409

DELETE /v2/users/current/friends

Remove a friend for the current user.

Request Body

{
	"friend": "000000000000000987654321"
}

Responses

200 OK; 400; 401; 403; 404; 409

Notes

• Friendships are bidirectional: when User A adds User B as a friend, User B also has User A as a friend
• The friend field in request bodies accepts user IDs (24-digit strings)
• Friend lists respect privacy settings: some user data may be hidden based on privacy configuration
• Attempting to add an existing friend returns 409 Conflict
• Attempting to remove a non-existent friendship returns 404 Not Found
• Mutual friends can be queried through the API (implementation detail)
• Friend recommendations may be available through separate recommendation endpoints

Error Format

{
	"error": {
		"code": "E404",
		"message": "Not found"
	}
}

{
	"error": {
		"code": "E409",
		"message": "Friendship already exists"
	}
}