Referencia de la API

URL base y formato de respuesta

Todas las rutas se sirven bajo el prefijo /api. En local la URL base es http://localhost:8000/api; en un servidor es la dirección de tu API seguida de /api, el mismo valor que el panel lee de NEXT_PUBLIC_API_BASE_URL. Los cuerpos de las peticiones son JSON, salvo la subida. Cada respuesta llega en el mismo sobre:

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

data contiene el resultado. message es una frase corta que rellenan algunas escrituras, en el idioma de la petición, y está vacío en los demás casos. La comprobación de estado no necesita token:

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

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

Hasta que la base de datos responde y contiene sus tablas, responde 503 con "status":"unavailable" y "database":"down". La comprobación de salud de la imagen de Docker lo lee.

Errores

Un fallo mantiene el envoltorio, con success: false y el estado 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 es una frase en el idioma de la petición.
• errors se rellena cuando falla la validación, con los problemas por campo. Un campo del cuerpo que la ruta no conoce se rechaza.
• Una ruta protegida sin token, o con uno caducado, responde 401; un token sin el permiso responde 403.

Listas y paginación

Las rutas de lista aceptan page y page_count (o limit). page_count tiene un máximo de 100; un valor ausente o no válido vuelve al valor por defecto de la ruta, 15 para usuarios y 10 para las demás.

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

Los usuarios salen primero los más recientes por defecto (order=asc lo invierte); los proyectos, primero los actualizados más recientemente; los administradores, primero los más recientes; los ajustes, por categoría; los roles, por nombre.

Idioma

Envía Accept-Language: ar para mensajes en árabe; cualquier otro valor responde en inglés. Los países, permisos, ajustes y nombres de proyecto llevan los dos idiomas como { "en": "…", "ar": "…" } sea cual sea la cabecera, y el cliente elige uno.

Inicio de sesión

1. 01

   Obtén un token

   Envía el correo y la contraseña de un administrador. Una API con seed acepta al Super Admin de la guía de instalación.

   TerminalCopiar

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

   RespuestaCopiar

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

   Envíalo en cada llamada

   TerminalCopiar

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

   Resultado esperado: /api/auth/me devuelve al administrador con sesión iniciada con sus roles y permisos.

• Un token dura JWT_EXPIRATION, 7d por defecto. No hay ruta de renovación: inicia sesión de nuevo.
• Un correo incorrecto y una contraseña incorrecta reciben el mismo mensaje 401.
• Después de RATE_LIMIT_LOGIN inicios de sesión fallidos (10 por defecto) desde una dirección en 15 minutos, POST /api/auth/login responde 429 hasta que el fallo más antiguo tenga 15 minutos. El recuento se guarda en memoria, así que un reinicio lo borra.

Permisos

Todas las rutas de abajo necesitan Authorization: Bearer con un token, salvo las marcadas como Cualquiera. La mayoría también necesita un permiso, con nombre module.action; un administrador tiene los permisos de todos sus roles. Los 25 permisos se listan en Pantallas, roles y permisos.

• Roles y permisos

Usuarios

Las personas a las que sirve tu producto, identificadas por username. Eliminar es un borrado lógico.

Proyectos

Los proyectos llevan name, description, environment, status (in-progress, ready o blocked), version, image e icon_name opcionales, y translations con un nombre y una descripción en en y en ar.

Tareas rápidas

La lista de tareas del resumen. Cada administrador tiene la suya y no necesita ningún permiso: cada ruta lee y escribe solo las tareas de quien llama. Una tarea es text y completed.

Administradores y tu perfil

Las cuentas que inician sesión en el panel. :id acepta un id o un nombre de usuario.

Roles

Ajustes de la aplicación

Pares de clave y valor con un nombre para mostrar, una descripción, un tipo y una categoría, como site_name, support_email y maintenance_mode.

Países y subidas

La subida acepta una imagen de 10 MB como máximo, la guarda en tu bucket R2 como JPEG de 1920 píxeles de ancho como máximo, con una copia redimensionada según su valor de for, y devuelve sus direcciones: original y, por ejemplo, 250x250. Sin las variables de R2 responde 503 con "Image uploads are not set up on this server yet."

El asistente de IA y sus conversaciones

Servidor MCP

Actualizaciones de permisos en vivo

Rutas del modo demostración