API Reference - Snek Platform Documentation

Protocol

Snek uses a JSON-RPC style protocol over WebSocket. Connect to /rpc.ws to establish a connection.

Request Format

{
  "callId": "unique-id",
  "method": "method_name",
  "args": [arg1, arg2, ...]
}

Response Format

{
  "callId": "unique-id",
  "success": true,
  "data": { ... }
}

Server Events

The server pushes events without a callId:

{
  "channel_uid": "...",
  "event": "new_message",
  "data": { ... }
}

Authentication

login(username, password)

Authenticate and establish a session. On success, the WebSocket connection is associated with the user and subscribed to all their channels.

username (string) - The username

password (string) - The password

Returns: User record (without password field) on success, error on failure

ping() Auth Required

Keep the connection alive and update the user's last activity timestamp.

Returns: {"pong": []}

User

get_user(user_uid=None) Auth Required

Get user information. If no user_uid is provided, returns the current user's data.

user_uid (string, optional) - Target user's UID

Returns: User record (email hidden for other users)

search_user(query) Auth Required

Search for users by username.

query (string) - Search query

Returns: Array of matching usernames

Channels

get_channels() Auth Required

Get all channels the current user is a member of.

Returns: Array of channel objects with name, uid, tag, new_count, is_moderator, is_read_only, color

create_channel(name, description=None, is_private=False) Auth Required

Create a new channel. The creating user becomes the moderator.

name (string) - Channel name

description (string, optional) - Channel description

is_private (boolean, optional) - Whether the channel is private

Returns: {success: true, uid: "...", name: "..."}

update_channel(channel_uid, name, description=None, is_private=False) Auth Required

Update channel settings. Only the channel creator or admin can update.

channel_uid (string) - Channel UID

name (string) - New channel name

description (string, optional) - New description

is_private (boolean, optional) - Privacy setting

Returns: {success: true, name: "..."}

delete_channel(channel_uid) Auth Required

Delete a channel (soft delete). Only the channel creator or admin can delete. Public channel cannot be deleted.

channel_uid (string) - Channel UID

Returns: {success: true}

invite_user(channel_uid, username) Auth Required

Invite a user to a channel. Requires membership in the channel.

channel_uid (string) - Channel UID

username (string) - Username to invite

Returns: {success: true, username: "..."}

leave_channel(channel_uid) Auth Required

Leave a channel. Cannot leave the public channel.

channel_uid (string) - Channel UID

Returns: {success: true}

clear_channel(channel_uid) Auth Required

Clear all messages from a channel. Admin only.

channel_uid (string) - Channel UID

Returns: Boolean success

Messages

send_message(channel_uid, message, is_final=True) Auth Required

Send a message to a channel. If is_final is false, the message can be updated (for typing indicators).

channel_uid (string) - Target channel UID

message (string) - Message content

is_final (boolean, optional) - Whether the message is final (default true)

Returns: Message UID on success

get_messages(channel_uid, offset=0, timestamp=None) Auth Required

Get messages from a channel with pagination.

channel_uid (string) - Channel UID

offset (integer, optional) - Pagination offset

timestamp (string, optional) - Filter by timestamp

Returns: Array of message objects

update_message_text(message_uid, text) Auth Required

Update a non-final message's text. Only the message author can update. Message must be less than 8 seconds old.

message_uid (string) - Message UID

text (string) - New text content

Returns: {success: true}

finalize_message(message_uid) Auth Required

Mark a message as final, preventing further updates.

message_uid (string) - Message UID

Returns: Boolean success

mark_as_read(channel_uid) Auth Required

Mark all messages in a channel as read for the current user.

channel_uid (string) - Channel UID

Returns: Boolean success

get_first_unread_message_uid(channel_uid) Auth Required

Get the UID of the first unread message in a channel.

channel_uid (string) - Channel UID

Returns: Message UID or null

Presence

set_typing(channel_uid, color=None) Auth Required

Broadcast a typing indicator to channel members.

channel_uid (string) - Channel UID

color (string, optional) - Indicator color (defaults to user's color)

Returns: Boolean success

get_online_users(channel_uid) Auth Required

Get users currently online in a channel.

channel_uid (string) - Channel UID

Returns: Array of user objects sorted by nick

get_recent_users(channel_uid) Auth Required

Get users with recent activity in a channel.

channel_uid (string) - Channel UID

Returns: Array with uid, username, nick, last_ping

get_users(channel_uid) Auth Required

Get all members of a channel.

channel_uid (string) - Channel UID

Returns: Array with uid, username, nick, last_ping

Container

Container methods provide access to channel-specific Docker containers (Ubuntu terminals).

get_container(channel_uid) Auth Required

Get container information for a channel.

channel_uid (string) - Channel UID

Returns: Container object with name, cpus, memory, image, status

start_container(channel_uid) Auth Required

Start the container for a channel.

channel_uid (string) - Channel UID

Returns: Boolean success

stop_container(channel_uid) Auth Required

Stop the container for a channel.

channel_uid (string) - Channel UID

Returns: Boolean success

get_container_status(channel_uid) Auth Required

Get the current status of a channel's container.

channel_uid (string) - Channel UID

Returns: Status string

write_container(channel_uid, content, timeout=3) Auth Required

Write to container stdin and capture output.

channel_uid (string) - Channel UID

content (string) - Content to write to stdin

timeout (integer, optional) - Wait timeout in seconds (max 30)

Returns: Output string

Database

Database methods provide direct access to user-scoped database operations.

db_insert(table_name, record) Auth Required

Insert a record into a user-scoped table.

table_name (string) - Table name

record (object) - Record to insert

Returns: Inserted record

db_update(table_name, record) Auth Required

Update a record in a user-scoped table.

table_name (string) - Table name

record (object) - Record with updates

Returns: Updated record

db_delete(table_name, record) Auth Required

Delete a record from a user-scoped table.

table_name (string) - Table name

record (object) - Record identifier

Returns: Boolean success

db_get(table_name, record) Auth Required

Get a single record from a user-scoped table.

table_name (string) - Table name

record (object) - Query criteria

Returns: Record or null

db_find(table_name, record) Auth Required

Find records in a user-scoped table.

table_name (string) - Table name

record (object) - Query criteria

Returns: Array of records

db_upsert(table_name, record, keys) Auth Required

Insert or update a record based on key fields.

table_name (string) - Table name

record (object) - Record data

keys (array) - Key fields for matching

Returns: Upserted record

db_query(sql, args) Auth Required

Execute a raw SQL query on user-scoped data.

sql (string) - SQL query

args (array) - Query parameters

Returns: Query results

query(sql) Auth Required

Execute a read-only SQL query. Forbidden keywords (DROP, ALTER, etc.) are blocked.

sql (string) - SQL SELECT query

Returns: Array of records (sensitive fields filtered)

Utility

echo(*args)

Echo back the provided arguments. Useful for testing.

args - Any arguments

Returns: The same arguments

echo_raw(obj)

Send a raw JSON object through the WebSocket. No response is sent back.

obj (object) - Object to send

Returns: No response

stars_render(channel_uid, message)

Broadcast a stars render event to all online users in a channel.

channel_uid (string) - Channel UID

message (string) - Message content

Returns: Boolean success