Skip to main content

Users REST API

The Users REST API provides endpoints for user profile management and preferences.

Base URL​

/api/eai/v3/users

Get Current User​

Get the authenticated user's profile.

GET /api/eai/v3/users/me

Example Request​

const response = await fetch('/api/eai/v3/users/me');
const user = await response.json();

Response​

{
  "id": "user_123",
  "email": "jane.smith@example.com",
  "name": "Jane Smith",
  "avatar": "https://avatars.example.com/user_123.jpg",
  "role": "admin",
  "permissions": [
    "resources.read",
    "resources.create",
    "resources.update",
    "documents.upload",
    "chat.access",
    "users.manage"
  ],
  "tenantId": "acme-corp",
  "preferences": {
    "theme": "dark",
    "language": "en",
    "timezone": "America/New_York",
    "notifications": {
      "email": true,
      "push": false
    }
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "lastLoginAt": "2026-03-11T09:30:00Z"
}

Get User by ID​

GET /api/eai/v3/users/:id

Response​

Same structure as current user endpoint.

List Users​

List users in the tenant (requires users.manage permission).

GET /api/eai/v3/users

Query Parameters​

ParameterTypeDescription
rolestringFilter by role
statusstringFilter by status (active/inactive)
searchstringSearch by name or email
limitnumberMax results
offsetnumberPagination offset

Example Request​

const response = await fetch('/api/eai/v3/users?' + new URLSearchParams({
  role: 'admin',
  status: 'active',
  limit: '50'
}));

const { data: users } = await response.json();

Response​

{
  "data": [
    {
      "id": "user_123",
      "email": "jane.smith@example.com",
      "name": "Jane Smith",
      "role": "admin",
      "status": "active",
      "lastLoginAt": "2026-03-11T09:30:00Z"
    }
  ],
  "total": 12
}

Update User​

Update user profile or preferences.

PATCH /api/eai/v3/users/:id

Request Body​

{
  "name": "Jane Doe",
  "preferences": {
    "theme": "dark",
    "language": "es",
    "notifications": {
      "email": true,
      "push": true
    }
  }
}

Example Request​

const response = await fetch('/api/eai/v3/users/user_123', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    preferences: {
      theme: 'dark',
      timezone: 'Europe/London'
    }
  })
});

const updated = await response.json();

Update Current User​

Convenience endpoint for updating current user.

PATCH /api/eai/v3/users/me

Example Request​

await fetch('/api/eai/v3/users/me', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    preferences: {
      theme: 'light',
      notifications: { email: false }
    }
  })
});

User Permissions​

Check if user has specific permissions:

const user = await fetch('/api/eai/v3/users/me').then(r => r.json());

const canManageUsers = user.permissions.includes('users.manage');
const canUploadDocs = user.permissions.includes('documents.upload');

Next Steps​