Skip to content
Documentation

Users

Manage user profiles, social links, follows, and user content.

Base Endpoint

Section titled “Base Endpoint”

All user endpoints are prefixed with /users

User Profile

Section titled “User Profile”

Get My Profile

Section titled “Get My Profile”
GET /users/me

Get the current authenticated user’s profile.

Authentication: Required

Response:

{
  "id": "user-id",
  "username": "username",
  "displayName": "Display Name",
  "email": "user@example.com",
  "bio": "User bio",
  "image": "https://...",
  "bannerUrl": "https://...",
  "role": "USER",
  "badges": [...],
  "createdAt": "2024-01-01T00:00:00Z"
}

Update My Profile

Section titled “Update My Profile”
PATCH /users/me

Update the current user’s profile.

Authentication: Required

Request Body: (all fields optional)

{
  "displayName": "New Display Name",
  "bio": "Updated bio",
  "location": "City, Country",
  "website": "https://example.com"
}

Upload Profile Image

Section titled “Upload Profile Image”
POST /users/me/image

Upload a profile image.

Authentication: Required

Content-Type: multipart/form-data

Form Data:

  • image (file) - Image file (PNG, JPG, WEBP)

Response:

{
  "imageUrl": "https://cdn.orbis.place/profile-images/..."
}

Delete Profile Image

Section titled “Delete Profile Image”
DELETE /users/me/image

Delete the profile image (reverts to default).

Authentication: Required

Upload Profile Banner

Section titled “Upload Profile Banner”
POST /users/me/banner

Upload a profile banner.

Authentication: Required

Content-Type: multipart/form-data

Form Data:

  • banner (file) - Image file (PNG, JPG, WEBP)

Delete Profile Banner

Section titled “Delete Profile Banner”
DELETE /users/me/banner

Delete the profile banner.

Authentication: Required

Get My Servers

Section titled “Get My Servers”
GET /users/me/servers

Get all servers owned by the current user.

Authentication: Required

Response:

{
  "servers": [...]
}

User Lookup

Section titled “User Lookup”

Get User by Username

Section titled “Get User by Username”
GET /users/username/:username

Get a user’s public profile by username.

Authentication: Optional

URL Parameters:

  • username (string) - Username

Response:

{
  "id": "user-id",
  "username": "username",
  "displayName": "Display Name",
  "bio": "User bio",
  "image": "https://...",
  "bannerUrl": "https://...",
  "badges": [...],
  "socialLinks": [...],
  "followerCount": 50,
  "followingCount": 30,
  "isFollowing": false,
  "createdAt": "2024-01-01T00:00:00Z"
}

Get User by ID

Section titled “Get User by ID”
GET /users/:userId

Get a user’s public profile by ID.

Authentication: Not required

URL Parameters:

  • userId (string) - User ID

Response: Same as get by username

Search Users

Section titled “Search Users”
GET /users/search

Search for users by username or display name.

Authentication: Required

Query Parameters:

  • q (string, required) - Search query
  • limit (number, optional) - Maximum results (default: 20)

Response:

{
  "users": [
    {
      "id": "user-id",
      "username": "username",
      "displayName": "Display Name",
      "image": "https://...",
      "badges": [...]
    }
  ]
}

Following System

Section titled “Following System”

Follow User

Section titled “Follow User”
POST /users/:userId/follow

Follow a user.

Authentication: Required

URL Parameters:

  • userId (string) - User ID to follow

Response:

{
  "message": "User followed successfully",
  "followerCount": 51
}

Unfollow User

Section titled “Unfollow User”
DELETE /users/:userId/follow

Unfollow a user.

Authentication: Required

URL Parameters:

  • userId (string) - User ID to unfollow

Response:

{
  "message": "User unfollowed successfully",
  "followerCount": 50
}

Get User Followers

Section titled “Get User Followers”
GET /users/:userId/followers

Get a list of users following this user.

Authentication: Not required

URL Parameters:

  • userId (string) - User ID

Response:

{
  "followers": [
    {
      "id": "follower-id",
      "username": "follower",
      "displayName": "Follower Name",
      "image": "https://...",
      "followedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 50
}

Get User Following

Section titled “Get User Following”
GET /users/:userId/following

Get a list of users that this user is following.

Authentication: Not required

URL Parameters:

  • userId (string) - User ID

Response:

{
  "following": [
    {
      "id": "user-id",
      "username": "username",
      "displayName": "Display Name",
      "image": "https://...",
      "followedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 30
}
Section titled “Social Links”
Section titled “Get My Social Links”
GET /users/me/social-links

Get the current user’s social links.

Authentication: Required

Response:

{
  "socialLinks": [
    {
      "id": "link-id",
      "platform": "TWITTER",
      "url": "https://twitter.com/username",
      "order": 0
    }
  ]
}

Platforms: TWITTER, YOUTUBE, TWITCH, GITHUB, DISCORD, WEBSITE, OTHER

Section titled “Create Social Link”
POST /users/me/social-links

Add a social link to your profile.

Authentication: Required

Request Body:

{
  "platform": "TWITTER",
  "url": "https://twitter.com/username"
}

Response:

{
  "id": "link-id",
  "platform": "TWITTER",
  "url": "https://twitter.com/username",
  "order": 0
}
Section titled “Update Social Link”
PATCH /users/me/social-links/:id

Update a social link.

Authentication: Required

URL Parameters:

  • id (string) - Social link ID

Request Body:

{
  "platform": "TWITTER",
  "url": "https://twitter.com/new-username"
}
Section titled “Delete Social Link”
DELETE /users/me/social-links/:id

Delete a social link.

Authentication: Required

URL Parameters:

  • id (string) - Social link ID
Section titled “Reorder Social Links”
PATCH /users/me/social-links/reorder

Reorder social links on your profile.

Authentication: Required

Request Body:

{
  "linkIds": ["link-id-1", "link-id-2", "link-id-3"]
}

Response:

{
  "message": "Social links reordered successfully"
}