API Reference

RESTful API documentation for developers

Overview

The RetailMind AI API is a RESTful JSON API. All endpoints are prefixed with /api/v1/.

Base URL: https://retailmind.amuzaraai.com/api/v1/

Response Format

All responses are in JSON format. List endpoints return paginated results with 20 items per page by default.

{
  "count": 50,
  "next": "https://...?page=2",
  "previous": null,
  "results": [...]
}

Rate Limiting

  • Anonymous: 100 requests/hour
  • Authenticated: 1,000 requests/hour

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header.

Authorization: Bearer <access_token>
POST /api/v1/auth/login/

Authenticate and receive JWT tokens.

Request Body:

{
  "email": "[email protected]",
  "password": "your_password"
}

Response:

{
  "access": "eyJ0eXAi...",
  "refresh": "eyJ0eXAi...",
  "user": { "id": "...", "email": "...", "role": "..." },
  "must_change_password": false
}
POST /api/v1/auth/register/

Register a new business owner account. Creates an organization automatically.

Request Body:

{
  "organization_name": "My Business",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone_number": "+233201234567",
  "password": "securepassword"
}
POST /api/v1/auth/forgot-password/
Request a password reset email. Sends a reset link valid for 1 hour. Body: {"email": "..."}
POST /api/v1/auth/reset-password/
Reset password using the token from the email link. Body: {"token": "...", "new_password": "...", "new_password_confirm": "..."}
POST /api/v1/token/refresh/

Refresh an expired access token using a valid refresh token.

Users

GET /api/v1/users/
List all users in your organization. Requires authentication.
GET /api/v1/users/me/
Get the current authenticated user's profile.
POST /api/v1/users/create-staff/
Create a staff account with a temporary password. Management only.

Shops

GET /api/v1/shops/
List all shops in your organization.
POST /api/v1/shops/
Create a new shop. Organization is set automatically.
GET /api/v1/shops/{id}/
Get details of a specific shop.
PUT /api/v1/shops/{id}/
Update a shop's details.

Products

GET /api/v1/products/
List all products. Supports search, filtering by category, and ordering.
POST /api/v1/products/
Create a new product. SKU is auto-generated.
GET /api/v1/products/categories/
List product categories.
GET /api/v1/products/suppliers/
List suppliers.

Inventory

GET /api/v1/inventory/
List inventory records across shops.
GET /api/v1/inventory/low-stock/
Get items below minimum stock threshold.
POST /api/v1/inventory/adjustments/
Create a stock adjustment (stock-in, stock-out, or correction).

Transactions

GET /api/v1/transactions/
List all transactions. Filter by shop, date range, payment method.
POST /api/v1/transactions/
Create a new transaction (sale). Automatically updates inventory.
GET /api/v1/transactions/{id}/receipt/
Get receipt data for a specific transaction.

Staff

GET /api/v1/staff/
List staff assignments for your organization.
POST /api/v1/staff/
Assign a user to a shop with a specific role.

Fraud Detection

GET /api/v1/fraud/alerts/
List fraud alerts for your organization.
GET /api/v1/fraud/risk-profiles/
Get risk profiles for staff members.
GET /api/v1/fraud/alerts/dashboard/
Get fraud dashboard summary with alert counts and trends.

Analytics

GET /api/v1/analytics/dashboard/overview/
Get dashboard overview with revenue, transactions, and key metrics.
GET /api/v1/analytics/dashboard/revenue-chart/
Get revenue chart data for a specified period.
GET /api/v1/analytics/dashboard/shop-comparison/
Compare performance across shops.

Payments (Paystack)

POST /api/v1/payments/paystack/initialize/
Initialize a Paystack payment. Returns an authorization URL.
GET /api/v1/payments/paystack/verify/{reference}/
Verify a Paystack payment by reference.