API Structures

Response and request structures used across multiple API endpoints that don’t map directly to a single resource.

AuthTokenResponse

Returned by login, register, and refresh endpoints.

Field	Type	Description
`token`	`string`	Access token (Bearer)
`session_token`	`string`	Refresh/session token

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "session_token": "019cf96a-abcd-1234-5678-abcdef012345"
}

InviteCode

Returned when creating a room invite: the invite link itself.

Field	Type	Description
`id`	`string`	Invite link ID
`code`	`string`	The invite code
`room_id`	`string`	Room the invite points to
`created_by`	`string`	ID of the user who created it
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 last update timestamp
`expires_at`	`string?`	ISO 8601 time it stops working; null for one that works until it is revoked

{
  "id": "01920000-0000-7000-8000-000000000001",
  "code": "01920000-0000-7000-8000-000000000002",
  "room_id": "01920000-0000-7000-8000-000000000003",
  "created_by": "01920000-0000-7000-8000-000000000004",
  "created_at": "2026-10-17T12:00:00Z",
  "updated_at": "2026-10-17T12:00:00Z",
  "expires_at": "2026-10-24T12:00:00Z"
}

InviteInfo

Returned when fetching invite details.

Field	Type	Description
`code`	`string`	The invite code
`space_id`	`string`	Space ID
`space_name`	`string`	Space name
`description`	`string`	Space description
`member_count`	`integer`	Current member count

StorageStatus

Returned by storage status endpoints.

