Digital Twins

Digital twins are AI personas sourced from the Mind Reasoner integration. Browse the available catalog, add twins to your personal workspace, and configure how each twin participates in conversations. Rate limited to 60 requests per minute. Real-time updates are broadcast via WebSocket events.

List Available Twins

GET/api/v2/twin-workspace/availableAuthenticated

Returns paginated, filterable list of available digital twins fetched from the Mind Reasoner integration. Supports search across name, description, and expertise.

Query Parameters

pageinteger

Default: 1

Page number for pagination.

page_sizeinteger

Default: 20

Number of twins per page.

categorystring

Filter by category. Options: Visionary, Innovator, Advisor, Designer, Engineer, Scientist, Writer, Philosopher, Expert.

searchstring

Full-text search across twin name, description, and expertise fields.

Request

cURL

400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/twin-workspace/available?page=1&page_size=10&category=Visionary" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"data": [
    {
      400">class="text-emerald-400">"id": 400">class="text-emerald-400">"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Steve Jobs",
      400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Digital twin personality",
      400">class="text-emerald-400">"category": 400">class="text-emerald-400">"Visionary",
      400">class="text-emerald-400">"expertise": [400">class="text-emerald-400">"Product Design", 400">class="text-emerald-400">"User Experience", 400">class="text-emerald-400">"Vision"],
      400">class="text-emerald-400">"avatar_url": null,
      400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-01-10T09:00:00.000Z",
      400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-15T14:00:00.000Z"
    },
    {
      400">class="text-emerald-400">"id": 400">class="text-emerald-400">"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Elon Musk",
      400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Digital twin personality",
      400">class="text-emerald-400">"category": 400">class="text-emerald-400">"Visionary",
      400">class="text-emerald-400">"expertise": [400">class="text-emerald-400">"Engineering", 400">class="text-emerald-400">"Innovation", 400">class="text-emerald-400">"Scale"],
      400">class="text-emerald-400">"avatar_url": null,
      400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-01-10T09:00:00.000Z",
      400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-15T14:00:00.000Z"
    }
  ],
  400">class="text-emerald-400">"pagination": {
    400">class="text-emerald-400">"total": 2,
    400">class="text-emerald-400">"page": 1,
    400">class="text-emerald-400">"page_size": 10,
    400">class="text-emerald-400">"hasMore": false
  }
}

Get My Workspace

GET/api/v2/twin-workspace/mineAuthenticated

Returns all twins the authenticated user has added to their workspace, including per-twin settings. Ordered by is_favorite descending, then added_at descending.

Request

cURL

400">curl -X 400">GET https:400">class="text-zinc-500">//api.lvng.ai/api/v2/twin-workspace/mine \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"data": {
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f901234",
    400">class="text-emerald-400">"twins": [
      {
        400">class="text-emerald-400">"id": 400">class="text-emerald-400">"e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012",
        400">class="text-emerald-400">"twin_id": 400">class="text-emerald-400">"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        400">class="text-emerald-400">"customer_id": 400">class="text-emerald-400">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f901234",
        400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Steve Jobs",
        400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Digital twin personality",
        400">class="text-emerald-400">"category": 400">class="text-emerald-400">"Visionary",
        400">class="text-emerald-400">"expertise": [400">class="text-emerald-400">"Product Design", 400">class="text-emerald-400">"User Experience", 400">class="text-emerald-400">"Vision"],
        400">class="text-emerald-400">"avatar_url": null,
        400">class="text-emerald-400">"is_favorite": true,
        400">class="text-emerald-400">"participation_mode": 400">class="text-emerald-400">"active",
        400">class="text-emerald-400">"settings": {},
        400">class="text-emerald-400">"added_at": 400">class="text-emerald-400">"2026-03-01T12:00:00.000Z"
      },
      {
        400">class="text-emerald-400">"id": 400">class="text-emerald-400">"a7b8c9d0-1e2f-3a4b-5c6d-7e8f90123456",
        400">class="text-emerald-400">"twin_id": 400">class="text-emerald-400">"b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
        400">class="text-emerald-400">"customer_id": 400">class="text-emerald-400">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f901234",
        400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Paul Graham",
        400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Digital twin personality",
        400">class="text-emerald-400">"category": 400">class="text-emerald-400">"Advisor",
        400">class="text-emerald-400">"expertise": [400">class="text-emerald-400">"Startups", 400">class="text-emerald-400">"Programming", 400">class="text-emerald-400">"Essays"],
        400">class="text-emerald-400">"avatar_url": null,
        400">class="text-emerald-400">"is_favorite": false,
        400">class="text-emerald-400">"participation_mode": 400">class="text-emerald-400">"on-demand",
        400">class="text-emerald-400">"settings": {},
        400">class="text-emerald-400">"added_at": 400">class="text-emerald-400">"2026-03-10T08:30:00.000Z"
      }
    ],
    400">class="text-emerald-400">"total_twins": 2,
    400">class="text-emerald-400">"favorite_count": 1,
    400">class="text-emerald-400">"active_count": 1
  }
}

