# Digital Twins API

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.

## GET /api/v2/twin-workspace/available

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

**Authentication required**

### Query Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| page | integer | No | 1 | Page number for pagination. |
| page_size | integer | No | 20 | Number of twins per page. |
| category | string | No | -- | Filter by category. Options: Visionary, Innovator, Advisor, Designer, Engineer, Scientist, Writer, Philosopher, Expert. |
| search | string | No | -- | Full-text search across twin name, description, and expertise fields. |

### Example Request

```bash
curl -X GET "https://api.lvng.ai/api/v2/twin-workspace/available?page=1&page_size=10&category=Visionary" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

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

## GET /api/v2/twin-workspace/mine

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

**Authentication required**

### Example Request

```bash
curl -X GET https://api.lvng.ai/api/v2/twin-workspace/mine \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

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

## POST /api/v2/twin-workspace/twins

Add Twin to Workspace -- 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.

**Authentication required**

### Body Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| twin_id | string (UUID) | Yes | -- | The ID of the twin to add, from the available twins list. |
| is_favorite | boolean | No | false | Whether to mark as a favorite. |
| participation_mode | string | No | "active" | How the twin participates in conversations. One of: active, observer, on-demand. |
| settings | object | No | -- | Custom settings object for this twin instance. |

### Example Request

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

### Response (201)

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

## DELETE /api/v2/twin-workspace/twins/:twinId

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

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| twinId | string (UUID) | Yes | The twin_id (not the workspace row ID) of the twin to remove. |

### Example Request

```bash
curl -X DELETE https://api.lvng.ai/api/v2/twin-workspace/twins/8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

```json
{
  "success": true,
  "data": {
    "removed": true,
    "twin_id": "8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
  }
}
```

## PATCH /api/v2/twin-workspace/twins/:twinId

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

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| twinId | string (UUID) | Yes | The twin_id of the twin to update. |

### Body Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| is_favorite | boolean | No | Toggle favorite status. |
| participation_mode | string | No | Change participation mode. One of: active, observer, on-demand. |
| settings | object | No | Updated custom settings object. |

### Example Request

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

### Response (200)

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