LVNGDocs
API ReferenceSDKslvng.ai

Channels API

Channels are the core communication containers in LVNG. They hold messages, members, and digital twin assignments. Every message belongs to a channel, and channels belong to workspaces. All endpoints require JWT authentication and are rate-limited to 300 requests per minute.

Base path: /api/v2/channels

Channel CRUD

Create, read, update, and delete channels within a workspace.

GET/api/v2/channelsAuthenticated

List channels in a workspace. Includes aggregate counts for messages and members.

Query Parameters

workspace_idstringrequired

UUID of the workspace to list channels from.

typestring

Filter by channel_type (e.g. text, voice, thread).

is_archivedboolean

Filter by archived status.

limitinteger

Maximum channels to return.

offsetinteger

Number of channels to skip.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/channels?workspace_id=ws_01HMPJ4WX9R6N8K5T3F0V7QB1Z&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "channels": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "general",
      "display_name": "General",
      "description": "Main workspace channel",
      "channel_type": "text",
      "topic": null,
      "is_archived": false,
      "message_count": 1423,
      "member_count": 8,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-03-19T12:00:00.000Z"
    },
    {
      "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "engineering",
      "display_name": "Engineering",
      "description": "Dev team discussions",
      "channel_type": "text",
      "topic": "Sprint 23 planning",
      "is_archived": false,
      "message_count": 892,
      "member_count": 5,
      "created_at": "2026-02-01T09:00:00.000Z",
      "updated_at": "2026-03-18T16:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 2,
    "hasMore": false
  }
}
POST/api/v2/channelsAuthenticated

Create a new channel. Creator is auto-added as member for private channels.

Body Parameters

workspace_idstringrequired

UUID of the workspace.

namestringrequired

URL-safe channel name (lowercase, hyphens).

display_namestring

Human-readable display name.

descriptionstring

Channel description.

channel_typestringrequired

Channel type: text, voice, thread, or dm.

topicstring

Current topic displayed in the channel header.

parent_channel_idstring

UUID of parent channel (for sub-channels).

Request

cURL
curl -X POST https://api.lvng.ai/api/v2/channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_01HMPJ4WX9R6N8K5T3F0V7QB1Z",
    "name": "product-strategy",
    "description": "Roadmap, pricing, and launch coordination",
    "type": "public"
  }'

Response 201

{
  "success": true,
  "channel": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "product-launches",
    "display_name": "Product Launches",
    "description": "Coordinate product launch activities",
    "channel_type": "text",
    "topic": null,
    "is_archived": false,
    "parent_channel_id": null,
    "created_by": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "created_at": "2026-03-19T15:30:00.000Z",
    "updated_at": "2026-03-19T15:30:00.000Z"
  }
}
GET/api/v2/channels/:idAuthenticated

Get a channel with member count and message count. Checks access permissions.

Path Parameters

idstringrequired

UUID of the channel.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/channels/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "channel": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "general",
    "display_name": "General",
    "description": "Main workspace channel",
    "channel_type": "text",
    "topic": null,
    "is_archived": false,
    "member_count": 8,
    "message_count": 1423,
    "created_by": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-03-19T12:00:00.000Z"
  }
}
PATCH/api/v2/channels/:idAuthenticated

Update channel properties. Requires owner, admin, or creator role.

Path Parameters

idstringrequired

UUID of the channel.

Body Parameters

display_namestring

Updated display name.

descriptionstring

Updated description.

topicstring

Updated channel topic.

is_archivedboolean

Set to true to archive the channel.

Request

cURL
curl -X PATCH "https://api.lvng.ai/api/v2/channels/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "channel": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "general",
    "display_name": "General Discussion",
    "description": "Main workspace channel",
    "channel_type": "text",
    "topic": "Weekly standup notes and general chat",
    "is_archived": false,
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-03-19T15:35:00.000Z"
  }
}
DELETE/api/v2/channels/:idAuthenticated

Delete a channel. CASCADE deletes all related data (messages, members, pins). Broadcasts socket event.

Path Parameters

idstringrequired

UUID of the channel to delete.

Request

cURL
curl -X DELETE "https://api.lvng.ai/api/v2/channels/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": "Channel deleted successfully"
}

Channel Members

Manage channel membership. Members are validated against workspace membership before being added. Supports individual adds, bulk adds, role updates, and email-based invites.

GET/api/v2/channels/:id/membersAuthenticated

List all members of a channel. LEFT JOINs user profiles for display details.

Path Parameters

idstringrequired

UUID of the channel.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/channels/{id}/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "members": [
    {
      "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "display_name": "Matty Squarzoni",
      "email": "matty@lvng.ai",
      "avatar_url": "https://storage.lvng.ai/avatars/a0eebc99.jpg",
      "role": "admin",
      "joined_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "user_id": "b1ffc99a-0d1c-5fa9-cc7e-7cc0ce491b22",
      "display_name": "Sarah Chen",
      "email": "sarah@lvng.ai",
      "avatar_url": null,
      "role": "member",
      "joined_at": "2026-01-16T09:30:00.000Z"
    }
  ],
  "count": 2
}
POST/api/v2/channels/:id/membersAuthenticated

Add a user to the channel. Validates workspace membership first.

Path Parameters

idstringrequired

UUID of the channel.

Body Parameters

user_idstringrequired

UUID of the user to add.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/channels/{id}/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "success": true,
  "member": {
    "user_id": "c2aad00b-1e2d-6gb0-dd8f-8dd1df502c33",
    "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "role": "member",
    "joined_at": "2026-03-19T15:40:00.000Z"
  }
}
PATCH/api/v2/channels/:id/members/:userIdAuthenticated

