API HTTP

A API HTTP é a interface de integração do Beam Bench. O app para desktop, a CLI e qualquer cliente externo usam as mesmas rotas. Se você tem um caso de uso que exige o Beam Bench em um ambiente que não seja de CLI (app web, servidor de integração, app móvel ou suas próprias ferramentas), use a API diretamente.

A API é fornecida com o app para desktop e é executada no processo dele. Não há um serviço separado para instalar.

Padrões e segurança

Na versão atual, o servidor de API local é fornecido com estas configurações:

• API local: desativada.
• Porta da API: 5900.
• Permitir dispositivos de rede: desativada. Quando a API está ativada, ela se vincula a 127.0.0.1 e aceita conexões somente deste computador.

A API não escuta conexões até que você a habilite. Habilitar o acesso pela rede é uma opção separada porque a API não tem autenticação e inclui operações que podem movimentar a máquina e disparar o laser.

Para usar a API, altere as configurações dela em Configurações → Geral:

1. Abra o app para desktop.
2. Editar → Configurações → Geral.
3. Ative API local.
4. Mantenha Permitir dispositivos de rede desativado, a menos que outro dispositivo confiável precise se conectar.

As alterações têm efeito imediato; não é necessário reiniciar.

URL base

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

<host> é localhost (ou 127.0.0.1) quando Permitir dispositivos de rede está desativado. Quando está ativado, o servidor pode ser acessado pelo IP da LAN da máquina a partir de qualquer dispositivo na rede.

A porta pode ser configurada em Configurações → Geral; 5900 é o padrão.

Autenticação

Nenhuma. A API não tem token, chave nem login.

• Com a vinculação a localhost, o modelo de acesso do sistema operacional é o limite: qualquer processo na sua máquina pode se comunicar com a API.
• Com a vinculação à rede ativada, qualquer pessoa na mesma rede pode se comunicar com a API. Não use o modo de vinculação à rede em Wi-Fi não confiável.

Formato da solicitação

Todos os corpos de POST/PATCH/PUT são JSON:

Content-Type: application/json

As strings de consulta são pares simples chave=valor. Os segmentos de caminho são codificados em URL normalmente.

Envelope de resposta

As respostas bem-sucedidas retornam o corpo do recurso diretamente, sem wrapper:

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

Os erros retornam um envelope uniforme:

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

error.code é um destes:

Erros que exigem confirmação

Um pequeno conjunto de operações pode movimentar a máquina ou disparar o laser. Esses endpoints exigem uma sinalização explícita de confirmação no corpo da solicitação. Se ela estiver ausente, a API retornará 428 Precondition Required:

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

Envie novamente a solicitação com a sinalização nomeada definida como true. As sinalizações atualmente em uso são confirm_motion, confirm_laser_on, confirm_raw_gcode e confirm_air_assist.

Grupos de endpoints

As páginas de referência por recurso estão em desenvolvimento; enquanto isso, consulte o esquema de recursos do agente.

Descubra a interface disponível

A maneira mais rápida de ver o que sua versão instalada expõe:

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

Isso retorna o esquema completo de recursos, incluindo cada endpoint, seus parâmetros e o formato de resposta. O esquema é a descrição oficial; esta página é um guia para ele.

Para inspecionar o estado:

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

Para uma orientação escrita sobre como controlar o app:

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

Versionamento

Todas as rotas estão em /api/v1. Alterações incompatíveis entrarão em /api/v2 quando ocorrerem. Alterações aditivas (novos endpoints, novos campos opcionais) são fornecidas em v1 sem aumento de versão.

Relacionados

• Guia de uso da API HTTP: uma introdução em estilo tutorial com exemplos práticos.
• Como a CLI e o app compartilham estado: o modelo de consistência por trás destes endpoints.
• Configurações → Geral: onde ativar a API e escolher a porta.