API Reference

Complete REST API and WebSocket protocol documentation for Monaime

REST API

https://api.monaime.app/api/*

WebSocket

wss://api.monaime.app/ws/chat

Web App

https://monaime.app

🔐 Authentication

All protected endpoints require a JWT token from Supabase Auth in the Authorization header:

Authorization: Bearer <supabase-jwt-token>

Tokens are obtained via Supabase Auth (email/password or OAuth). The server validates tokens using supabase.auth.getUser(token).

⏱️ Rate Limiting

100 req/min

REST API per user

30 msg/min

WebSocket per user

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

1 Dashboard

GET /api/dashboard Get all initial data (batch)

Description

Returns all user data in a single request. Used by clients on app launch to hydrate local state.

Response

{
  "wallets": [...],        // All wallets
  "goals": [...],          // Savings goals
  "categories": [...],     // All categories
  "budgets": [...],        // Active budgets
  "contacts": [...],       // Contacts with debts
  "recurring": [...],      // Recurring templates
  "transactions": [...],   // Recent transactions
  "recentTransactions": [...] // Last 50 transactions
}

2 Chat & Messages

POST /api/chat/message Send chat message (REST)

Request Body

{
  "content": string,       // User message text
  "chatHistory": array?    // Previous messages for context
}

Response

{
  "messages": [
    { "type": "text", "content": "..." },
    { "type": "card", "data": {...} }
  ]
}

GET /api/chat/history Get bot messages for offline sync

Query Parameters

since=ISO8601   // Messages after this timestamp
limit=50           // Max messages to return

DELETE /api/chat/history Clear all chat history

POST /api/chat/messages/:id/feedback Rate a message (like/dislike)

Request Body

{
  "type": "like" | "dislike",
  "comment": string?,
  "context": object?
}

3 Wallets

GET /api/wallets List wallets

Query Parameters

type=regular|goal    // Filter by type
include_archived=true  // Include archived wallets

Response

{
  "data": [{
    "id": uuid,
    "name": string,
    "currency": "RUB",
    "cached_balance": number,
    "icon": string?,
    "color": string?,
    "is_default": boolean,
    "is_archived": boolean
  }]
}

POST /api/wallets Create wallet

Request Body

{
  "name": string,         // Required
  "currency": "RUB",      // Default: RUB
  "icon": string?,
  "color": string?
}

GET /api/wallets/:id Get wallet details

PATCH /api/wallets/:id Update wallet

Request Body

{
  "name": string?,
  "balance": number?,     // Creates adjustment tx
  "currency": string?
}

DELETE /api/wallets/:id Delete wallet (orphans transactions)

POST /api/wallets/:id/archive Archive wallet

POST /api/wallets/:id/unarchive Unarchive wallet

POST /api/wallets/:id/set-default Set as default wallet

GET /api/wallets/settings/default Get default wallet ID

Goals (wallets with type='goal')

GET /api/wallets/goals List goals

Response includes

{
  "data": [{
    "id": uuid,
    "name": string,
    "target_amount": number,
    "cached_balance": number,  // Current saved
    "target_date": date?,
    "progress": number        // Percentage 0-100
  }]
}

POST /api/wallets/goals Create goal

Request Body

{
  "name": string,
  "target_amount": number,
  "initial_amount": number?,
  "target_date": date?
}

4 Transactions

GET /api/transactions List transactions (paginated)

Query Parameters

page=1             // Page number
limit=50           // Items per page
wallet_id=uuid     // Filter by wallet
category_id=uuid   // Filter by category
type=income|expense // Filter by type
start_date=ISO     // Date range start
end_date=ISO       // Date range end

Response

{
  "data": [{
    "id": uuid,
    "amount": number,
    "currency": string,
    "description": string?,
    "date": ISO8601,
    "type": "income" | "expense",
    "wallet": { "id", "name" },
    "category": { "id", "name", "icon" }
  }],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": number,
    "pages": number
  }
}

POST /api/transactions Create transaction

Request Body

{
  "wallet_id": uuid,       // Required
  "category_id": uuid,     // Required
  "amount": number,        // Required, positive
  "currency": "RUB"?,      // Default: wallet currency
  "description": string?,   // Max 500 chars
  "date": ISO8601?         // Default: now
}

