Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IvanchoDev89/maleku-system/llms.txt

Use this file to discover all available pages before exploring further.

The Superadmin API provides unrestricted, platform-wide access to all entities and operational data on Maleku System. Every endpoint in this section is protected by the require_superadmin dependency — the token’s role must be exactly super_admin. These endpoints exist outside the normal vendor/client scope and are intended exclusively for internal platform operations.
All superadmin endpoints return 403 Forbidden if called with a token that does not have the super_admin role — including admin role tokens. There is no role escalation path.
All mutating operations (create, update, delete) on core platform models are automatically logged to the audit trail via AuditService. Every state change records the actor’s user ID, the old and new values, a plain-text changes summary, the originating IP address, and a UTC timestamp. These logs are immutable and cannot be deleted via the API.

​
Users

​
GET /api/v1/superadmin/users

List all users with comprehensive filtering, sorting, and pagination. Returns a flat array of UserListItem objects, each augmented with vendor_count and booking_count computed via correlated subqueries.
​
search
string
Search by email address or full name (ILIKE).
​
role
string
Filter by role: client, vendor, admin, super_admin.
​
is_active
boolean
Filter by active status.
​
is_verified
boolean
Filter by email verification status.
​
sort_by
string
default:"created_at"
Sort field (any column on the users table).
​
sort_order
string
default:"desc"
Sort direction: asc or desc.
​
limit
integer
default:"20"
Items per page. Range: 1–100.
​
offset
integer
default:"0"
Records to skip.
Response — UserListItem[] 
[
  {
    "id": "f9e8d7c6-...",
    "email": "traveller@example.com",
    "full_name": "Ana González",
    "role": "client",
    "is_active": true,
    "is_verified": true,
    "phone": "+50688990011",
    "avatar_url": null,
    "last_login": "2025-01-20T14:30:00Z",
    "created_at": "2024-03-01T10:00:00Z",
    "vendor_count": 0,
    "booking_count": 7
  }
]

​
GET /api/v1/superadmin/users/count

Get the total count of users matching the same filter parameters as the list endpoint. Returns { "count": 1840 }.

​
GET /api/v1/superadmin/users/

Get detailed information about a specific user, including failed_login_attempts and locked_until fields not exposed in the public user response. Response — UserDetail 
{
  "id": "f9e8d7c6-...",
  "email": "traveller@example.com",
  "full_name": "Ana González",
  "phone": "+50688990011",
  "avatar_url": null,
  "role": "client",
  "is_active": true,
  "is_verified": true,
  "last_login": "2025-01-20T14:30:00Z",
  "failed_login_attempts": 0,
  "locked_until": null,
  "created_at": "2024-03-01T10:00:00Z",
  "updated_at": "2025-01-20T14:30:00Z"
}

​
POST /api/v1/superadmin/users

Create a new user directly. Pre-verified (skips email verification flow). Rate-limited to 10 requests per minute.

​
PUT /api/v1/superadmin/users/

Update any user’s role, status, email, or verification flag. All changes are captured in the audit log with old and new values. Rate-limited to 10 requests per minute.

​
DELETE /api/v1/superadmin/users/

Permanently delete a user record. Cannot delete your own account or other super_admin accounts. This action is logged before the database deletion.

​
GET /api/v1/superadmin/users//activity

Get the audit activity history for a specific user (actions they performed). Returns up to 100 entries per page.

​
POST /api/v1/superadmin/users//block

Suspend a user account with a reason and optional duration. Sets is_active = false and optionally sets locked_until. Generates both an audit log entry and a security log entry with critical severity.

​
POST /api/v1/superadmin/users//unblock

Reactivate a blocked account. Clears locked_until and resets failed_login_attempts to 0.

​
POST /api/v1/superadmin/users//impersonate

Generate a short-lived (1 hour) impersonation access token for debugging user-reported issues. Cannot impersonate super_admin or inactive accounts. Every impersonation attempt is audited.

​
Vendors

​
GET /api/v1/superadmin/vendors

List all vendors including pending, suspended, and rejected accounts (unlike the public /vendors/ endpoint which only returns active vendors). Supports comprehensive filtering and sorting.
​
status
string
default:"all"
Filter by vendor status: all, pending, active, suspended, rejected.
​
sort_by
string
default:"created_at"
Sort field: created_at, name, rating, bookings.
​
sort_order
string
default:"desc"
asc or desc.
​
search
string
Search by business name or owner email.
​
featured_only
boolean
default:"false"
Return only featured vendors.
​
limit
integer
default:"50"
Range: 1–200.
​
offset
integer
default:"0"
Records to skip.

​
GET /api/v1/superadmin/vendors/pending

List vendors with status = pending ordered oldest-first (priority queue). Returns full VendorDetailResponse including compliance flags, owner info, and booking/review stats calculated via batch queries.

