# API

La API vive en `https://zpxforge.com/api/v1`. La especificación completa (OpenAPI) está en
[`/api/v1/docs`](/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

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