Admin Users & Analytics API

Endpoints for managing the dashboard, staff roles, users, and overall analytics.

Base: /api/v1/admin | X-Tenant-ID required | Requires auth & admin role 🔒

Dashboard & Analytics

GET /api/v1/admin/stats 🔒 Auth Required

Get high-level overview stats for the dashboard (Revenue, Orders, Products, Customers).

Response

{ "success": true, "data": { "revenue": { "value": 120000, "trend": 15 }, "orders": { "value": 150, "trend": 5 }, "products": { "value": 45, "trend": 0 }, "customers": { "value": 300, "trend": 10 } } }

GET /api/v1/admin/revenue-chart 🔒 Auth Required

Get revenue chart data over a period.

Query Parameters

Param	Type	Required	Description
`period`	string	No	daily \| weekly \| monthly
`days`	number	No	Days to look back

Response

{ "success": true, "data": { "chart": [ { "date": "2024-01-01", "revenue": 5000, "orders": 12 } ] } }

GET /api/v1/admin/top-products 🔒 Auth Required

List top selling products.

Response

{ "success": true, "data": { "products": [ { "id", "name", "revenue", "sales" } ] } }

GET /api/v1/admin/recent-orders 🔒 Auth Required

List recently placed orders.

Response

{ "success": true, "data": [ { "id": "uuid", "order_number": "ORD-...", "total": 120.50, "status": "pending", "created_at": "...", "customer_name": "John Doe" } ] }

GET /api/v1/admin/top-categories 🔒 Auth Required

List top categories by revenue.

Response

{ "success": true, "data": [ { "id": "uuid", "name": "Electronics", "slug": "electronics", "revenue": 15000.00, "orders_count": 45 } ] }

GET /api/v1/admin/activity-logs 🔒 Auth Required

List paginated administrative activity logs.

Query Parameters

Param	Type	Required	Description
`page`	number	No	Page number
`limit`	number	No	Items per page

Response

{ "success": true, "data": [ { "id": "uuid", "action": "UPDATE_ORDER", "admin_name": "Jane", "created_at": "..." } ], "pagination": { "total": 100, "page": 1, "limit": 20, "totalPages": 5 } }

GET /api/v1/admin/server-logs 🔒 Auth Required

Read tail lines from backend server logs (stderr.log or stdout.log).

Query Parameters

Param	Type	Required	Description
`lines`	number	No	Number of lines to read (default 100)
`type`	string	No	"error" or "out"

Response

{ "success": true, "data": { "file": "stderr.log", "content": "..." } }

Users & Staff Management

GET /api/v1/admin/users 🔒 Auth Required

List all users across all roles (customers, admins, superadmins).

Query Parameters

Param	Type	Required	Description
`search`	string	No	Search by name or email
`role`	string	No	Filter by role (customer, admin, superadmin)
`page`	number	No	Page number
`limit`	number	No	Items per page

Response

{ "success": true, "data": { "data": [ { "id", "name", "email", "role": "customer", "is_active": true, "created_at": "..." } ], "pagination": { "total": 10, "page": 1, "limit": 20, "totalPages": 1 } } }

PATCH /api/v1/admin/users/:id/status 🔒 Auth Required

Toggle a user's active status (suspend/activate).

Response

{ "success": true, "message": "User status updated" }

GET /api/v1/admin/staff 🔒 Auth Required

List all admin and superadmin staff.

Response

{ "success": true, "data": { "staff": [ { "id", "name", "role": { "name": "admin" } } ] } }

POST /api/v1/admin/staff/:userId/assign 🔒 Auth Required

Assign an admin role to a user.

Request Body

{ "role_name": "admin" }

Response

{ "success": true, "message": "Role assigned successfully." }