API Reference & Interactive Tester

Expense & User Bank Account Management REST API. Includes App Home Screen Dashboard API, profile photos, transaction descriptions, and invoice receipts/photos. Writable endpoints expect Content-Type: application/json.

Session: Not signed in

Overview & Architecture

This API treats each User directly as a bank account. Each user record manages account details including full_name, email, profile_photo, and account balance.

Every transaction supports transaction description and attaching invoice photos (receipts/bills).

Authentication

Pass JWT tokens in HTTP Header: Authorization: Bearer <token>.

Default Seeded Credentials

  • Admin Account: Email: admin@example.com | Password: password123 (Role: admin)
  • Regular User Account: Email: user@example.com | Password: password123 (Role: user)

GET /v1/home Authenticated User

App Home Screen Dashboard API. Returns the total balance across user accounts and the top 10 most recent transactions.

Sample Response (200 OK) 
{
  "total_balance": 1500.00,
  "accounts_count": 1,
  "user": {
    "id": "3ecafeed-b74c-4ac8-99a5-9ab1bfdcbb79",
    "email": "user@example.com",
    "full_name": "John Doe",
    "profile_photo": "https://ui-avatars.com/api/?name=John+Doe",
    "balance": 1500.00,
    "role": "user"
  },
  "recent_transactions": [
    {
      "id": "tx1",
      "type": "expense",
      "amount": 250.00,
      "category": "Grocery",
      "description": "Weekly organic fruits purchase",
      "invoice_photo": "https://example.com/invoices/receipt.jpg",
      "balance_after": 1500.00,
      "created_at": "2026-09-04 23:31:30"
    }
  ]
}
Try this request

Sign In & Session Management

Sign in using email and password. Upon successful login, your JWT token and user profile photo will be saved in sessionStorage for this tab and attached to all endpoint test requests.

POST /v1/auth/login Public

Authenticate with email and password to receive a JWT Bearer Token and user account info (including balance & profile photo).

Request Body

  • email (string, required) — User's email address.
  • password (string, required) — User's password.
Sample Response (200 OK) 
{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "3ecafeed-b74c-4ac8-99a5-9ab1bfdcbb79",
    "email": "user@example.com",
    "full_name": "John Doe",
    "profile_photo": "https://ui-avatars.com/api/?name=John+Doe",
    "balance": 1000.00,
    "role": "user",
    "created_at": "2026-09-04 22:31:30"
  }
}
Try this request
JSON Body

GET /v1/auth/profile Authenticated User

Retrieve own authenticated user profile information (including full name, email, role, balance, and profile photo). Alias endpoints: /v1/profile, /v1/auth/me.

Try this request

PATCH /v1/auth/me/profile-photo Authenticated User

Update the authenticated user's profile photo URL.

Request Body

  • profile_photo (string, required) — Image URL or path for user profile photo.
Try this request
JSON Body

POST /v1/uploads Authenticated User

Upload an image file tagged with a category/folder name (e.g. tag = "profile" saves to public/uploads/profile/, tag = "invoice" saves to public/uploads/invoice/). Aliases: /v1/files/upload, /v1/upload.

Form Data (multipart/form-data)

  • file (file, required) — Image file attachment (supported: jpg, jpeg, png, webp, gif, svg). Can also use field key image or photo.
  • tag (string, optional, default: general) — Folder name tag (e.g. profile, invoice, receipt).
Sample Response (201 Created) 
{
  "message": "File uploaded successfully",
  "file": {
    "filename": "6a6b822d-78f6-4721-a286-b632cdc19411.png",
    "original_name": "my_photo.png",
    "tag": "profile",
    "folder": "profile",
    "mime_type": "image/png",
    "size_bytes": 1048576,
    "path": "/uploads/profile/6a6b822d-78f6-4721-a286-b632cdc19411.png",
    "url": "http://localhost:8889/uploads/profile/6a6b822d-78f6-4721-a286-b632cdc19411.png"
  }
}

POST /v1/admin/accounts Admin Only

Admin endpoint to create a new user account with initial balance & profile photo.

Request Body

  • email (string, required) — User email.
  • full_name (string, required) — User full name.
  • password (string, optional) — Password (default: "password123").
  • profile_photo (string, optional) — Profile photo URL.
  • amount (number, optional) — Initial balance to deposit into user account. Default: 0.00.
  • role (string, optional) — Account role ("user" or "admin"). Default: "user".
Try this request
JSON Body (Requires Admin Session)

PATCH /v1/admin/accounts/role Admin Only

Admin endpoint to change a user's role ("admin" or "user").

Request Body

  • user_id (string UUID, required) — Target user ID.
  • role (string, required) — New role ("admin" or "user").

PATCH /v1/admin/accounts/status Admin Only

Admin endpoint to activate or deactivate a user account.

Request Body

  • user_id (string UUID, required) — Target user ID.
  • is_active (boolean, required) — Active status (true to activate, false to deactivate).

