Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
The Users API allows tenant administrators to list existing users and invite new ones. User creation uses a privacy-safe response that does not reveal whether an email is already registered.
Base path
List users
Returns a paginated list of users for the current tenant, ordered by creation date (newest first). Only returns non-sensitive fields.
Query parameters
| Parameter | Required | Type | Description |
|---|
limit | No | integer | Maximum results per page. Default 25. |
cursor | No | string | Cursor for keyset pagination. |
Response 200
{
"data": [
{
"id": "usr_001",
"name": "Jane Smith",
"email": "jane@example.com",
"image": null,
"role": "admin",
"lastLoginAt": "2026-03-16T10:00:00.000Z",
"createdAt": "2026-02-01T12:00:00.000Z",
"updatedAt": "2026-03-16T10:00:00.000Z"
}
],
"pagination": {
"total": 5,
"limit": 25,
"hasMore": false,
"nextCursor": null
}
}
Invite a user
Creates a new user account for the tenant. If the email is already registered, the response is identical to a successful creation to prevent email enumeration.
Request body
| Field | Required | Type | Description |
|---|
email | Yes | string | Valid email address. |
name | No | string | null | User display name. |
role | No | enum | viewer (default), editor, admin. |
Example request
{
"email": "jane@example.com",
"name": "Jane Smith",
"role": "editor"
}
Response 201
{
"message": "If this email is not already registered, an account has been created."
}
The response message is intentionally vague for security. The same 201 status and message is returned regardless of whether the user already existed.
Error codes
| Code | Reason |
|---|
400 | Validation error (invalid email, invalid role). |
415 | Content-Type is not application/json. |
Update a user
Updates an existing user’s name or role.
Path parameters
| Parameter | Required | Type | Description |
|---|
id | Yes | string | User ID. |
Request body
All fields are optional. Only include the fields you want to change.
| Field | Type | Description |
|---|
name | string | null | Updated display name. |
role | enum | Updated role: viewer, editor, admin. |
Example request
{
"name": "Jane Doe",
"role": "admin"
}
Response 200
Returns the full updated user object.
{
"id": "usr_001",
"name": "Jane Doe",
"email": "jane@example.com",
"image": null,
"role": "admin",
"lastLoginAt": "2026-03-16T10:00:00.000Z",
"createdAt": "2026-02-01T12:00:00.000Z",
"updatedAt": "2026-03-30T14:00:00.000Z"
}
Delete a user
DELETE /api/v1/users/{id}
Path parameters
| Parameter | Required | Type | Description |
|---|
id | Yes | string | User ID. |
Response 204
No content. The user has been deleted.
Error codes
| Code | Reason |
|---|
404 | User not found in the current tenant. |
Role requirements
| Method | Minimum role |
|---|
| GET | admin |
| POST | admin |
| PUT | admin |
| DELETE | admin |
