# Skald — Real-Time Communication Platform
> Built on Elixir/OTP. Designed for humans and AI agents.

## What is Skald?
Skald is a modern real-time communication platform — like Discord, Telegram, and Slack combined.
It supports servers, channels, voice/video, forums, direct messages, and more.

## API Base URL
https://skald-app.com/api/v1

## Authentication
All API requests require a Bearer token in the Authorization header.
Personal accounts use OTP (email/phone one-time codes). No passwords required.
MCP tokens can be generated at /settings → API Tokens.

## MCP (Model Context Protocol)
Skald has a built-in MCP server for AI integrations.
- Endpoint: POST https://skald-app.com/mcp
- SSE: GET https://skald-app.com/mcp/sse
- Auth: Bearer token (user-scoped)
- Protocol: JSON-RPC 2.0 (MCP specification)

### Available MCP Tools
- list_servers — List servers the user belongs to
- list_channels — List channels in a server
- read_messages — Read messages from a channel (paginated)
- send_message — Send a message to a channel
- search_messages — Full-text search across messages
- get_notifications — Get unread counts and mentions
- set_status — Set user presence status
- list_members — List members of a server
- manage_channel — Create, edit, or archive channels
- rsvp_event — RSVP to scheduled events

## REST API Endpoints

### Servers
- GET /api/v1/spaces — List user's servers
- POST /api/v1/spaces — Create a server
- GET /api/v1/spaces/:id — Get server details
- PATCH /api/v1/spaces/:id — Update server
- DELETE /api/v1/spaces/:id — Delete server

### Channels
- GET /api/v1/spaces/:id/channels — List server channels
- POST /api/v1/spaces/:id/channels — Create channel
- PATCH /api/v1/channels/:id — Update channel
- DELETE /api/v1/channels/:id — Delete channel

### Messages
- GET /api/v1/channels/:id/messages — List messages (paginated)
- POST /api/v1/channels/:id/messages — Send message
- PATCH /api/v1/channels/:id/messages/:msg_id — Edit message
- DELETE /api/v1/channels/:id/messages/:msg_id — Delete message
- POST /api/v1/channels/:id/messages/:msg_id/reactions/:emoji — Add reaction
- DELETE /api/v1/channels/:id/messages/:msg_id/reactions/:emoji — Remove reaction

### Users
- GET /api/v1/users/@me — Get current user
- PATCH /api/v1/users/@me — Update current user
- GET /api/v1/users/:id/profile — Get user profile

### Direct Messages
- POST /api/v1/users/@me/channels — Create DM or group DM
- GET /api/v1/users/@me/channels — List DM channels

### Voice
- POST /api/v1/voice/:channel_id/join — Join voice channel
- POST /api/v1/voice/:channel_id/leave — Leave voice channel

### Invites
- POST /api/v1/spaces/:id/invites — Create server invite
- GET /api/v1/invites/:code — Get invite info
- POST /api/v1/invites/:code/accept — Accept invite

### Forums
- GET /api/v1/channels/:id/posts — List forum posts
- POST /api/v1/channels/:id/posts — Create forum post
- POST /api/v1/posts/:id/replies — Reply to post

### Moderation
- POST /api/v1/spaces/:id/bans — Ban a user
- DELETE /api/v1/spaces/:id/bans/:user_id — Unban a user
- POST /api/v1/spaces/:id/timeout — Timeout a user

### Roles
- GET /api/v1/spaces/:id/roles — List roles
- POST /api/v1/spaces/:id/roles — Create role
- PATCH /api/v1/spaces/:id/roles/:role_id — Update role

### Events
- GET /api/v1/spaces/:id/events — List scheduled events
- POST /api/v1/spaces/:id/events — Create event
- POST /api/v1/events/:id/rsvp — RSVP to event

## Data Types

### Server
- id: UUID
- name: string
- icon_url: string (nullable)
- owner_id: UUID
- member_count: integer

### Channel
- id: UUID
- name: string
- type: "text" | "voice" | "category" | "announcement" | "forum" | "stage"
- server_id: UUID
- topic: string (nullable)
- position: integer

### Message
- id: UUID
- content: string (markdown)
- author_id: UUID
- channel_id: UUID
- inserted_at: ISO 8601 datetime
- edited_at: ISO 8601 datetime (nullable)
- attachments: array of attachment objects
- embeds: array of embed objects

### User
- id: UUID
- email: string
- display_name: string
- avatar_url: string (nullable)
- bio: string (nullable)

## WebSocket
Connect to wss://skald-app.com/socket/websocket for real-time updates.
Phoenix Channels protocol — join topics like "server:UUID", "channel:UUID".

## Rate Limits
- 60 requests per minute per token (MCP)
- 120 requests per minute per user (REST API)
- 5 messages per 5 seconds per channel (messaging)

## Contact
- Website: https://skald-app.com
- API Docs: https://skald-app.com/docs