Add Twin to Workspace

POST/api/v2/twin-workspace/twinsAuthenticated

Adds a twin from the available catalog to the user's workspace. Validates that the twin exists and is not already added. Emits a twin:added WebSocket event.

Body Parameters

twin_idstring (UUID)required

The ID of the twin to add, from the available twins list.

is_favoriteboolean

Default: false

Whether to mark as a favorite.

participation_modestring

Default: "active"

How the twin participates in conversations. One of: active, observer, on-demand.

settingsobject

Custom settings object for this twin instance.

Request

cURL

400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/twin-workspace/twins \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"twin_id": 400">class="text-emerald-400">"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    400">class="text-emerald-400">"is_favorite": true,
    400">class="text-emerald-400">"participation_mode": 400">class="text-emerald-400">"active"
  }'

Response 201

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"data": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"c9d01e2f-3a4b-5c6d-7e8f-901234567890",
    400">class="text-emerald-400">"customer_id": 400">class="text-emerald-400">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f901234",
    400">class="text-emerald-400">"twin_id": 400">class="text-emerald-400">"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    400">class="text-emerald-400">"is_favorite": true,
    400">class="text-emerald-400">"participation_mode": 400">class="text-emerald-400">"active",
    400">class="text-emerald-400">"settings": {}
  }
}

Remove Twin from Workspace

DELETE/api/v2/twin-workspace/twins/:twinIdAuthenticated

Removes a twin from the user's workspace. Returns 404 if the twin is not in the workspace. Emits a twin:removed WebSocket event.

Path Parameters

twinIdstring (UUID)required

The twin_id (not the workspace row ID) of the twin to remove.

Request

cURL

400">curl -X 400">DELETE https:400">class="text-zinc-500">//api.lvng.ai/api/v2/twin-workspace/twins/8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"data": {
    400">class="text-emerald-400">"removed": true,
    400">class="text-emerald-400">"twin_id": 400">class="text-emerald-400">"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
  }
}

Update Twin Settings

PATCH/api/v2/twin-workspace/twins/:twinIdAuthenticated

Updates workspace settings for a specific twin. At least one field must be provided. Emits a twin:updated WebSocket event.

Path Parameters

twinIdstring (UUID)required

The twin_id of the twin to update.

Body Parameters

is_favoriteboolean

Toggle favorite status.

participation_modestring

Change participation mode. One of: active, observer, on-demand.

settingsobject

Updated custom settings object.

Request

cURL

400">curl -X 400">PATCH https:400">class="text-zinc-500">//api.lvng.ai/api/v2/twin-workspace/twins/8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"is_favorite": false,
    400">class="text-emerald-400">"participation_mode": 400">class="text-emerald-400">"observer"
  }'

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"data": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"c9d01e2f-3a4b-5c6d-7e8f-901234567890",
    400">class="text-emerald-400">"customer_id": 400">class="text-emerald-400">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f901234",
    400">class="text-emerald-400">"twin_id": 400">class="text-emerald-400">"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    400">class="text-emerald-400">"is_favorite": false,
    400">class="text-emerald-400">"participation_mode": 400">class="text-emerald-400">"observer",
    400">class="text-emerald-400">"settings": {},
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T10:45:00.000Z"
  }
}