GET /v1/accounts Authenticated User

Retrieves all user/member accounts in system (alias: /v1/members).

Try this request

POST /v1/transactions Authenticated User

Add an expense transaction with optional description and invoice photo. Deducts specified expense amount directly from user account balance within a database transaction.

Request Body

  • user_id (string UUID, optional) — Target user account ID (defaults to current user).
  • amount (number > 0, required) — Expense amount to deduct.
  • category (string, optional) — Category (e.g. "Food", "Bills", "Rent"). Default: "Expense".
  • description (string, optional) — Transaction description/note.
  • invoice_photo (string, optional) — URL or file path for the receipt/invoice image.
  • created_at (string, optional) — Custom timestamp formatted as YYYY-MM-DD HH:MM:SS (defaults to current server time).
Sample Response (201 Created) 
{
  "message": "Transaction added and amount deducted successfully",
  "account": {
    "id": "3ecafeed-b74c-4ac8-99a5-9ab1bfdcbb79",
    "full_name": "John Doe",
    "balance": 1000.00
  },
  "transaction": {
    "id": "9a8b7c6d-5432-10fe-dcba-0987654321fe",
    "user_id": "3ecafeed-b74c-4ac8-99a5-9ab1bfdcbb79",
    "type": "expense",
    "amount": 250.00,
    "category": "Grocery",
    "description": "Supermarket shopping for weekly organic fruits",
    "invoice_photo": "https://example.com/invoices/receipt_12345.jpg",
    "balance_after": 1000.00,
    "created_at": "2026-09-04 22:41:20"
  }
}
Try this request
JSON Body (Includes Description & Invoice Photo)

POST /v1/accounts/add-fund Authenticated User

Deposit/Add funds directly into a user account balance and log credit transaction with optional description & invoice photo.

Request Body

  • user_id (string UUID, optional) — Target user account ID (defaults to current user).
  • amount (number > 0, required) — Amount to add.
  • description (string, optional) — Description/note for deposit.
  • invoice_photo (string, optional) — Deposit receipt/invoice photo URL.
  • created_at (string, optional) — Custom timestamp formatted as YYYY-MM-DD HH:MM:SS (defaults to current server time).
Try this request
JSON Body

GET /v1/accounts/info Authenticated User

Get user account details (including profile_photo & balance) along with top 5 recent transactions with description & invoice photo.

Try this request

GET /v1/transactions/account Authenticated User

Get transactions for a specific user account in pagination, including description & invoice photo fields.

Try this request
Query Parameters

GET /v1/transactions Authenticated User

Get all transactions in pagination. (Admin sees all system transactions).

Try this request
Query Parameters

GET /v1/categories Authenticated User

Get all expense categories (default system categories + user-created custom categories).

Sample Response (200 OK) 
{
  "categories": [
    {
      "id": "food",
      "user_id": null,
      "name": "Food & Dining",
      "icon": "fork.knife",
      "color_hex": "#FF9500",
      "is_default": 1,
      "created_at": "2026-09-05 11:45:00",
      "updated_at": "2026-09-05 11:45:00"
    },
    {
      "id": "c71e89f2-...",
      "user_id": "3ecafeed-b74c-4ac8-99a5-9ab1bfdcbb79",
      "name": "Subscriptions",
      "icon": "repeat.circle.fill",
      "color_hex": "#5856D6",
      "is_default": 0,
      "created_at": "2026-09-05 11:50:00",
      "updated_at": "2026-09-05 11:50:00"
    }
  ]
}
Try this request

POST /v1/categories Authenticated User

Create a new custom expense category.

Request Body (JSON)

{
  "name": "Subscriptions",
  "icon": "repeat.circle.fill",
  "color_hex": "#5856D6"
}
Sample Response (201 Created) 
{
  "message": "Category created successfully",
  "category": {
    "id": "c71e89f2-...",
    "user_id": "3ecafeed-...",
    "name": "Subscriptions",
    "icon": "repeat.circle.fill",
    "color_hex": "#5856D6",
    "is_default": 0,
    "created_at": "2026-09-05 11:50:00",
    "updated_at": "2026-09-05 11:50:00"
  }
}
Try this request
Request Body (JSON)

PUT /v1/categories Authenticated User

Update an existing custom expense category owned by the authenticated user.

Request Body (JSON)

{
  "id": "c71e89f2-...",
  "name": "Subscriptions & Streaming",
  "icon": "tv.fill",
  "color_hex": "#AF52DE"
}
Sample Response (200 OK) 
{
  "message": "Category updated successfully",
  "category": {
    "id": "c71e89f2-...",
    "user_id": "3ecafeed-...",
    "name": "Subscriptions & Streaming",
    "icon": "tv.fill",
    "color_hex": "#AF52DE",
    "is_default": 0,
    "created_at": "2026-09-05 11:50:00",
    "updated_at": "2026-09-05 11:52:00"
  }
}
Try this request
Request Body (JSON)