Channels

Channels are where communication happens in Local Universe. They come in several types: text channels and planets within systems, DMs between users, group DMs, and voice channels.

The channel model

Properties

Name
id
Type
string
Description
Unique identifier for the channel.
Name
name
Type
string
Description
The name of the channel.
Name
icon
Type
string?
Description
Channel icon URL.
Name
type
Type
integer
Description
The channel type.
Name
system_id
Type
string?
Description
The system this channel belongs to (null for DMs).
Name
owner_id
Type
string?
Description
The user who created this channel.
Name
flags
Type
integer
Description
Channel flags bitfield.
Name
last_message_id
Type
string?
Description
The ID of the most recent message in this channel.
Name
created_at
Type
string
Description
When the channel was created.
Name
updated_at
Type
string
Description
When the channel was last updated.
Name
recipients
Type
User[]?
Description
Array of recipient users (DM and group DM channels only).

Channel types

Value	Name	Description
0	SYSTEM_TEXT	A text channel within a system
1	DM	A direct message between two users
2	GROUP_DM	A group direct message
3	SYSTEM_PLANET	A planet channel within a system (3D world)
4	SYSTEM_VOICE	A voice channel within a system
5	HOME	The system's home channel

GET/v1/channels/:channelId

Get a channel

Retrieve a channel by its ID.

Request

GET

/v1/channels/1344387816333352652

curl https://api.localuniverse.io/v1/channels/1344387816333352652 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "1344387816333352652",
  "name": "general",
  "type": 0,
  "system_id": "1344387816333350000",
  "owner_id": "1344387816333399999",
  "flags": 0,
  "last_message_id": "1344387816333359999",
  "created_at": "2025-02-26T19:17:12.848375Z",
  "updated_at": "2025-02-26T19:17:12.848375Z"
}

PATCH/v1/channels/:channelId

Update a channel

Optional attributes

Name
name
Type
string
Description
New channel name.
Name
icon
Type
string
Description
New channel icon URL.

Request

PATCH

/v1/channels/1344387816333352652

curl -X PATCH https://api.localuniverse.io/v1/channels/1344387816333352652 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "announcements"}'

GET/v1/channels/:channelId/messages

List messages

Retrieve messages from a channel. Sorted by creation time descending (newest first).

Query parameters

Name
limit
Type
integer
Description
Maximum number of messages to return (1-100). Default: 50.
Name
before
Type
string
Description
Get messages before this message ID.
Name
after
Type
string
Description
Get messages after this message ID.

Request

GET

/v1/channels/1344387816333352652/messages?limit=10

curl "https://api.localuniverse.io/v1/channels/1344387816333352652/messages?limit=10" \
  -H "Authorization: Bearer {token}"

POST/v1/channels/:channelId/messages

Create a message

Required attributes

Name
content
Type
string
Description
The message content.

Optional attributes

Name
nonce
Type
string
Description
Client-generated nonce for optimistic message deduplication.
Name
message_reference
Type
object
Description
Reference to another message (for replies). Must contain message_id.

Request

POST

/v1/channels/1344387816333352652/messages

curl -X POST https://api.localuniverse.io/v1/channels/1344387816333352652/messages \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, world!"}'

DELETE/v1/channels/:channelId/messages/:messageId

Delete a message

Delete a message. You can delete your own messages, or any message if you have MANAGE_MESSAGES permission.

Request

DELETE

/v1/channels/1344387816333352652/messages/1344387816333352999

curl -X DELETE https://api.localuniverse.io/v1/channels/1344387816333352652/messages/1344387816333352999 \
  -H "Authorization: Bearer {token}"

POST/v1/channels/:channelId/ack

Acknowledge messages

Mark messages in a channel as read. Updates the user's read state.

Required attributes

Name
message_id
Type
string
Description
The ID of the last read message.

Request

POST

/v1/channels/1344387816333352652/ack

curl -X POST https://api.localuniverse.io/v1/channels/1344387816333352652/ack \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "1344387816333352999"}'

GET/v1/channels/:channelId/scene

Get channel scene

Retrieve the 3D scene state for a planet channel (type 3). Returns tile and prefab data.

Request

GET

/v1/channels/1344387816333352652/scene

curl https://api.localuniverse.io/v1/channels/1344387816333352652/scene \
  -H "Authorization: Bearer {token}"

PATCH/v1/channels/:channelId/scene

Save channel scene

Update the 3D scene state for a planet channel. Requires BUILD or PLACE_PREFABS permission.

Request

PATCH

/v1/channels/1344387816333352652/scene

curl -X PATCH https://api.localuniverse.io/v1/channels/1344387816333352652/scene \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"version": 2, "biome": "forest", "chunks": [], "prefabs": []}'

GET/v1/channels/:channelId/endpoints

Get channel endpoints

Returns available endpoints for a channel (e.g., voice server information).

Request

GET

/v1/channels/1344387816333352652/endpoints

curl https://api.localuniverse.io/v1/channels/1344387816333352652/endpoints \
  -H "Authorization: Bearer {token}"

GET/v1/channels/:channelId/permissions

Get channel permissions

Returns all permission overwrites for a channel. See Permissions for the overwrite model.

Request

GET

/v1/channels/1344387816333352652/permissions

curl https://api.localuniverse.io/v1/channels/1344387816333352652/permissions \
  -H "Authorization: Bearer {token}"

PUT/v1/channels/:channelId/permissions/:targetId

Set channel permission overwrite

Create or update a permission overwrite for a role or member on this channel.

Required attributes

Name
type
Type
integer
Description
Overwrite type: 0 (ROLE) or 1 (MEMBER).
Name
allow
Type
string
Description
Allowed permissions bitfield as string.
Name
deny
Type
string
Description
Denied permissions bitfield as string.

Request

PUT

/v1/channels/1344387816333352652/permissions/1344387816333355555

curl -X PUT https://api.localuniverse.io/v1/channels/1344387816333352652/permissions/1344387816333355555 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"type": 0, "allow": "2048", "deny": "0"}'

DELETE/v1/channels/:channelId/permissions/:targetId

Delete channel permission overwrite

Remove a permission overwrite for a role or member on this channel.

Request

DELETE

/v1/channels/1344387816333352652/permissions/1344387816333355555

curl -X DELETE https://api.localuniverse.io/v1/channels/1344387816333352652/permissions/1344387816333355555 \
  -H "Authorization: Bearer {token}"