# API REST (/docs/referencia/api)

La web y el CLI hablan con el servidor por esta API. Tú también puedes. Todo es JSON, y cada ruta tiene su página
en esta sección, agrupada por área. La especificación completa, en OpenAPI 3.1, se descarga en
[`/openapi.yaml`](/openapi.yaml).

## La URL base [#la-url-base]

El servidor escucha en `PORT` (8080 por defecto). En local, con `make dev`, la base es `http://127.0.0.1:8080` y
todas las rutas cuelgan de `/api`, salvo `/healthz`. Las de tu trabajo van bajo `/api/w/{ws}`, donde `{ws}` es el
slug del workspace.

```bash
curl -s http://127.0.0.1:8080/api/config
```

`GET /api/config` es pública. Devuelve la versión, el idioma por defecto, si el registro está abierto
(`allow_signup`), si hay correo configurado (`email_configured`) y si vale el código de desarrollo desde donde
llamas (`dev_code_hint`).

## Autenticación [#autenticación]

Mandas la credencial en la cabecera `Authorization: Bearer <token>`. Hay cuatro, y cada una abre rutas distintas.

| Credencial | Prefijo | Sirve para |
|---|---|---|
| Sesión del navegador | (un JWT) | Todas las rutas de usuario. Algunas sólo la aceptan a ella: aprobar, resolver preocupaciones, cambiar roles o políticas, crear tokens |
| Token personal de API | `hqf_` | Con alcance `api`, las rutas de usuario que no exigen la sesión. Con alcance `runtime`, sólo `GET /api/me`, `GET /api/workspaces` y registrar un runtime |
| Token del runtime | `hqfrt_` | Las rutas `/api/daemon/*`, que usa el daemon `hqf` |
| Token de la tarea | `hqftk_` | Nueve rutas de su propia tarea, las que usa el agente con `hqf agent …` |

Ningún token de API puede aprobar. Esa decisión siempre pasa por una persona con la sesión del navegador abierta.

### Una sesión con el código por correo [#una-sesión-con-el-código-por-correo]

Pides un código para tu correo y lo canjeas por un JWT de 7 días.

```bash
curl -s -X POST http://127.0.0.1:8080/api/auth/request-code \
  -H 'Content-Type: application/json' \
  -d '{"email":"tu@ejemplo.com"}'

curl -s -X POST http://127.0.0.1:8080/api/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"tu@ejemplo.com","code":"123456"}'
```

La segunda respuesta trae `token`. Sin correo configurado (`RESEND_API_KEY` vacía), el código aparece en el log del
servidor. En producción eso sólo vale para el administrador de la instancia o la primera cuenta: al resto no se le
crea código. La respuesta de pedir un código es la misma para cualquier correo.
Con el token ya puedes leer:

```bash
curl -s http://127.0.0.1:8080/api/workspaces -H "Authorization: Bearer $TOKEN"
```

Para un script que no deba aprobar nada, crea un token personal en **Ajustes → Tokens** de la web, o con
`POST /api/tokens` desde la sesión del navegador.

## Errores [#errores]

Un error trae siempre la misma forma:

```json
{ "error": "workspace_not_found", "message": "Workspace no encontrado" }
```

`error` es un código estable para programar contra él. `message` es para personas. Los más comunes:

| Estado | Código | Qué significa |
|---|---|---|
| 400 | `bad_json`, `invalid` | El cuerpo no es JSON válido, o un dato no pasa la validación |
| 401 | `unauthorized` | Falta la credencial o ya no vale |
| 403 | `forbidden` | Tu rol en el workspace no alcanza |
| 403 | `session_required` | La ruta sólo acepta la sesión del navegador |
| 403 | `token_scope` | El alcance de tu token no llega a esta ruta |
| 403 | `instance_admin_required` | Sólo el administrador de la instancia |
| 404 | `not_found`, `workspace_not_found` | No existe, o no lo puedes ver |
| 409 | `conflict` y otros | Choca con el estado actual |

## Quién puede qué [#quién-puede-qué]

Hay que ser miembro del workspace para cualquier ruta bajo `/api/w/{ws}`. Si no lo eres, la respuesta es 404, igual
que si no existiera. Lo mismo pasa con un issue fuera de tu audiencia.

Algunas rutas piden el rol `admin` (o `owner`) del workspace. Las que ejecutan código en la máquina del servidor
o abren conexiones desde ella piden también ser el administrador de la instancia: la cuenta en `INSTANCE_ADMINS` o,
si no está definida, la primera que se registró. Cada página de ruta dice lo que exige.

## Tiempo real [#tiempo-real]

Los eventos del workspace y las terminales en vivo van por WebSocket. Sus mensajes están en
[WebSocket](/docs/referencia/websocket).