API REST
Autenticación, errores y permisos de la API de HQ Fabric, con una página por cada una de sus 241 rutas.
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.
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.
curl -s http://127.0.0.1:8080/api/configGET /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
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
Pides un código para tu correo y lo canjeas por un JWT de 7 días.
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:
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
Un error trae siempre la misma forma:
{ "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é
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
Los eventos del workspace y las terminales en vivo van por WebSocket. Sus mensajes están en WebSocket.