Field	Type	Description
`used_bytes`	`integer`	Bytes used in the default storage (files in your own buckets don't count)
`max_bytes`	`integer`	Maximum storage allowed
`upload_limit_bytes`	`integer`	Maximum single upload size
`percentage_used`	`number`	Usage as a percentage (0-100)

{
  "used_bytes": 52428800,
  "max_bytes": 33554432,
  "upload_limit_bytes": 10485760,
  "percentage_used": 15.6
}

StorageBucket

Returned by bucket management endpoints.

Field	Type	Description
`id`	`string`	Bucket UUID
`owner_id`	`string`	Owner user/space ID
`name`	`string`	Display name
`endpoint`	`string`	S3-compatible endpoint URL
`region`	`string`	Bucket region
`bucket_name`	`string`	Actual bucket name on the provider
`access_key_id`	`string`	Access key ID
`secret_access_key`	`string`	Secret access key
`is_active`	`boolean`	Whether this bucket is currently active
`is_default`	`boolean`	Whether this is the default system bucket
`use_path_style`	`boolean`	Whether to use path-style S3 URLs
`max_bytes`	`integer?`	Custom storage limit
`upload_limit_bytes`	`integer?`	Custom upload size limit
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 last update timestamp
`deleted_at`	`string?`	ISO 8601 soft-delete timestamp

Friend

Returned by friend list and accept endpoints.

Field	Type	Description
`id`	`string`	Friend record UUID
`request_id`	`string`	Original friend request UUID
`sender_id`	`string`	User who sent the original request
`recipient_id`	`string`	User who received the original request
`user_username`	`string`	The other user's username
`user_alias`	`string?`	The other user's display name
`user_avatar`	`string?`	The other user's avatar ID

FriendRequest

Returned by friend request endpoints.

Field	Type	Description
`id`	`string`	Request UUID
`sender_id`	`string`	Sender user ID
`recipient_id`	`string`	Recipient user ID
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 last update timestamp
`user_username`	`string`	The other user's username
`user_alias`	`string?`	The other user's display name
`user_avatar`	`string?`	The other user's avatar ID

MessageResponse

Returned by message list and get endpoints. Extends the base Message with additional resolved fields.

Field	Type	Description
`id`	`string`	Message UUID
`room_id`	`string?`	Room ID
`author_id`	`string?`	Author user ID
`content`	`string?`	Message text content
`type`	`integer`	Message type: 0 a message, 1 a voice note, 2 a pin notice
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 last update timestamp
`pinned_at`	`string?`	ISO 8601 time the message was pinned; null while it isn't
`sticker_attachment_id`	`string?`	Sticker attachment ID
`embeds`	Embed[]	Link embeds
`user` ?	User	Author user object
`attachments`	Attachment[]	File attachments
`reactions`	Reaction[]	Reactions grouped by emoji
`referenced_message` ?	ReferencedMessage	Resolved referenced message (for replies)
`conversation_id`	`string?`	Conversation ID (for DM/group messages)
`webhook_id` ?	`string?`	Webhook ID if sent by a webhook
`member_alias`	`string?`	Member server nickname at time of message

ReferencedMessage

Nested inside MessageResponse when a message is a reply. The replied message is always in the same room or conversation. Once it’s deleted, only type, message_id, room_id and space_id are left: the missing created_at is how to tell (a message without text still has its date).

Field	Type	Description
`type`	`integer?`	Reference type (always 0 = reply)
`message_id`	`string?`	Referenced message ID
`room_id`	`string?`	Room of the referenced message
`space_id`	`string?`	Space of the referenced message
`content` ?	`string?`	Content preview
`author_id` ?	`string`	Author ID of the referenced message
`author_name` ?	`string`	Author display name
`author_avatar` ?	`string?`	Author avatar ID
`created_at` ?	`string`	Creation timestamp of the referenced message; absent once it's deleted

MessageReference (Request)

Used in create message request body to reference another message (reply/forward).

Field	Type	Description
`type` ?	`integer`	Reference type (0 = reply)
`message_id` ?	`string`	Message ID to reference
`room_id` ?	`string`	Room ID of the referenced message
`space_id` ?	`string`	Space ID of the referenced message
`fail_if_not_exists` ?	`boolean`	Whether to fail if the referenced message doesn't exist (default: true)

CreateSpaceResult

Returned when creating a new space.

Field	Type	Description
`space`	Space	The created space
`role`	Role	The default @everyone role
`text_room`	Room	The default text room (general)
`voice_room`	Room	The default voice room (general)
`member`	Member	The creator's member object

MemberWithUser

Returned by member list endpoints. Combines member data with user profile.

Field	Type	Description
`id`	`string`	Member UUID
`space_id`	`string`	Space ID
`user_id`	`string`	User ID
`alias`	`string?`	Server nickname
`created_at`	`string`	Join timestamp
`updated_at`	`string`	Last update timestamp
`deleted_at`	`string?`	Always null: members who left aren't listed
`user`	User	Full user profile
`max_pos`	`integer`	Highest role position for sorting

ThreadMessageResponse

Returned by thread message endpoints. A lightweight message representation used in thread/reply contexts.

Field	Type	Description
`id`	`string`	Message UUID
`room_id`	`string?`	Room ID
`author_id`	`string?`	Author user ID
`content`	`string?`	Message text content
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 last update timestamp
`ref_type`	`integer?`	Reference type (e.g., reply)
`ref_message_id`	`string?`	Referenced message ID
`ref_room_id`	`string?`	Room of the referenced message
`ref_space_id`	`string?`	Space of the referenced message
`depth`	`integer`	Thread nesting depth
`webhook_id` ?	`string`	Webhook ID if sent by a webhook
`user` ?	User	Author user object
`member_alias`	`string?`	Member server nickname at time of message

GatewaySpaceCreatePayload

Full space snapshot sent with the SPACE_CREATE event when a user joins or creates a space.

Field	Type	Description
`space`	`GatewaySpaceCreateSpace`	The space object with embedded rooms, roles, and members
`rooms`	Record<string, Room>	Map of room ID to room object
`roles_permissions`	Record<string, Role>	Map of role ID to role object
`member_roles`	`Record<string, string[]>`	Map of member ID to array of role IDs
`overwrites`	Record<string, Overwrite[]>?	Map of room ID to permission overwrites
`owner_id`	`string`	Space owner user ID
`voice_states`	VoiceState[]	Current voice states in the space (empty when nobody is in voice)
`activities` ?	`Record<string, Activity[]>`	Map of user ID to that member's current activities; absent for bots and when nobody has one
`member_statuses` ?	`Record<string, integer>`	Map of user ID to online status; absent when none is known

VoiceState

A user’s state in a voice room, in SPACE_CREATE snapshots. version orders it against VOICE_STATE_UPDATE events.

Field	Type	Description
`room_id`	`string`	Voice room ID
`user_id`	`string`	User ID
`muted`	`boolean`	Whether the user is muted (always true without SpeakInVoice)
`deafened`	`boolean`	Whether the user is deafened
`screen_sharing`	`boolean`	Whether the user is screen sharing
`version`	`integer`	Version of this state; see VOICE_STATE_UPDATE

GatewayReady

Payload of the READY event users get after identify (bots get GatewayBotReady).

Field	Type	Description
`user`	User	The connected user
`sessionToken`	`string`	Gateway session token, for resuming
`guild_ids`	`string[]`	IDs of the user's spaces; a SPACE_CREATE follows for each
`unread_rooms`	`string[]`	Rooms with messages newer than the user's read state
`last_read_rooms`	`Record<string, string>`	Map of room ID to the last message ID the user read
`last_msg_rooms`	`Record<string, string>`	Map of room ID to its last message ID
`unread_convs`	`string[]`	Conversations with unread messages
`active_calls`	ReadyActiveCall[]?	Calls going on in the user's conversations
`ice_servers`	`RTCIceServer[]`	ICE servers for voice peer connections: the ones the gateway uses itself. Each has urls, plus username and credential when set; credentialType (always "password") is added by the WebRTC library and can be ignored

GatewayBotReady

Payload of the READY event bots get.

Field	Type	Description
`user`	User	The bot user
`sessionToken`	`string`	Gateway session token, for resuming
`guild_ids`	`string[]`	IDs of the spaces this shard handles
`shard`	`[integer, integer]`	This connection's shard_id and num_shards

ReadyActiveCall

Field	Type	Description
`conversation_id`	`string`	Conversation the call is in
`initiator_id`	`string`	User who started the call
`voice_states`	CallVoiceState[]?	Who is connected to the call; null before anyone joins

CallVoiceState

Field	Type	Description
`user_id`	`string`	User ID
`muted`	`boolean`	Whether the user is muted
`deafened`	`boolean`	Whether the user is deafened
`screen_sharing`	`boolean`	Whether the user is screen sharing
`version`	`integer`	Version of this state; see VOICE_STATE_UPDATE

MessageSearchResponse

Returned by the message search endpoints of a space and of a conversation.

Field	Type	Description
`total_results`	`integer`	How many messages the search finds, all its pages together, counted up to 1000
`messages`	MessageResponse[]	This page of them, newest first

MentionCounts

Returned by the mention counts endpoint.

Field	Type	Description
`(key)`	`string`	Room or conversation ID
`(value)`	`integer`	Number of unread mentions

{
  "019cf96a-be82-72c5-830f-75e85355d800": 3,
  "019cf96a-cf44-72c5-830f-75e85355d900": 1
}