Skip to main content
GET
/
:projectId
/
api
/
v7
/
users
/
suggestions
Fetch User Suggestions
curl --request GET \
  --url https://api.sublay.io/api/v6/:projectId/api/v7/users/suggestions
{
  "id": "<string>",
  "foreignId": {},
  "name": {},
  "username": {},
  "avatar": {},
  "bio": {},
  "metadata": {},
  "reputation": 123,
  "createdAt": "<string>"
}
Returns up to 5 users whose usernames contain the provided query string, ranked by prefix match first, then alphabetically. Designed for @mention autocomplete and user search UIs.
Sensitive fields (email, hash, salt, isVerified, isActive, lastActive) are excluded from suggestions results.

​
Query Parameters

​
query
string
required
The search string. Matches usernames that contain this value (case-insensitive). Users whose usernames start with query are ranked first.

​
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 an array of up to 5 user objects:
​
id
string
Unique user ID (UUID).
​
foreignId
string | null
External identifier from your system.
​
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.
​
createdAt
string
ISO timestamp of account creation.

​
Error Responses

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

​
See Also