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 the dashboard reads from NEXT_PUBLIC_API_BASE_URL. Request bodies are JSON, except the upload. 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. The health check needs no token:

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

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

Until the database answers and holds its tables, it answers 503 with "status":"unavailable" and "database":"down". The Docker image's health check reads it.

Errors

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

{
  "success": false,
  "data": null,
  "message": "That email and password combination didn't work. Please try again.",
  "errors": { "email": ["Enter a valid email address (example@domain.com)."] }
}

• message is a sentence in the request's language.
• errors is filled on a validation failure, with the problems per field. A body field the route does not know is refused.
• A guarded route with no token, or an expired one, answers 401; a token without the permission answers 403.

Lists and paging

List routes take page and page_count (or limit). page_count is capped at 100; a missing or invalid value falls back to the route's default, 15 for users and 10 for the others.

{ "data": [ ], "page": 1, "limit": 15, "total": 15, "totalPages": 1 }

Users come newest first by default (order=asc reverses it); projects newest-updated first; admins newest first; settings by category; roles by name.

Language

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

Signing in

1. 01

   Get a token

   Post an admin's email and password. A seeded API accepts the Super Admin from the installation guide.

   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": "eyJ…",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": { "id": 1, "email": "admin@example.com", "username": "…", "roles": [ ], "permissions": [ ] }
     },
     "message": "Signed in successfully."
   }
2. 02

   Send it on every call

   TerminalCopy

   curl http://localhost:8000/api/auth/me -H "Authorization: Bearer eyJ…"

   Expected result: /api/auth/me returns the signed-in admin with their roles and permissions.

• A token lasts JWT_EXPIRATION, 7d by default. There is no refresh route: sign in again.
• A wrong email and a wrong password get the same 401 message.
• After RATE_LIMIT_LOGIN failed sign-ins (10 by default) from one address within 15 minutes, POST /api/auth/login answers 429 until the oldest failure is 15 minutes old. The count is kept in memory, so a restart clears it.

Permissions

Every route below needs Authorization: Bearer with a token, except the ones marked Anyone. Most also need a permission, named module.action; an admin holds the permissions of all their roles. The 25 permissions are listed in Screens, roles and permissions.

• Roles and permissions

Users

The people your product serves, addressed by username. Deleting is a soft delete.

Projects

Projects carry name, description, environment, status (in-progress, ready or blocked), version, optional image and icon_name, and translations with an en and an ar name and description.

Quick tasks

The overview's to-do list. Every admin has their own and needs no permission: each route reads and writes only the caller's tasks. A task is text and completed.

Admins and your profile

The accounts that sign in to the dashboard. :id accepts an id or a username.

Roles

App settings

Key and value pairs with a display name, a description, a type and a category, such as site_name, support_email and maintenance_mode.

Countries and uploads

The upload takes one image of at most 10 MB, stores it in your R2 bucket as a JPEG of at most 1920 pixels wide, with a resized copy for its for value, and returns their addresses: original and, for example, 250x250. Without the R2 variables it answers 503 with "Image uploads are not set up on this server yet."

AI assistant and its conversations

MCP server

Live permission updates

Demo mode routes