API HTTP

La API HTTP es la interfaz de integración de Beam Bench. La mayoría de los comandos de la CLI y los clientes externos usan estas rutas. El frontend de escritorio llama al servicio compartido mediante Tauri IPC y no necesita el servidor HTTP para el uso normal. Si tienes un caso de uso que requiere Beam Bench en un entorno que no sea la CLI (aplicación web, servidor de integración, aplicación móvil o tus propias herramientas), usa la API directamente.

La API se incluye con la aplicación de escritorio y se ejecuta en el mismo proceso. No hay ningún servicio independiente que instalar.

Valores predeterminados y seguridad

En la compilación actual, el servidor de API local se incluye con estos ajustes:

• API local: desactivada.
• Puerto de la API: 5900.
• Permitir dispositivos de red: desactivado. Cuando la API está activada, se enlaza a 127.0.0.1 y solo acepta conexiones desde este equipo.

La API no escucha conexiones hasta que aceptas activarla. Activar el acceso de red requiere una aceptación independiente porque la API no tiene autenticación e incluye operaciones que pueden mover la máquina y disparar el láser.

Para usar la API, cambia sus ajustes desde Configuración → General:

1. Abre la aplicación de escritorio.
2. Editar → Configuración → General.
3. Activa API local.
4. Deja Permitir dispositivos de red desactivado a menos que otro dispositivo de confianza tenga que conectarse.

Los cambios se aplican inmediatamente; no es necesario reiniciar.

URL base

http://<host>:5900/api/v1

<host> es localhost (o 127.0.0.1) cuando Permitir dispositivos de red está desactivado. Cuando está activado, se puede acceder al servidor desde cualquier dispositivo de la red mediante la IP LAN de la máquina.

El puerto se puede configurar en Configuración → General; 5900 es el valor predeterminado.

Autenticación

Ninguna. La API no tiene token, clave ni inicio de sesión.

• Con el enlace a localhost, el modelo de acceso del sistema operativo es el límite: cualquier proceso de tu máquina puede comunicarse con la API.
• Con el enlace de red activado, cualquiera que esté en la misma red puede comunicarse con la API. No uses el modo de enlace de red en una Wi-Fi que no sea de confianza.

Formato de las solicitudes

Todos los cuerpos POST/PATCH/PUT son JSON:

Content-Type: application/json

Las cadenas de consulta son pares clave=valor planos. Los segmentos de ruta se codifican como URL de la forma habitual.

Envoltorio de respuesta

Las respuestas correctas devuelven directamente el cuerpo del recurso, sin envoltorio:

{
  "field": "value",
  "...": "..."
}

Los errores devuelven un envoltorio uniforme:

{
  "error": {
    "code": "invalid_input",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code puede ser uno de estos valores:

Errores que requieren confirmación

Un pequeño conjunto de operaciones puede mover la máquina o disparar el láser. Esos endpoints requieren una marca de confirmación explícita en el cuerpo de la solicitud. Si falta, la API devuelve 428 Precondition Required:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

Vuelve a enviar la solicitud con la marca indicada establecida en true. Las marcas que se usan actualmente son confirm_motion, confirm_laser_on, confirm_raw_gcode y confirm_air_assist.

Ediciones simultáneas del proyecto

Las transacciones de Diseño comparan el proyecto capturado en el momento de confirmar los cambios. Una edición simultánea, un cambio de proyecto o un cierre pueden devolver stale_revision. Actualiza el estado y vuelve a valorar el cambio antes de reintentarlo. No reproduzcas a ciegas una instantánea antigua del proyecto sobre un trabajo más reciente.

Grupos de endpoints

Las páginas de referencia de cada recurso aún están en desarrollo; mientras tanto, consulta el esquema de capacidades del agente.

Descubrir la interfaz activa

La forma más rápida de ver lo que expone tu versión instalada:

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Esto devuelve el esquema completo de capacidades, incluidos todos los endpoints, sus parámetros y la forma de sus respuestas. El esquema es la descripción de referencia; esta página es una guía para interpretarlo.

Para inspeccionar el estado:

curl -s http://localhost:5900/api/v1/agent/state | jq .

Para obtener una orientación escrita sobre cómo controlar la aplicación:

curl -s http://localhost:5900/api/v1/agent/guide

Versionado

Todas las rutas están bajo /api/v1. Los cambios incompatibles se incorporan a /api/v2 cuando se producen. Los cambios aditivos (nuevos endpoints y nuevos campos opcionales) se publican en v1 sin aumentar la versión.

Relacionado

• Guía para usar la API HTTP: introducción con formato de tutorial y ejemplos completos.
• Cómo comparten el estado la CLI y la aplicación: el modelo de coherencia que sustenta estos endpoints.
• Configuración → General: dónde activar la API y elegir el puerto.