Update a member's role within the channel.

Path Parameters

idstringrequired

UUID of the channel.

userIdstringrequired

UUID of the user to update.

Body Parameters

rolestringrequired

New role: admin or member.

Request

cURL
curl -X PATCH "https://api.lvng.ai/api/v2/channels/{id}/members/{userId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "member": {
    "user_id": "b1ffc99a-0d1c-5fa9-cc7e-7cc0ce491b22",
    "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "role": "admin",
    "joined_at": "2026-01-16T09:30:00.000Z"
  }
}
DELETE/api/v2/channels/:id/members/:userIdAuthenticated

Remove a member from the channel.

Path Parameters

idstringrequired

UUID of the channel.

userIdstringrequired

UUID of the user to remove.

Request

cURL
curl -X DELETE "https://api.lvng.ai/api/v2/channels/{id}/members/{userId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": "Member removed successfully"
}
POST/api/v2/channels/:id/inviteAuthenticated

Invite a user by email. Looks up the user and adds them if found.

Path Parameters

idstringrequired

UUID of the channel.

Body Parameters

emailstringrequired

Email address to invite.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/channels/{id}/invite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "status": "added",
  "member": {
    "user_id": "d3bbe11c-2f3e-7hc1-ee9g-9ee2eg613d44",
    "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "role": "member",
    "joined_at": "2026-03-19T15:45:00.000Z"
  }
}
POST/api/v2/channels/:id/members/bulkAuthenticated

Add up to 50 members in a single request. Uses UPSERT to avoid duplicates.

Path Parameters

idstringrequired

UUID of the channel.

Body Parameters

user_idsstring[]required

Array of user UUIDs to add. Maximum 50.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/channels/{id}/members/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "success": true,
  "members": [
    {
      "user_id": "d3bbe11c-2f3e-7hc1-ee9g-9ee2eg613d44",
      "role": "member",
      "joined_at": "2026-03-19T15:50:00.000Z"
    },
    {
      "user_id": "e4ccf22d-3g4f-8id2-ff0h-0ff3fh724e55",
      "role": "member",
      "joined_at": "2026-03-19T15:50:00.000Z"
    },
    {
      "user_id": "f5ddg33e-4h5g-9je3-gg1i-1gg4gi835f66",
      "role": "member",
      "joined_at": "2026-03-19T15:50:00.000Z"
    }
  ],
  "added": 3
}

Digital Twins

Assign digital twins to channels. Twins process incoming messages and can respond based on their configuration and knowledge base.

GET/api/v2/channels/:id/twinsAuthenticated

List all digital twins assigned to a channel.

Path Parameters

idstringrequired

UUID of the channel.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/channels/{id}/twins" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "twins": [
    {
      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "name": "Research Assistant",
      "participation_mode": "active",
      "assigned_at": "2026-02-10T14:00:00.000Z"
    }
  ]
}
POST/api/v2/channels/:id/twinsAuthenticated

Assign a digital twin to the channel.

Path Parameters

idstringrequired

UUID of the channel.

Body Parameters

ai_twin_idstringrequired

UUID of the digital twin to assign.

participation_modestring

How the twin participates: active, passive, or on-demand.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/channels/{id}/twins" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "success": true,
  "twin": {
    "ai_twin_id": "2c0e7dce-ccge-5c3e-0c6e-bc9egcce5cfe",
    "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "participation_mode": "active",
    "assigned_at": "2026-03-19T16:00:00.000Z"
  }
}
DELETE/api/v2/channels/:id/twins/:twinIdAuthenticated

Remove a digital twin from the channel.

Path Parameters

idstringrequired

UUID of the channel.

twinIdstringrequired

UUID of the twin to remove.

Request

cURL
curl -X DELETE "https://api.lvng.ai/api/v2/channels/{id}/twins/{twinId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true
}

Pinned Messages

Pin and unpin messages within a channel. Pinned state is stored in the message's metadata column as pinned: true.

POST/api/v2/channels/:id/messages/:messageId/pinAuthenticated

Pin a message. Sets metadata.pinned=true on the message.

Path Parameters

idstringrequired

UUID of the channel.

messageIdstringrequired

UUID of the message to pin.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/channels/{id}/messages/{messageId}/pin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "message": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "content": "Q2 roadmap finalized. All features listed below are confirmed.",
    "metadata": {
      "pinned": true,
      "pinned_by": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "pinned_at": "2026-03-19T16:10:00.000Z"
    },
    "updated_at": "2026-03-19T16:10:00.000Z"
  }
}
DELETE/api/v2/channels/:id/messages/:messageId/pinAuthenticated

Unpin a message. Strips pinned fields from metadata.

Path Parameters

idstringrequired

UUID of the channel.

messageIdstringrequired

UUID of the message to unpin.

Request

cURL
curl -X DELETE "https://api.lvng.ai/api/v2/channels/{id}/messages/{messageId}/pin" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "content": "Q2 roadmap finalized. All features listed below are confirmed.",
    "metadata": {},
    "updated_at": "2026-03-19T16:12:00.000Z"
  }
}
GET/api/v2/channels/:id/pinsAuthenticated

List all pinned messages in a channel. Filters by metadata->>pinned='true'.

Path Parameters

idstringrequired

UUID of the channel.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/channels/{id}/pins" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "pins": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "channel_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "content": "Q2 roadmap finalized. All features listed below are confirmed.",
      "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "metadata": {
        "pinned": true,
        "pinned_by": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
        "pinned_at": "2026-03-19T16:10:00.000Z"
      },
      "created_at": "2026-03-19T14:30:00.000Z"
    }
  ],
  "count": 1
}