Interfaz REST

Salvo que se indique lo contrario, todas las interfaces requieren la API Key del inquilino en la cabecera:

Authorization: Bearer <API Key del inquilino>

La dirección por defecto es http://localhost:8787 y el inquilino de demostración es demo (la apiKey se genera aleatoriamente en el primer arranque y se imprime en el registro). Esta página es una referencia para integraciones; los usuarios normales no necesitan preocuparse por ella.

Iniciar el servidor

# Se puede iniciar sin clave de modelo (autenticación/sesiones/interfaces se pueden probar; solo la conversación dará error)
pnpm run server

# Con un modelo real (recomendado)
OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-4o-mini pnpm run server

Variables principales: PORT (8787 por defecto), DATA_DIR (./.zqagent_data por defecto), APPROVAL_TIMEOUT_SECONDS (tiempo de espera de aprobaciones/preguntas, 900 por defecto), TENANT_ID / TENANT_API_KEY / MODEL (inquilino de demostración).

Autenticación

export BASE=http://localhost:8787
export TOKEN=zk_xxxx   # la apiKey de la línea «已创建演示租户» del registro de arranque

# Comprobación de estado (pública)
curl -s $BASE/healthz                 # => {"status":"ok"}

# Sin Key → 401
curl -s -o /dev/null -w "%{http_code}\n" $BASE/api/v1/sessions   # => 401

# Key correcta → 200
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" $BASE/api/v1/sessions

Endpoints principales

Conversaciones

Método	Ruta	Descripción
GET	/healthz	Comprobación de estado (pública)
POST	/api/v1/sessions	Crear conversación
GET	/api/v1/sessions	Listar conversaciones
GET	/api/v1/sessions/{id}	Obtener conversación
PATCH	/api/v1/sessions/{id}	Renombrar conversación
DELETE	/api/v1/sessions/{id}	Eliminar conversación
GET	/api/v1/sessions/{id}/state	Estado (incluye aprobaciones/preguntas pendientes)
PATCH	/api/v1/sessions/{id}/model	Cambiar el modelo de la conversación
PATCH	/api/v1/sessions/{id}/mode	Cambiar el modo de permisos (plan / interactive / auto / discuss)
PATCH	/api/v1/sessions/{id}/draft	Guardar el borrador del cuadro de entrada (cadena vacía = borrar)
POST	/api/v1/sessions/{id}/turns	Enviar tarea
POST	/api/v1/sessions/{id}/steer	Información adicional en ejecución
POST	/api/v1/sessions/{id}/interrupt	Interrumpir la tarea actual
POST	/api/v1/sessions/{id}/resume	Reanudar la conversación
GET	/api/v1/sessions/{id}/events	Flujo de eventos (sondeo o SSE, con ?since= incremental)
GET	/api/v1/sessions/{id}/approvals	Aprobaciones pendientes
POST	/api/v1/sessions/{id}/approvals/{aid}	Responder a una aprobación
GET	/api/v1/sessions/{id}/questions	Preguntas pendientes
POST	/api/v1/sessions/{id}/questions/{qid}	Responder a una pregunta

Proyectos y nodos

Método	Ruta	Descripción
GET / POST	/api/v1/projects	Listar / crear proyectos (indica el directorio de trabajo al crear)
DELETE	/api/v1/projects/{id}	Eliminar proyecto
GET	/api/v1/models	Modelos disponibles
GET / PUT	/api/v1/config	Ver / actualizar la configuración del nodo
GET / PUT	/api/v1/node/llm	Ver / definir el modelo predeterminado del nodo
GET	/api/v1/node/host	Información del host del nodo
GET	/api/v1/tools	Lista de herramientas
GET	/api/v1/mcp	Lista de servidores MCP
PUT	/api/v1/mcp	Reemplazar toda la configuración MCP (escribe .agent/mcp.json; 409 si la entrega la plataforma)
POST	/api/v1/mcp/test	Probar la conexión de un servidor MCP (sin guardar)

Uso y coste

Método	Ruta	Descripción
GET	/api/v1/usage/summary	Resumen de uso (por periodo / modelo)
GET	/api/v1/usage/records	Registros de detalle
GET	/api/v1/usage/export	Exportar CSV
GET / PUT	/api/v1/usage/pricing	Ver / modificar la tabla de precios
POST	/api/v1/usage/rebuild	Reconstruir el resumen
POST	/api/v1/usage/verify	Verificar el libro mayor

Acceso remoto y emparejamiento

Método	Ruta	Descripción
GET	/api/v1/fleet/status	Estado de conexión del nodo
POST	/api/v1/fleet/enroll	Conectar con código (lo llama zqagent link)
POST	/api/v1/fleet/unlink	Desconectar
GET	/api/v1/fleet/pairing	Información de emparejamiento en la nube (pasarela + espacio de nombres/clave + nodeId)
GET / POST	/api/v1/notifications	Ver / añadir canales de notificación
DELETE	/api/v1/notifications/{id}	Eliminar un canal de notificación

Inicio rápido

# Crear una conversación
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini"}' $BASE/api/v1/sessions
# => {"data":{"sessionId":"e4df66d6...","status":"idle",...}}

export SID=e4df66d6...   # sustituye por el sessionId devuelto

# Enviar tarea (responde de inmediato; se ejecuta en segundo plano)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"input":"Hola, preséntate"}' $BASE/api/v1/sessions/$SID/turns
# => {"data":{"accepted":true,"status":"running"}}

# Sondear eventos (incremental con el cursor since)
curl -s "$BASE/api/v1/sessions/$SID/events?since=0"

# Suscripción en tiempo real (SSE)
curl -N -H "Authorization: Bearer $TOKEN" -H "Accept: text/event-stream" \
  $BASE/api/v1/sessions/$SID/events

Si la conversación está ejecutando una tarea, POST /turns se convierte automáticamente en información adicional inyectada en la tarea actual (devuelve {"data":{"accepted":true,"status":"steering"}}), en lugar de dar error.

Aprobaciones y preguntas

Cuando el modelo pide una operación con efectos secundarios (escribir archivos, ejecutar comandos, etc.) queda suspendido esperando aprobación; al llamar a herramientas como ask_user queda suspendido esperando respuesta.

# Ver aprobaciones pendientes (el id es el ID de la llamada a la herramienta)
curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/v1/sessions/$SID/approvals

# Responder a la aprobación: once | always_tool | always_command | deny
#   always_command solo es válido para run_shell
export AID=call_xxx
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"decision":"once"}' $BASE/api/v1/sessions/$SID/approvals/$AID

# Responder a una pregunta
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"answer":"continúa"}' $BASE/api/v1/sessions/$SID/questions/qid_xxx

Aislamiento multiinquilino

Cada inquilino accede a sus conversaciones con su propia API Key; usar la Key del inquilino A para una conversación del inquilino B devuelve 404.

Códigos de error

HTTP	code	Situación
401	unauthorized	Sin Key / Key no válida
404	not_found	Conversación inexistente / ruta desconocida / acceso entre inquilinos
409	not_running	Al hacer steer explícito, la conversación no está en ejecución
409	has_pending_interaction	Hay aprobaciones/preguntas pendientes y no se puede enviar una tarea nueva
400	bad_request	JSON del body no válido / input vacío
400	invalid_decision	decision no válida, o always_command en algo que no es run_shell