​
GET /api/v1/superadmin/vendors/

Get full vendor detail including compliance flags from VendorService.run_compliance_check(), owner contact information, and aggregated statistics (total bookings, revenue, completed/cancelled breakdown, average rating).

​
POST /api/v1/superadmin/vendors//approval

Process a vendor lifecycle action. Rate-limited to 10 requests per minute. All actions are audited. Valid state transitions:
ActionFrom statusTo status
approvependingactive
rejectpendingrejected
suspendactivesuspended
reactivatesuspendedactive
Request body 
{
  "action": "approve",
  "reason": "All documents verified and business registration confirmed.",
  "notes": "Premium tier vendor — assign featured status."
}

​
POST /api/v1/superadmin/vendors//feature

Toggle a vendor’s featured status. Only active vendors can be featured. Audited.

​
GET /api/v1/superadmin/vendors/analytics/overview

Platform-wide vendor analytics including status counts, top performers by revenue, recent registrations, bookings by month (last 12 months), and revenue broken down by business_type.
​
days
integer
default:"30"
Look-back period for trend data. Range: 1–365.

​
POST /api/v1/superadmin/vendors//compliance-check

Run an on-demand compliance check on a vendor. Updates last_compliance_check timestamp and returns any flags raised. Rate-limited to 10 requests per minute.

​
Bookings

​
GET /api/v1/superadmin/bookings

List all bookings platform-wide with filtering and pagination. Results ordered by created_at descending.
​
status
string
Filter by booking status: pending, confirmed, completed, cancelled.
​
booking_type
string
Filter by booking type (e.g. property, tour, vehicle).
​
search
string
Search by guest_name or guest_email (ILIKE).
​
page
integer
default:"1"
Page number.
​
page_size
integer
default:"20"
Items per page. Range: 1–100.
Response — BookingListResponse 
{
  "items": [
    {
      "id": "b1c2d3e4-...",
      "user_id": "f9e8d7c6-...",
      "vendor_id": "a1b2c3d4-...",
      "property_id": "p1q2r3s4-...",
      "tour_id": null,
      "booking_type": "property",
      "status": "confirmed",
      "guest_name": "Marco Fernández",
      "guest_email": "marco@example.com",
      "total_amount": 750.00,
      "currency": "USD",
      "created_at": "2025-01-18T09:15:00Z",
      "check_in": "2025-02-10T15:00:00Z",
      "check_out": "2025-02-13T11:00:00Z"
    }
  ],
  "total": 4821,
  "page": 1,
  "page_size": 20,
  "total_pages": 242
}

​
GET /api/v1/superadmin/bookings/

Get full booking detail including guest_phone, guest_notes, subtotal, commission_amount, confirmation_code, cancellation_reason, and timestamps for confirmed_at and cancelled_at.

​
PUT /api/v1/superadmin/bookings//status

Override a booking’s status. Rate-limited to 10 requests per minute. 
{ "status": "completed" }

​
DELETE /api/v1/superadmin/bookings/

Permanently delete a booking record. Rate-limited to 10 requests per minute.

​
Audit Logs

​
POST /api/v1/superadmin/audit/logs

Record a client-side security event reported by the frontend (e.g. a middleware access denial). The event_type string is mapped to a known AuditAction enum value before storage — free-form text is captured in changes_summary only. Events containing denied or deny also create a SecurityLog entry with warning severity; events with blocked or suspicious create one with critical severity. Rate-limited to 30 requests per minute. Requires any authenticated user. Request body 
{
  "event_type": "superadmin_access_denied",
  "path": "/admin/dashboard",
  "metadata": { "attempted_role": "vendor" },
  "severity": "warning"
}
Response 
{ "status": "recorded", "event_type": "superadmin_access_denied" }

​
GET /api/v1/superadmin/audit/logs

Query the audit trail with comprehensive filtering. Returns entries in reverse chronological order.
​
user_id
UUID
Filter by the user who performed the action.
​
action
string
Filter by action type: create, update, delete, view, approve, reject, suspend, activate, impersonate, export, etc.
​
entity_type
string
Filter by entity type (e.g. user, vendor, booking, destination).
​
entity_id
UUID
Filter to a specific entity.
​
date_from
datetime
ISO 8601 start date for the query window.
​
date_to
datetime
ISO 8601 end date.
​
search
string
Search within changes_summary and entity_name (ILIKE).
​
limit
integer
default:"50"
Range: 1–500.
​
offset
integer
default:"0"
Records to skip.
Example audit log entry 
{
  "id": "00a1b2c3-...",
  "user_id": "99z8y7x6-...",
  "user_email": "superadmin@maleku.dev",
  "action": "update",
  "entity_type": "vendor",
  "entity_id": "a1b2c3d4-...",
  "entity_name": "Tropical Adventures CR",
  "old_values": {
    "status": "pending",
    "is_featured": false
  },
  "new_values": {
    "status": "active",
    "reason": "All documents verified.",
    "notes": null
  },
  "changes_summary": "approved vendor: All documents verified.",
  "ip_address": "203.0.113.45",
  "user_agent": "Mozilla/5.0 (Macintosh; ...) Safari/537.36",
  "request_path": "/api/v1/superadmin/vendors/a1b2c3d4-.../approval",
  "created_at": "2025-01-22T11:04:33Z"
}

