Skip to main content
GET
/
:projectId
/
api
/
v7
/
users
/
by-username
Fetch User by Username
curl --request GET \
  --url https://api.sublay.io/api/v6/:projectId/api/v7/users/by-username
{
  "id": "<string>",
  "foreignId": {},
  "projectId": "<string>",
  "name": {},
  "username": {},
  "avatar": {},
  "bio": {},
  "metadata": {},
  "reputation": 123,
  "avatarFile": {},
  "bannerFile": {},
  "createdAt": "<string>"
}
Finds a user within the project by their username. Optionally includes file associations for avatar and banner images.

​
Query Parameters

​
username
string
required
The username to look up. Lookup is exact-match and case-sensitive to the stored value (usernames are lowercased on write).
​
include
string
Comma-separated list of associations to include. Pass "files" to include the processed avatarFile and bannerFile objects.

​
Space-scoped reputation

This endpoint has no space in context, so spaceReputationId accepts a space <uuid> or none only — context is rejected (400). It adds a spaceReputation field to each returned user, alongside the always-present reputation total. Requires the reputation bundle. See the Reputation data model.
​
spaceReputationId
string
Adds spaceReputation to each returned user. Either a space <uuid> (that space’s bucket) or none (the project-general bucket). context, the empty string, and the legacy general / null aliases are rejected (400). Missing buckets read as 0.
​
spaceReputationDescendants
boolean
Only honored with an explicit space <uuid>. When true, spaceReputation is the subtree sum — the space plus all of its descendants. Ignored for none.

​
Response

On success, returns HTTP 200 with the user object:
​
id
string
Unique user ID (UUID).
​
foreignId
string | null
External identifier from your system.
​
projectId
string
Project this user belongs to.
​
name
string | null
Display name.
​
username
string | null
The user’s username.
​
avatar
string | null
Avatar image URL.
​
bio
string | null
Short bio text.
​
metadata
object | null
Public custom key-value data.
​
reputation
number
Reputation score.
​
avatarFile
object | null
Processed avatar image with variants. Only present when include=files is requested.
​
bannerFile
object | null
Processed banner image with variants. Only present when include=files is requested.
​
createdAt
string
ISO timestamp of account creation.

​
Error Responses

{
  "error": "User not found",
  "code": "user/not-found"
}

{
  "error": "...",
  "code": "user/invalid-query"
}

​
See Also