LobotomyLabs/dumpsterChat
2
0
Fork 0
Code Issues Pull Requests Actions Packages Releases 1 Wiki Activity
Page: API Reference
Pages
API Reference Architecture Frontend Design Getting Started Home Phase 3 Phase 4 Phase 5 Phase 6 Profiles Roadmap Self Hosting Troubleshooting Voice and Video
Clone
4
API Reference
hobokenchicken edited this page 2026-06-28 19:20:43 -04:00
Table of Contents

API Reference

Base URL: /api/v1

Authentication

All endpoints except auth require a valid session cookie (dumpster_session).

POST /auth/register

{
  "email": "user@example.com",
  "username": "username",
  "display_name": "Nickname",
  "password": "hunter2"
}

Returns: { "id": "uuid" }

POST /auth/login/password

{
  "email": "user@example.com",
  "password": "hunter2"
}

Returns: { "id": "uuid" }

POST /auth/logout

Clears session cookie. Returns 204.

GET /auth/me

Returns full user profile including bio, accent_color, status_text, avatar.

PATCH /auth/me

Update profile fields. All optional:

{
  "display_name": "New Name",
  "bio": "Hello world",
  "accent_color": "#fe8019",
  "status_text": "brb"
}

Servers

POST /servers

{
  "name": "My Server",
  "icon": "https://..."
}

GET /servers

List servers the authenticated user is a member of.

GET /servers/:id

Get a specific server.

PATCH /servers/:id

Update server name/icon. Owner only.

DELETE /servers/:id

Delete a server. Owner only.

Channels

POST /channels

{
  "server_id": "uuid",
  "name": "general",
  "type": "text",
  "category": "TEXT",
  "position": 0
}

GET /channels?server_id=uuid

List channels in a server.

GET /channels/:id

Get a channel.

PATCH /channels/:id

Update channel fields.

DELETE /channels/:id

Delete a channel.

Messages

GET /channels/:channelID/messages?limit=50&before=messageID

Get messages in a channel. Cursor-based pagination.

POST /channels/:channelID/messages

{
  "content": "hello",
  "reply_to": "optional-message-uuid"
}

PATCH /messages/:messageID

{
  "content": "edited message"
}

DELETE /messages/:messageID

Delete a message. Author only.

Reactions

POST /messages/:messageID/reactions

{
  "emoji": "👍"
}

DELETE /messages/:messageID/reactions/:emoji

Remove a reaction.

GET /messages/:messageID/reactions

List reactions grouped by emoji with user IDs and counts.

Voice

POST /voice/token

{
  "room_name": "voice-channel-id"
}

Returns: { "token": "jwt...", "livekit_url": "wss://..." }

GET /voice/rooms/:roomID/participants

List participants in a voice room.

Invites

POST /invites

{
  "server_id": "uuid",
  "expires_hours": 24,
  "max_uses": 10
}

Returns: { "code": "ABCD1234", "url": "https://..." }

GET /invites/:code

Get invite info (server name, inviter, expiry).

POST /invites/:code/join

Join server via invite code.

Bots

POST /bots

{
  "name": "Modbot",
  "description": "Moderation bot"
}

Returns bot with token (shown only once).

GET /bots

List bots owned by current user.

GET /bots/:id

Get bot details.

PATCH /bots/:id

{
  "name": "New Name",
  "description": "New description"
}

DELETE /bots/:id

Delete a bot.

POST /bots/:id/servers

{
  "server_id": "uuid"
}

Add bot to server.

DELETE /bots/:id/servers/:serverID

Remove bot from server.

POST /bots/:id/regenerate-token

Returns: { "token": "new_token..." }

Slash Commands

POST /bots/:id/commands

{
  "server_id": "uuid",
  "name": "kick",
  "description": "Kick a user"
}

GET /bots/:id/commands

List commands for a bot.

DELETE /bots/:id/commands/:cmdID

Delete a command.

GET /servers/:serverID/commands

List all commands for a server (for autocomplete).

Webhooks

POST /channels/:channelID/webhooks

{
  "name": "GitHub"
}

Returns: { "id": "...", "token": "...", "url": "https://host/webhooks/{id}/{token}" }

GET /channels/:channelID/webhooks

List webhooks for a channel.

DELETE /webhooks/:webhookID

Delete a webhook.

POST /webhooks/:webhookID/:token

Execute webhook (public, no auth required):

{
  "content": "New commit pushed",
  "username": "GitHub",
  "avatar_url": "https://..."
}

Roles & Permissions

POST /servers/:serverID/roles

{
  "name": "Moderator",
  "color": "#fe8019",
  "permissions": 76,
  "position": 1
}

Create a role. Requires MANAGE_SERVER permission.

GET /servers/:serverID/roles

List roles for a server.

PATCH /servers/:serverID/roles/:roleID

{
  "name": "New Name",
  "color": "#fabd2f",
  "permissions": 127
}

Update a role. Requires MANAGE_SERVER permission.

DELETE /servers/:serverID/roles/:roleID

Delete a role. Cannot delete the default @everyone role. Requires MANAGE_SERVER permission.

PUT /servers/:serverID/members/:userID/roles

{
  "role_ids": ["uuid1", "uuid2"]
}

Set member roles (replaces existing). Requires MANAGE_SERVER permission.

GET /servers/:serverID/members/:userID/roles

Get roles assigned to a member.

Permission Constants

Permission Bit Value
VIEW_CHANNEL 0 1
SEND_MESSAGES 1 2
MANAGE_MESSAGES 2 4
KICK_MEMBERS 3 8
BAN_MEMBERS 4 16
MANAGE_SERVER 5 32
MANAGE_CHANNELS 6 64
ADMINISTRATOR 7 128
CONNECT_VOICE 8 256
SPEAK_VOICE 9 512
SHARE_SCREEN 10 1024

Push Notifications

GET /push/vapid-public-key

Returns the VAPID public key for push subscription.

POST /push/subscribe

{
  "endpoint": "https://...",
  "p256dh": "...",
  "auth": "..."
}

Subscribe to push notifications.

POST /push/unsubscribe

{
  "endpoint": "https://..."
}

Unsubscribe from push notifications.

WebAuthn (Passkeys)

POST /auth/webauthn/register/begin

Begin passkey registration for authenticated user. Returns WebAuthn credential creation options.

POST /auth/webauthn/register/finish

Complete passkey registration. Stores credential in webauthn_credentials table.

POST /auth/webauthn/login/begin

Begin passkey login (no auth required). Returns WebAuthn assertion options.

POST /auth/webauthn/login/finish

Complete passkey login. Creates session and sets cookie on success.

File Upload

POST /upload

Multipart form upload. Returns: { "url": "/files/uuid.ext", "size": 12345 }

GET /files/:filename

Serve uploaded file.

Giphy

GET /gifs/search?q=query

Search GIFs (requires GIPHY_API_KEY).

GET /gifs/trending

Get trending GIFs.

WebSocket

Connect to /ws with the session cookie. Incoming events:

  • MESSAGE_CREATE
  • MESSAGE_UPDATE
  • MESSAGE_DELETE
  • CHANNEL_CREATE
  • CHANNEL_UPDATE
  • CHANNEL_DELETE
  • SERVER_MEMBER_ADD
  • SERVER_MEMBER_REMOVE
  • PRESENCE_UPDATE
  • TYPING_START
  • REACTION_ADD
  • REACTION_REMOVE
  • VOICE_JOIN
  • VOICE_LEAVE
  • VOICE_MUTE
  • VOICE_DEAFEN
  • BOT_JOIN
  • BOT_LEAVE

Navigation