Skip to main content
GET
Fetch User Suggestions
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 the opt-in spaceReputation object accepts a spaceId of 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.

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

See Also