Ir al contenido
HQ Fabric

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/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

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

CredencialPrefijoSirve 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 APIhqf_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 runtimehqfrt_Las rutas /api/daemon/*, que usa el daemon hqf
Token de la tareahqftk_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:

EstadoCódigoQué significa
400bad_json, invalidEl cuerpo no es JSON válido, o un dato no pasa la validación
401unauthorizedFalta la credencial o ya no vale
403forbiddenTu rol en el workspace no alcanza
403session_requiredLa ruta sólo acepta la sesión del navegador
403token_scopeEl alcance de tu token no llega a esta ruta
403instance_admin_requiredSólo el administrador de la instancia
404not_found, workspace_not_foundNo existe, o no lo puedes ver
409conflict y otrosChoca 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.

En esta página