​
GET /api/v1/superadmin/audit/logs/count

Get the total count of audit log entries matching the same filters as the list endpoint.

​
GET /api/v1/superadmin/audit/logs/

Get detailed information about a single audit log entry.

​
Security Logs

​
GET /api/v1/superadmin/audit/security

Query security events such as login failures, access denials, and account lockouts.
​
user_id
UUID
Filter by user.
​
action
string
Security action type (e.g. login_failure, access_denied, account_locked, suspicious_activity).
​
severity
string
Filter by severity: info, warning, or critical.
​
ip_address
string
Filter by originating IP address.
​
date_from / date_to
datetime
Date range filter.

​
GET /api/v1/superadmin/audit/security/failed-logins

Get failed login attempts for brute-force detection. When group_by_ip=true, groups results by IP address and only returns IPs with 3 or more failures.
​
hours
integer
default:"24"
Look-back period. Range: 1–168 (1 week).
​
group_by_ip
boolean
default:"false"
Group results by IP address to identify coordinated attacks.

​
GET /api/v1/superadmin/audit/summary

Get aggregate statistics for the audit and security log dashboards. 
{
  "total_audit_logs": 48210,
  "total_security_logs": 3840,
  "today_audit_logs": 142,
  "today_security_logs": 18,
  "failed_logins_24h": 7,
  "critical_events_24h": 0
}

​
POST /api/v1/superadmin/audit/export

Export audit or security logs as JSON or CSV. Streams up to 5,000 records per request. The export action itself is logged. Rate-limited to 5 requests per minute. 
{
  "format": "csv",
  "log_type": "audit",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-01-31T23:59:59Z"
}

​
Content

Blog posts are managed via the standard blog endpoints, which require an admin or super_admin role for write operations:
MethodPathDescription
GET/api/v1/blog/List published blog posts (public)
POST/api/v1/blog/Create a blog post (Admin)
GET/api/v1/blog/{id}Get post by ID
GET/api/v1/blog/slug/{slug}Get post by slug
PUT/api/v1/blog/{id}Update post (Admin)
DELETE/api/v1/blog/{id}Delete post (Admin)
Destination content is managed via POST/PUT/DELETE /api/v1/destinations/ — see the Destinations API for full reference.

​
Analytics

The Analytics API provides platform-wide metrics for Admin and Super Admin dashboards. Requires admin or super_admin role.

​
GET /api/v1/analytics/overview

Single-query aggregate stats across users, vendors, and bookings. Response — OverviewStats 
{
  "total_users": 4820,
  "total_vendors": 48,
  "total_bookings": 12450,
  "total_revenue": 1845230.00,
  "net_revenue": 1660707.00,
  "pending_bookings": 38,
  "completed_bookings": 11920,
  "cancelled_bookings": 492
}

​
GET /api/v1/analytics/revenue

Daily revenue time series for the specified look-back period.
​
period
string
default:"30"
Number of days to look back (e.g. 7, 30, 90).
Returns an array of RevenueData objects: { date, gross_revenue, net_revenue, bookings_count }.

​
GET /api/v1/analytics/bookings/by-status

Booking counts and revenue grouped by status (pending, confirmed, completed, cancelled).

​
GET /api/v1/analytics/top-vendors

Top vendors ranked by total revenue from completed bookings.
​
limit
integer
default:"10"
Number of vendors to return. Range: 1–50.
Returns TopVendorData[]: { vendor_id, vendor_name, total_bookings, total_revenue }.

​
GET /api/v1/analytics/users/stats

User growth stats: total users, new today/this week/this month, and a breakdown by role. 
{
  "total": 4820,
  "new_today": 12,
  "new_this_week": 84,
  "new_this_month": 320,
  "by_role": {
    "client": 4680,
    "vendor": 48,
    "admin": 4,
    "super_admin": 2
  }
}

​
GET /api/v1/analytics/bookings/trends

Daily booking counts for the specified period.
​
period
string
default:"30"
Number of days to look back.

​
GET /api/v1/analytics/traffic

Placeholder endpoint for future pageview and unique visitor tracking. Currently returns zero-valued data — real analytics tracking is planned.

Build docs developers (and LLMs) love

Get started for freeTalk to us