Skip to content

User Lookup

Search and look up tenant users for collaboration purposes. These endpoints provide type-ahead search and user card resolution, useful for workspace member pickers, file owner display, and activity feeds.

Base path: /api/v1/users

Method Endpoint Description
GET /api/v1/users Search Users
GET /api/v1/users/{userId} Get User Card

Search Users

GET /api/v1/users

Requires Authentication - Scopes: users:lookup

Rate Limited - This endpoint enforces stricter rate limits

Search for users by name or username within the caller's tenant. Supports type-ahead / autocomplete scenarios. The search parameter is required and must be at least 2 characters to prevent open enumeration of all tenant users.

Results are sorted by username and paginated. The response indicates whether more results exist beyond the requested page size.

Query Parameters
Parameter Type Required Default Description
search string Yes - Case-insensitive prefix match on name or username. Minimum 2 characters.
size integer No 10 Number of results to return. Clamped to range 1–20.
includeSelf boolean No false Include the calling user in the results. 
curl -X GET "https://koldan.dixilang.com/api/v1/users?search=john&size=5" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/users",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"search": "john", "size": 5}
)
print(resp.json())
UserLookupSearchResponse
Field Type Nullable Description
users UserCardResponse[] No List of matching users.
size integer No Number of results returned.
hasMore boolean No Whether more results are available beyond the requested page size.
UserLookupSearchResponse
{
  "users": [
    {
      "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "username": "john.doe",
      "displayName": "John Doe"
    },
    ...
  ],
  "size": 2,
  "hasMore": false
}
Status Description
200 OK Search results returned successfully.
400 Bad Request The search parameter is missing or fewer than 2 characters.
401 Unauthorized Missing or invalid authentication token.
403 Forbidden The authenticated principal does not have the users:lookup scope.
429 Too Many Requests Rate limit exceeded.

Get User Card

GET /api/v1/users/{userId}

Requires Authentication - Scopes: users:lookup

Resolve a user ID into a minimal public profile card. Useful when the UI needs to display user information for workspace members, file owners, or activity feeds.

Path Parameters
Parameter Type Required Description
userId string (UUID) Yes The unique identifier of the user. 
curl -X GET "https://koldan.dixilang.com/api/v1/users/b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

user_id = "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/users/{user_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
UserCardResponse
Field Type Nullable Description
id string (UUID) No User unique identifier.
username string No Login username.
displayName string No Display name.
UserCardResponse
{
  "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "username": "john.doe",
  "displayName": "John Doe"
}
Status Description
200 OK User card returned successfully.
401 Unauthorized Missing or invalid authentication token.
403 Forbidden The authenticated principal does not have the users:lookup scope.
404 Not Found User does not exist in the caller's tenant.