GitHub

REST API Reference

Complete reference for the STORM DAY Gateway REST API. All endpoints are accessed through the Gateway at port 8080.

Response Format

All API responses are wrapped in a consistent envelope format:

// Success response
{
  "ok": true,
  "data": { ... }
}

// Error response
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials"
  }
}

Authentication

Every authenticated request must include:

Authorization: Bearer <access_token>
X-User-ID: <uuid>

User ID can also be sent as a query parameter (?user_id=) as a fallback.

Authentication Endpoints

User registration, login, token refresh, and logout.

MethodEndpoint
POST/auth/register
POST/auth/login
POST/auth/refresh
POST/auth/logout

POST /auth/register

// Request
POST /auth/register
Content-Type: application/json

{
  "username": "john_doe",
  "display_name": "John Doe",
  "email": "john@example.com",
  "password": "securepassword123"
}

// Response
{
  "ok": true,
  "data": {
    "id": "uuid",
    "username": "john_doe",
    "display_name": "John Doe",
    "email": "john@example.com"
  }
}

POST /auth/login

// Request
POST /auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "securepassword123"
}

// Response
{
  "ok": true,
  "data": {
    "access_token": "eyJhbG...",
    "refresh_token": "eyJhbG...",
    "user": {
      "id": "uuid",
      "username": "john_doe",
      "display_name": "John Doe",
      "email": "john@example.com",
      "avatar_url": null
    }
  }
}

Users Endpoints

Search users and manage profiles.

MethodEndpoint
GET/users/search?q=...
GET/users/{id}
PUT/users/{id}
PATCH/users/{id}

GET /users/search

// Request
GET /users/search?q=john
Authorization: Bearer <token>

// Response
{
  "ok": true,
  "data": [
    {
      "id": "uuid",
      "username": "john_doe",
      "display_name": "John Doe",
      "avatar_url": "https://..."
    }
  ]
}

Messages Endpoints

Send, retrieve, edit, and delete messages.

MethodEndpoint
POST/api/messages
GET/api/messages?conversation_id={id}
GET/api/messages/{id}
PUT/api/messages/{id}
PATCH/api/messages/{id}
DELETE/api/messages/{id}
POST/api/messages/{id}/receipt

POST /api/messages

// Request
POST /api/messages
Content-Type: application/json
Authorization: Bearer <token>
X-User-ID: <uuid>

{
  "sender_id": "uuid",
  "conversation_id": "conversation-uuid",
  "content": "Hello, world!",
  "reply_to_id": "optional-message-uuid",
  "forward_from_id": "optional-message-uuid",
  "attachment": "optional-file-url"
}

// Response
{
  "ok": true,
  "data": {
    "id": "message-uuid",
    "sender_id": "uuid",
    "conversation_id": "conversation-uuid",
    "content": "Hello, world!",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Groups / Conversations Endpoints

Create and manage group conversations.

MethodEndpoint
POST/api/groups
GET/api/groups
GET/api/groups/{id}
DELETE/api/groups/{id}
POST/api/groups/{id}/leave
GET/api/groups/{id}/members
POST/api/groups/{id}/members
PATCH/api/groups/{id}/members/{user_id}/role
DELETE/api/groups/{id}/members/{user_id}

POST /api/groups

// Request
POST /api/groups
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Project Team",
  "member_ids": ["uuid1", "uuid2", "uuid3"]
}

// Response
{
  "ok": true,
  "data": {
    "id": "group-uuid",
    "name": "Project Team",
    "created_at": "2024-01-15T10:30:00Z",
    "members": [...]
  }
}

Media Endpoints

File and media upload handling.

MethodEndpoint
POST/media/upload

POST /media/upload

// Request
POST /media/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

file: <binary>

// Response
{
  "ok": true,
  "data": {
    "url": "https://storage.example.com/files/uuid.jpg",
    "filename": "image.jpg",
    "size": 12345,
    "content_type": "image/jpeg"
  }
}