Référence de l'API

URL de base et format des réponses

Chaque route est servie sous le préfixe /api. En local, l'URL de base est http://localhost:8000/api ; sur un serveur, c'est l'adresse de votre API suivie de /api, la même valeur que le tableau de bord lit dans NEXT_PUBLIC_API_BASE_URL. Les corps de requête sont en JSON, sauf pour l'envoi de fichier. Chaque réponse arrive dans la même enveloppe :

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

data contient le résultat. message est une courte phrase que certaines écritures remplissent, dans la langue de la requête, et vide sinon. Le contrôle de santé n'exige aucun jeton :

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

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

Tant que la base ne répond pas et ne contient pas ses tables, il répond 503 avec "status":"unavailable" et "database":"down". Le contrôle de santé de l'image Docker le lit.

Erreurs

Un échec garde l'enveloppe, avec success: false et le statut HTTP :

{
  "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 est une phrase dans la langue de la requête.
• errors est rempli en cas d'échec de validation, avec les problèmes par champ. Un champ de corps que la route ne connaît pas est refusé.
• Une route protégée sans jeton, ou avec un jeton expiré, répond 401 ; un jeton sans la permission répond 403.

Listes et pagination

Les routes de liste acceptent page et page_count (ou limit). page_count est plafonné à 100 ; une valeur absente ou invalide revient à la valeur par défaut de la route, 15 pour les utilisateurs et 10 pour les autres.

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

Les utilisateurs arrivent du plus récent au plus ancien par défaut (order=asc l'inverse) ; les projets du plus récemment modifié au plus ancien ; les admins du plus récent au plus ancien ; les paramètres par catégorie ; les rôles par nom.

Langue

Envoyez Accept-Language: ar pour des messages en arabe ; toute autre valeur répond en anglais. Les pays, permissions, paramètres et noms de projets portent les deux langues sous la forme { "en": "…", "ar": "…" } quel que soit l'en-tête, et le client en choisit une.

Connexion

1. 01

   Obtenir un jeton

   Envoyez l'e-mail et le mot de passe d'un admin. Une API remplie par le seed accepte le Super Admin du guide d'installation.

   TerminalCopier

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

   RéponseCopier

   {
     "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

   L'envoyer à chaque appel

   TerminalCopier

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

   Résultat attendu: /api/auth/me renvoie l'admin connecté avec ses rôles et ses permissions.

• Un jeton dure JWT_EXPIRATION, 7d par défaut. Il n'y a pas de route de rafraîchissement : reconnectez-vous.
• Un mauvais e-mail et un mauvais mot de passe reçoivent le même message 401.
• Après RATE_LIMIT_LOGIN connexions échouées (10 par défaut) depuis une même adresse en 15 minutes, POST /api/auth/login répond 429 jusqu'à ce que le plus ancien échec ait 15 minutes. Le compteur est gardé en mémoire, donc un redémarrage le remet à zéro.

Permissions

Chaque route ci-dessous demande Authorization: Bearer avec un jeton, sauf celles marquées Anyone. La plupart demandent aussi une permission, nommée module.action ; un admin détient les permissions de tous ses rôles. Les 25 permissions sont listées dans Écrans, rôles et permissions.

• Rôles et permissions

Utilisateurs

Les personnes que sert votre produit, adressées par username. La suppression est une suppression douce.

Projets

Les projets portent name, description, environment, status (in-progress, ready ou blocked), version, en option image et icon_name, et translations avec un nom et une description en et ar.

Tâches rapides

La liste de tâches de la vue d'ensemble. Chaque admin a la sienne et n'a besoin d'aucune permission : chaque route ne lit et n'écrit que les tâches de l'appelant. Une tâche est text et completed.

Admins et votre profil

Les comptes qui se connectent au tableau de bord. :id accepte un identifiant ou un nom d'utilisateur.

Rôles

Réglages de l'application

Des paires clé et valeur avec un nom d'affichage, une description, un type et une catégorie, comme site_name, support_email et maintenance_mode.

Pays et envois de fichiers

L'envoi prend une image d'au plus 10 Mo, la stocke dans votre bucket R2 en JPEG d'au plus 1920 pixels de large, avec une copie redimensionnée pour sa valeur for, et renvoie leurs adresses : original et, par exemple, 250x250. Sans les variables R2, il répond 503 avec « Image uploads are not set up on this server yet. »

L'assistant IA et ses conversations

Serveur MCP

Mises à jour des permissions en direct

Routes du mode démo