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 website's routes, and staff, who use the 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, in the request's language, and empty otherwise. Money is decimal dollars in JSON, such as 14.99, and every total is computed by the API: nothing a client sends about money is trusted.

The health check needs no token:

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

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

When the database cannot be read it still answers 200, with "status":"degraded" and "database":"down". The Docker image's health check reads that field.

Errors

A failure keeps the envelope, with success: false and the HTTP status:

{
  "success": false,
  "data": null,
  "message": "errors.kitchen_closed",
  "errors": { "email": ["…"] },
  "code": "…"
}

• Errors a customer sees are keys such as errors.kitchen_closed, errors.outside_area or errors.rate_limited, which the website translates itself. Other messages are sentences in the request's language.
• errors appears on a validation failure, with the problems per field.
• code carries a machine-readable reason where one exists, such as changes with a changes list when a price moved before an order was placed.
• A guarded route with no token answers 401; a token without the permission answers 403.

Lists and paging

List routes take page and limit (page_count is accepted for limit). limit is capped at 100. Unless the caller sorts, rows come newest-updated first, with the id as a tiebreaker, so paging is stable.

{ "items": [ ], "total": 64, "page": 1, "limit": 12, "totalPages": 6 }

The dish and order lists put the rows under items. The categories, reviews, customers, team, roles and settings lists put them under data, with the same paging fields. Lists read in a sequence, such as the homepage sections and the kitchens' queue, keep that sequence.

Language

Send Accept-Language: ar for Arabic messages; anything else answers in English. Menu records carry both languages as { "en": "…", "ar": "…" } whatever the header says, and the client picks one.

Signing in

1. 01

   Sign in as staff

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@foodstudio.example","password":"FoodDemo2026!"}'

   data.access_token is the staff token, with token_type Bearer, expires_in (7d by default, JWT_EXPIRATION) and the member with their roles. GET /api/auth/me returns the signed-in member with their permissions.
2. 02

   Call a protected route

   TerminalCopy

   curl http://localhost:8000/api/orders -H "Authorization: Bearer YOUR_TOKEN"
3. 03

   Sign in as a customer

   POST /api/auth/customer/login with the same body answers { token, user }; POST /api/auth/customer/register takes first_name, last_name, email, password (8 characters or more) and optionally phone, and answers the same. The demo customer is sam@foodstudio.example with FoodDemo2026!.

• A customer token is refused on every staff route, and a staff token on every customer route.
• An unknown email and a wrong password both answer 401 with the same message.
• Ten failed sign-ins from one address within 15 minutes, per form, answer 429 until the oldest failure is 15 minutes old (RATE_LIMIT_LOGIN). Successful sign-ins are not counted.
• There is no sign-out route: a client signs out by forgetting its token.

Permissions

Staff routes check a permission, named <module>.<action>. A member holds every permission of every role they have.

The menu

A dish carries name, description and ingredients in both languages, price, its category, images, option_groups with their choices and each choice's price_delta, allergens, dietary_tags, preparation_minutes, and the switches is_active (published), is_available (orderable now), is_featured and is_best_seller.

Kitchens and the postcode check

{ "postcode": "10001", "mode": "delivery", "kitchen_code": "central" }

It answers { result, kitchen, alternatives }, where result is match, outside_area or closed. Pickup is not limited by the postcode. Whether a kitchen is open follows the service clock setting.

Pricing, promo codes and the cart

{
  "lines": [
    { "product_id": 9, "quantity": 1, "options": [{ "group": "size", "choice": "double" }], "instructions": "no onions" },
    { "offer_id": 1, "quantity": 1, "offer_choices": { "main": 9, "side": 5, "drink": 3 } }
  ],
  "kitchen_code": "central",
  "fulfillment": "delivery",
  "address": { "street": "12 Main St", "city": "Demo City", "postcode": "10001" },
  "promo_code": "TASTE10"
}

• A line names a product_id or an offer_id, with a quantity from 1 to 10 and instructions of at most 200 characters.
• The quote reports the subtotal, the discounts, the fee, the total, the points the order would earn, whether delivery can go ahead (address_incomplete, outside_area, closed, below_minimum) and a changes list for any line whose price moved or that cannot be ordered.
• A promo takes its percentage of the menu subtotal, never of the delivery fee. redeem_points: true takes one redemption off for a signed-in customer with enough points.

Placing and tracking an order

• POST /api/orders takes the quote's lines, kitchen_code, fulfillment and address, plus phone, payment_method (stripe, paypal or demo, as GET /api/payments/methods lists), terms_accepted: true, and for a guest name and email. Optional: promo_code, redeem_points, delivery_instructions, locale, accept_changes, and return_url_ok and return_url_cancel, which must be on a CORS_ORIGIN address.
• It answers 201 with { order, payment, tracking }. payment.kind is redirect, with the provider's page in payment.url, or none for the demo payment, which POST /api/payments/checkout-session then pays. tracking is a signed token, valid for three hours, for GET /api/orders/track/status.
• The same Idempotency-Key from the same person returns the stored order instead of a second one.
• A price that moved, or a dish that became unavailable, answers 422 with code: "changes" until the client sends the change's key in accept_changes.
• Guest tracking answers the same 404 for an unknown number, a wrong email and missing parameters.

An order's status moves pending, confirmed, preparing, ready, then out_for_delivery and delivered for delivery, or straight to delivered for pickup. It can be cancelled with a reason before it leaves the kitchen, and becomes refunded only when the payment provider reports a refund.

Payments

• Set up payments

Addresses, saved dishes, rewards, reviews and contact

Staff: menu, categories, combos and homepage

Staff: orders and the overview

• A move the status line does not allow answers 409 errors.transition_not_allowed; one this account may not make, 403 errors.transition_forbidden; confirming an unpaid order, 409 errors.payment_required.
• A kitchen account sees only its own kitchen's orders, with no prices, and any other order answers 404.

Staff: customers, team and roles

Staff: settings, kitchens, promo codes, uploads and notifications

• The settings the restaurant runs on are delivery_fee, pickup_fee, delivery_minimum, rewards_points_per_dollar, rewards_redeem_points, rewards_redeem_value and service_clock (real or demo-fixed), beside site_name, site_tagline, support_email and support_phone.
• An uploaded image is stored as JPEG in several sizes and the answer maps each version to its address. Files go to the bucket when the R2_* variables are set, and to /media/uploads/… on the API otherwise.
• Every notifications route answers the whole feed, so a client replaces what it holds with the answer.

Limits per address

A request over a limit answers 429 with errors.rate_limited. The counts live in the API's memory, so a restart clears them. Behind a reverse proxy, set TRUST_PROXY so each visitor is counted on their own address.

AI assistant and its conversations

AI studio

MCP server

Live updates over WebSocket

Demo mode routes