API reference

Base URL and response format

Every route is served under the /api prefix. Locally the base URL is http://localhost:8000/api. On a server it is your API's address followed by /api, the same value both frontends read from NEXT_PUBLIC_API_BASE_URL (Environment variables).

The API serves two audiences that never share a token: customers, who use the storefront's routes, and staff, who use the admin dashboard's. Request bodies are JSON, except file uploads. Every answer comes in the same envelope:

{
  "success": true,
  "data": { },
  "message": ""
}

data holds the result. message is a short sentence some writes fill in, translated to the request's language, and empty otherwise.

The health check is the one route outside the envelope. It needs no token:

curl http://localhost:8000/api/health

{"status":"ok"}

It answers 503 with {"status":"unavailable"} while the database cannot be reached or holds no tables, so a load balancer can use it as a readiness probe.

Errors

A failed request answers with the matching HTTP status and the same envelope, with success: false, data: null, and for validation the problems per field:

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

Successful writes answer 201 for POST and 200 for the other methods.

Pagination and sorting

Lists take page, from 1, and page_count, the page size. A page holds at most 100 rows: a larger size is read as 100, a smaller one as 1, and a missing or unreadable one falls back to the list's default. A list answers in one shape:

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

• order=asc or order=desc sets the direction on products, categories, customers and orders. Categories default to ascending, the others to newest first.
• Products also sort with sort: created_at, updated_at, price, rating or best_selling. An unknown value falls back to the default, newest-updated first with ties broken by id. order_by_featured=true puts featured and best-selling products first.
• The product list filters by search (name in either language, or SKU), category_id, is_active, is_featured, is_best_seller, min_price, max_price, tag and on_sale.

Language

Send the reader's language in the Accept-Language header: en or ar as shipped. ar-SA counts as Arabic, and any language the API does not have is answered in English. There is no language query parameter.

• Error messages and the message of a successful write are translated.
• Text stored in both languages, such as product and category names, comes back as { "en": "...", "ar": "..." } and the client picks one.

Authentication

Customers and staff sign in at different endpoints, against different tables, and receive tokens only their own routes accept.

• Both are JWTs signed with JWT_SECRET. Send them as Authorization: Bearer <token>.
• A token lasts for JWT_EXPIRATION, 7d by default (Environment variables). The staff sign-in reports the same value as expires_in.
• There is no refresh endpoint. When a token expires, the next request answers 401 and the client signs in again.
• A customer token is refused on admin routes and a staff token on customer routes, although both use the same secret.
• A failed sign-in answers 401 with one message, whether the email has no account or the password is wrong.
• The sign-in, registration, password and order-tracking routes accept 10 attempts a minute from one address, counted per route. Past that they answer 429 with a Retry-After header. The count is kept in the API's memory, so it starts again on a restart and is counted separately by each instance. Behind a proxy, see TRUST_PROXY (Troubleshooting).

1. 01

   Sign in as the seeded Super Admin

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@example.com","password":"Admin@123"}'

   ResponseCopy

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@example.com",
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "..."
   }
2. 02

   Call a protected route with the token

   TerminalCopy

   curl "http://localhost:8000/api/orders?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Expected result: The five newest orders, in the list shape.
3. 03

   Sign in as a seeded customer

   The demo store also holds customers, such as john.doe@example.com with the password password123:

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/customer/login \
     -H "Content-Type: application/json" \
     -d '{"email":"john.doe@example.com","password":"password123"}'

   Then pass data.token the same way, for example to GET /api/orders/my.

Permissions

Every admin route checks the token first, then the permission it names. An admin holds every permission of every role they have; where a route names several, any one of them is enough. In the admin tables below, a permission name in the Who can call it column means an admin whose roles grant it.

The homepage sections and the AI studio use the products permissions. Reviews have no permission of their own: the dashboard reads them through the products.

Running the seed again creates what is missing and leaves existing roles' permissions as you set them.

Public catalogue

No token needed. Shoppers only ever see active products: without an admin token, an inactive or deleted product does not exist.

Customer sign-up and accounts

A server-side cart is also available to signed-in customers. The shipped storefront keeps its cart in the browser and does not call it.

Orders, checkout and tracking

With payment_method: "stripe" and Stripe configured, the answer carries a client_secret that the storefront confirms with Stripe. Shipping is free from a subtotal of 75 and 9.99 below it; tax is 0. A promo_code is stored on the order but not applied.

• Payments

Staff sign-in and accounts

Roles

Customers

Customers are addressed by their username. The list filters by search, email, phone, country_id, username, first_name, last_name, verified, from_date and to_date.

Products and categories

The section keys are style-pillars, editorial-split, new-drops, best-sellers, spotlight, lux-difference and editorial-slider.

Orders

The API accepts any status change; the dashboard only offers the next step or a cancellation.

Settings

There is no route to create a setting: the seed creates them. Nothing in the shipped code reads their values.

Media uploads

• Multipart form: the file in file, the folder in path (uploads by default), and optionally a size preset in for.
• Up to 150 MB. Videos (MP4, WebM, MOV, M4V) are stored as they are and answer { "original": url }.
• Images are re-encoded to JPEG, at most 1920 pixels wide, plus the preset's size, and answer with each URL, such as { "original": url, "250x250": url }.
• Without the five R2_* variables it answers 503: "File uploads are not set up yet."

Notifications

• Live notifications use Socket.IO on the namespace /notifications, on the API's address without /api. Send the staff token in auth.token of the handshake; customer tokens are disconnected.
• Each new one arrives as notification:created. The types are order_created, for every admin who can view orders, and studio_generation_completed and studio_generation_failed, for the admin who started the generation.
• A second namespace, /auth, sends permissions-updated when an admin's roles or permissions change.
• The socket accepts connections only from FRONTEND_URL.

AI assistant

AI studio

Fitting room

Demo mode routes