GET /api/transactions/:id Get transaction details

PATCH /api/transactions/:id Update transaction

DELETE /api/transactions/:id Delete transaction

POST /api/transactions/transfer Transfer between wallets

Request Body

{
  "from_wallet_id": uuid,
  "to_wallet_id": uuid,
  "amount": number,
  "description": string?
}

Response

{
  "success": true,
  "expense_tx_id": uuid,  // Outgoing transaction
  "income_tx_id": uuid    // Incoming transaction
}

GET /api/transactions/stats/summary Financial summary

Query Parameters

period=day|week|month|year

Response

{
  "income": number,
  "expense": number,
  "balance": number,
  "byCategory": [
    { "name": "Food", "amount": 15000, "percentage": 35 }
  ]
}

Bulk Operations

POST /api/bulk/transactions Create multiple transactions

PATCH /api/bulk/transactions Update multiple transactions

DELETE /api/bulk/transactions Delete multiple transactions

5 Categories

GET /api/categories List categories

Query Parameters

type=income|expense // Filter by type

POST /api/categories Create category

Request Body

{
  "name": string,
  "type": "income" | "expense",
  "icon": string?,
  "color": string?,
  "parent_id": uuid?   // For subcategories
}

GET/api/categories/:idGet category details

PATCH/api/categories/:idUpdate category

DELETE/api/categories/:idDelete category

6 Budgets

GET /api/budgets List budgets with current spend

Response

{
  "data": [{
    "id": uuid,
    "name": string,
    "amount": number,           // Budget limit
    "current_spent": number,    // Spent so far
    "period": "monthly" | "weekly",
    "percentage": number,       // Usage % (0-100+)
    "category": { "id", "name", "icon" }
  }]
}

GET/api/budgets/:idGet budget details

PATCH/api/budgets/:idUpdate budget

DELETE/api/budgets/:idDelete budget

7 Contacts & Debts

GET /api/contacts List contacts with debt balances

Response

{
  "data": [{
    "contact_name": string,
    "cached_balance": number,   // + = they owe, - = you owe
    "due_date": date?,
    "is_overdue": boolean
  }]
}

GET/api/contacts/:nameGet debt details for contact

POST/api/contactsCreate debt contact

PATCH/api/contacts/:nameUpdate contact

DELETE/api/contacts/:nameClose debt (archive)

8 Recurring Payments

GET /api/recurring List recurring payments

Response

{
  "data": [{
    "id": uuid,
    "description": string,
    "amount": number,
    "frequency": "daily"|"weekly"|"monthly"|"yearly",
    "next_run_date": date,
    "wallet": { "id", "name" },
    "category": { "id", "name" }
  }]
}

POST/api/recurringCreate recurring payment

PATCH/api/recurring/:idUpdate recurring

DELETE/api/recurring/:idCancel recurring (soft delete)

9 Notifications

GET/api/notificationsList notifications

GET/api/notifications/unreadGet unread notifications

GET/api/notifications/countGet unread count

POST/api/notifications/seenMark notifications as seen

POST/api/notifications/:id/actAccept notification action

POST/api/notifications/:id/dismissDismiss notification

POST/api/notifications/:id/snoozeSnooze notification

DELETE/api/notifications/:idDelete notification

DELETE/api/notifications/clearClear all dismissed/seen

10 Triggers

GET /api/triggers Get trigger configuration

Response

{
  "data": {
    "enabled": boolean,
    "push_enabled": boolean,
    "quiet_hours_start": "23:00",
    "quiet_hours_end": "08:00",
    "triggers": {
      "limit_warning": { "enabled": true, "threshold": 80 },
      "goal_milestone": { "enabled": true },
      ...
    }
  }
}

PATCH/api/triggersUpdate trigger config

POST/api/triggers/toggle/:triggerTypeToggle specific trigger

POST/api/triggers/resetReset to defaults

11 Voice & Receipt

POST /api/voice/transcribe Transcribe audio (Whisper)

Request

Content-Type: multipart/form-data

file: audio file (m4a, wav, mp3)

Response

{ "text": string }

POST /api/receipt/scan Scan receipt image (Vision AI)

Request Body

{ "image": base64 string }

Response

{
  "transactions": [{ "description", "amount", "category" }],
  "store": string?,
  "total": number?
}

