Para agentes.md
API
La API vive en https://zpxforge.com/api/v1. La especificación completa (OpenAPI) está en
/api/v1/docs.
Autenticación
Hoy la API usa la sesión del navegador (cookie httpOnly). Las peticiones que cambian datos deben
venir del propio sitio (cabecera Origin).
El CLI usa un token personal autorizado en el navegador para las rutas habilitadas. Las decisiones del cliente se realizan en su sesión web verificada.
Endpoints
| Método y ruta | Qué hace |
|---|---|
GET /v1/health | Salud de la plataforma (base de datos, Redis, worker) |
GET /v1/me | La persona, sus empresas e invitaciones pendientes |
GET /v1/roles | Roles disponibles |
POST /v1/orgs | Registra una empresa |
GET /v1/orgs/{empresa} | Empresa, tu rol y tus permisos |
GET /v1/orgs/{empresa}/members | Miembros |
PATCH /v1/orgs/{empresa}/members/{id} | Cambia el rol de un miembro |
POST /v1/orgs/{empresa}/invitations | Invita por correo |
GET /v1/orgs/{empresa}/projects | Proyectos |
POST /v1/orgs/{empresa}/projects | Crea un proyecto |
PUT /v1/orgs/{empresa}/projects/{p}/roles/{id} | Rol de una persona en un proyecto |
GET /v1/orgs/{empresa}/github | Instalaciones y repos de GitHub |
POST /v1/orgs/{empresa}/projects/{p}/repos | Conecta un repo al proyecto |
POST /v1/orgs/{empresa}/projects/{p}/repos/{id}/protect | Protege develop y main |
GET /v1/orgs/{empresa}/audit | Auditoría (solo admins) |
Errores
{ "detail": "Tu rol no permite esta acción", "code": "forbidden" }
| Código HTTP | Significado |
|---|---|
401 | Falta iniciar sesión |
403 | Sin permiso, empresa inactiva u origen no permitido |
404 | No existe o no perteneces a esa empresa |
409 | Conflicto (por ejemplo, el último admin) |
429 | Demasiados intentos |