Users API: Look Up Clody User Profiles by Username or ID

Bot is allowed on POST /api/users/get via the Authorization: <user_id> <token> header. See the Bots guide.

The Users API lets you fetch the public profile of any Clody account — including your own. You identify the user by either their username or their numeric ID, and Clody returns everything you need to render their profile card: display name, avatar, accent color, status text, bio, and your relationship with them. You must be logged in with a verified email address to use this endpoint.

POST /api/users/get

Looks up a single user profile by username or numeric ID.

Pass either username or id — you do not need both. If you include both, id takes precedence.

The special ID 0 always returns the built-in system user Clody regardless of any other parameters. This account is always shown as online. Note that the system user response omits the thought, color, and description fields — only username, id, display_name, is_friend, is_enemy, online, and avatar are returned.

Request body

string

The exact username of the user to look up. Case-sensitive.

integer

The numeric ID of the user to look up. Use 0 to retrieve the system user Clody.

# Look up by username
curl -b cookies.txt -X POST https://clody.lol/api/users/get \
  -H "Content-Type: application/json" \
  -d '{"username": "ada"}'

# Look up by ID
curl -b cookies.txt -X POST https://clody.lol/api/users/get \
  -H "Content-Type: application/json" \
  -d '{"id": 42}'

# Fetch the system user
curl -b cookies.txt -X POST https://clody.lol/api/users/get \
  -H "Content-Type: application/json" \
  -d '{"id": 0}'

Response

200 OK:

string

The user’s unique username.

integer

The user’s numeric account ID. 0 for the system user Clody.

string

The user’s chosen display name. May differ from username.

boolean

true if this user is in your friends list.

boolean

true if you have blocked this user.

boolean

true if the user currently has an active Socket.IO connection. Always true for the system user.

string | null

URL of the user’s avatar image, or null if none is set.

string

The user’s current short status or quote (up to 100 characters). Empty string if not set.

string

The user’s accent color as a hex string (e.g. "#a78bfa" or "#f0f"). Empty string if not set.

string

The user’s bio or profile description (up to 300 characters). Empty string if not set.

{
  "username": "ada",
  "id": 42,
  "display_name": "Ada",
  "is_friend": true,
  "is_enemy": false,
  "online": true,
  "avatar": "https://clody.lol/avatars/ada.webp",
  "thought": "building cool things ✨",
  "color": "#a78bfa",
  "description": "Software engineer. Coffee enthusiast."
}

Error codes

Status	Body	Meaning
`400`	`"Bad Requests"`	Neither `username` nor `id` was provided.
`400`	`"Not Authorized"`	No valid or verified session cookie.
`403`	`"Forbidden"`	The user has disabled friend requests (`accepts_friend_requests: false`) and you are neither friends with them nor viewing your own profile. Their profile is not visible to you.
`404`	`"Not Found"`	No user with the given `username` or `id` exists.

If a user sets accepts_friend_requests to false in their privacy settings, their profile becomes private. You will receive a 403 when attempting to look them up unless you are already friends or you are looking up your own account.

Auth & Users

Branches

Picnics

Interactions

Real-Time

Bots

Users API: Look Up Clody User Profiles by Username or ID

POST /api/users/get

Request body

Response

Error codes

​POST /api/users/get

​Request body

​Response

​Error codes

POST /api/users/get

Request body

Response

Error codes