POST /api/receipt/parse-text Parse receipt text or bank screenshot

12 Import

POST /api/import/parse Parse CSV with AI suggestions

Request

Content-Type: multipart/form-data

file: CSV file

Response

{
  "sessionId": string,
  "rowCount": number,
  "headers": [string],
  "preview": [...],
  "suggestion": {
    "mappings": { "amount": "col_name", ... }
  }
}

POST /api/import/execute Execute import with mappings

13 User & Settings

GET /api/user/settings Get user settings

Response

{
  "default_currency": "RUB",
  "default_wallet_id": uuid?,
  "chat_retention_days": number,
  "language": string
}

PATCH/api/user/settingsUpdate user settings

DELETE/api/accountDelete account (atomic)

GET/api/statsGet financial statistics

Action History (Undo)

GET/api/action-historyList recent actions

POST/api/action-history/:id/undoUndo action

Push Notifications

POST/api/push/registerRegister device token

POST/api/push/unregisterUnregister device token

Other

GET/api/currencyGet currency exchange rates

GET/api/healthHealth check (no auth)

14 WebSocket Protocol

💡

Connection URL wss://api.monaime.app/ws/chat — primary real-time channel for chat, notifications, and data sync.

Connection Flow

// 1. Connect
const ws = new WebSocket('wss://api.monaime.app/ws/chat');

// 2. Authenticate (first message)
ws.send(JSON.stringify({
  "token": "Bearer <jwt>",
  "platform": "ios",
  "appVersion": "1.0.0",
  "capabilities": ["streaming", "quick_actions", "card_grouping"]
}));

// 3. Server responds: { "type": "authenticated" }
// 4. Server sends initial data: { "type": "data_updated", "payload": {...} }

Message Types

Client → Server

Type	Payload	Description
message	`{ content, chatHistory? }`	Send chat message
quick_action	`{ command, params, label? }`	Execute quick action button
stop_generation	`{}`	Stop AI streaming

Server → Client

Type	Payload	Description
authenticated	`{}`	Auth successful
typing	`{}`	Bot is thinking
stream_start	`{ id }`	Begin streaming response
stream	`{ content, id }`	Streaming content chunk (incremental)
stream_chunk	`{ content, id }`	Streaming content (full accumulated)
stream_end	`{ id }`	Streaming finished
generation_stopped	`{}`	User stopped generation
message	`{ message: { type, content?, data? } }`	Bot text message
result	`{ content }`	Bot text result
card	`{ card: { type, data } }`	Single entity card
batch-cards	`{ cards: [...] }`	Multiple entity cards
grouped-cards	`{ groups: [{ title, cards }] }`	Cards grouped by title
data_updated	`{ payload: { wallets, categories, ... } }`	Cache invalidation / data sync
ai_notification	`{ payload: notification }`	Proactive AI notification
error	`{ message }`	Error occurred

Card Types

Type	Key Fields
transaction	id, amount, currency, description, date, wallet, category
wallet	id, name, currency, cached_balance, icon, color, is_default
category	id, name, type, icon, color, budget_amount, current_spent
debt	contact_name, cached_balance, due_date, is_overdue
goal	id, name, target_amount, cached_balance, progress, target_date
recurring	id, description, amount, frequency, next_run_date
budget	id, name, amount, current_spent, period, percentage
chart	chartType, data, title, subtitle
quick_actions	actions: [{ command, params, label }]

API Reference

🔐 Authentication

⏱️ Rate Limiting

On this page

1 Dashboard

Description

Response

2 Chat & Messages

Request Body

Response

Query Parameters

Request Body

3 Wallets

Query Parameters

Response

Request Body

Request Body

Goals (wallets with type='goal')

Response includes

Request Body

4 Transactions

Query Parameters

Response

Request Body

Request Body

Response

Query Parameters

Response

Bulk Operations

5 Categories

Query Parameters

Request Body

6 Budgets

Response

7 Contacts & Debts

Response

8 Recurring Payments

Response

9 Notifications

10 Triggers

Response

11 Voice & Receipt

Request

Response

Request Body

Response

12 Import

Request

Response

13 User & Settings

Response

Action History (Undo)

Push Notifications

Other

14 WebSocket Protocol

Connection Flow

Message Types

Client → Server

Server → Client

Card Types