OwnCord/API.md

REST API Spec

Base URL: https://{server}:{port}/api

Auth: session token in cookie session (set on login) or Authorization: Bearer {token} header for programmatic access.

All responses are JSON. Errors return { "error": "CODE", "message": "Human-readable detail" }.

---

Auth

Method	Endpoint	Auth	Description
POST	/api/auth/register	None (requires invite code)	Create account
POST	/api/auth/login	None	Login, returns session token
POST	/api/auth/logout	Yes	Invalidate current session
POST	/api/auth/verify-totp	Partial (after login with 2FA)	Submit TOTP code

POST /api/auth/register

// Request
{ "username": "alex", "password": "strongpassword", "invite_code": "abc123" }
// Response 201
{ "user": { "id": 1, "username": "alex" }, "token": "session-token" }

POST /api/auth/login

// Request
{ "username": "alex", "password": "strongpassword" }
// Response 200 (no 2FA)
{ "token": "session-token", "requires_2fa": false }
// Response 200 (2FA required)
{ "partial_token": "temp-token", "requires_2fa": true }

---

Users

Method	Endpoint	Auth	Description
GET	/api/users/me	Yes	Get current user profile
PATCH	/api/users/me	Yes	Update own profile (username, avatar)
PUT	/api/users/me/password	Yes	Change password
POST	/api/users/me/totp/enable	Yes	Start 2FA setup, returns QR URI + backup codes
POST	/api/users/me/totp/confirm	Yes	Confirm 2FA with first TOTP code
DELETE	/api/users/me/totp	Yes	Disable 2FA
GET	/api/users/me/sessions	Yes	List active sessions
DELETE	/api/users/me/sessions/{id}	Yes	Revoke a session

---

Channels

Method	Endpoint	Auth	Description
GET	/api/channels	Yes	List all channels user can see
GET	/api/channels/{id}/messages	Yes	Paginated message history
GET	/api/channels/{id}/pins	Yes	Get pinned messages
POST	/api/channels/{id}/pins/{msg_id}	Yes (mod)	Pin a message
DELETE	/api/channels/{id}/pins/{msg_id}	Yes (mod)	Unpin a message

GET /api/channels/{id}/messages

Query params: before (message ID), limit (1-100, default 50)

// Response 200
{
  "messages": [
    {
      "id": 1042,
      "channel_id": 5,
      "user": { "id": 1, "username": "alex", "avatar": "uuid.png" },
      "content": "Hello!",
      "reply_to": null,
      "attachments": [],
      "reactions": [{ "emoji": "👍", "count": 2, "me": true }],
      "pinned": false,
      "edited_at": null,
      "deleted": false,
      "timestamp": "2026-03-14T10:30:00Z"
    }
  ],
  "has_more": true
}

---

File Uploads

Method	Endpoint	Auth	Description
POST	/api/uploads	Yes	Upload a file (multipart)
GET	/api/files/{uuid}	Yes	Download a file

POST /api/uploads

Multipart form data. Field: file. Max size from server config (default 25MB).

// Response 201
{ "id": "upload-uuid", "filename": "photo.jpg", "size": 204800, "mime": "image/jpeg", "url": "/api/files/upload-uuid" }

Server validates: magic bytes, rejects executables, strips EXIF, stores with UUID filename.

---

Search

Method	Endpoint	Auth	Description
GET	/api/search	Yes	Full-text search across accessible channels

Query params: q (search query), channel_id (optional filter), limit (default 25)

// Response 200
{
  "results": [
    {
      "message_id": 1042,
      "channel_id": 5,
      "channel_name": "general",
      "user": { "id": 1, "username": "alex" },
      "content": "...matched text...",
      "timestamp": "2026-03-14T10:30:00Z"
    }
  ]
}

---

Invites

Method	Endpoint	Auth	Description
GET	/api/invites	Yes (admin)	List all invites
POST	/api/invites	Yes (manage_invites)	Create an invite
DELETE	/api/invites/{id}	Yes (manage_invites)	Revoke an invite

POST /api/invites

// Request
{ "max_uses": 5, "expires_in_hours": 48 }
// Response 201
{ "id": 1, "code": "abc123def", "url": "chatserver://invite/abc123def", "max_uses": 5, "expires_at": "2026-03-16T10:30:00Z" }

---

Admin Endpoints (admin panel uses these)

Method	Endpoint	Auth	Description
GET	/api/admin/stats	Admin	Server stats (users, messages, disk, uptime)
GET	/api/admin/users	Admin	List all users with details
PATCH	/api/admin/users/{id}	Admin	Update user (role, ban/unban)
DELETE	/api/admin/users/{id}/sessions	Admin	Force logout a user
POST	/api/admin/channels	Admin	Create channel
PATCH	/api/admin/channels/{id}	Admin	Update channel
DELETE	/api/admin/channels/{id}	Admin	Delete channel
GET	/api/admin/audit-log	Admin	View audit log (paginated)
POST	/api/admin/backup	Owner	Trigger manual backup
GET	/api/admin/backups	Owner	List available backups
POST	/api/admin/backups/{id}/restore	Owner	Restore from backup
GET	/api/admin/settings	Admin	Get server settings
PATCH	/api/admin/settings	Admin	Update server settings
GET	/api/admin/update-check	Admin	Check for new server version

---

WebRTC / TURN Credentials

Method	Endpoint	Auth	Description
GET	/api/voice/credentials	Yes	Get time-limited TURN credentials

// Response 200
{
  "ice_servers": [
    { "urls": "stun:server:3478" },
    { "urls": "turn:server:3478", "username": "timestamp:userid", "credential": "hmac-hash" }
  ],
  "expires_in": 86400
}

---

Custom Emoji

Method	Endpoint	Auth	Description
GET	/api/emoji	Yes	List all custom emoji
POST	/api/emoji	Yes (admin)	Upload new emoji
DELETE	/api/emoji/{id}	Yes (admin)	Delete emoji

---

Soundboard

Method	Endpoint	Auth	Description
GET	/api/sounds	Yes	List all soundboard sounds
POST	/api/sounds	Yes (permission)	Upload a sound
DELETE	/api/sounds/{id}	Yes (admin)	Delete a sound

---

Health Check

Method	Endpoint	Auth	Description
GET	/api/health	None	Returns 200 if server is running

{ "status": "ok", "version": "1.0.0", "uptime": 86400 }

---

Error Codes

Code	HTTP Status	Meaning
UNAUTHORIZED	401	Missing or invalid session
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Too many requests (includes retry_after)
INVALID_INPUT	400	Bad request body or params
CONFLICT	409	e.g. username already taken
TOO_LARGE	413	File exceeds upload limit
SERVER_ERROR	500	Internal server error