HTTP API

HTTP API är integrationsgränssnittet för Beam Bench. Skrivbordsappen, CLI:t och externa klienter använder samma rutter. Om du har ett användningsfall där Beam Bench behövs i en miljö utan CLI (webbapp, integrationsserver, mobilapp eller egna verktyg) använder du API:t direkt.

API:t levereras med skrivbordsappen och körs i samma process. Ingen separat tjänst behöver installeras.

Standardvärden och säkerhet

I den aktuella versionen levereras den lokala API-servern med följande inställningar:

• Lokalt API: av.
• API-port: 5900.
• Tillåt enheter i nätverket att ansluta: av. När API:t är aktiverat binder det till 127.0.0.1 och accepterar endast anslutningar från den här datorn.

API:t lyssnar inte efter anslutningar förrän du aktivt väljer att aktivera det. Nätverksåtkomst kräver ett separat aktivt val eftersom API:t saknar autentisering och innehåller funktioner som kan flytta maskinen och aktivera lasern.

Om du vill använda API:t ändrar du inställningarna i Inställningar → Allmänt:

1. Öppna skrivbordsappen.
2. Redigera → Inställningar → Allmänt.
3. Aktivera Lokalt API.
4. Låt Tillåt enheter i nätverket att ansluta vara avstängt om inte en annan betrodd enhet måste ansluta.

Ändringarna börjar gälla omedelbart; ingen omstart behövs.

Bas-URL

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

<host> är localhost (eller 127.0.0.1) när Tillåt enheter i nätverket att ansluta är avstängt. När det är aktiverat kan servern nås via maskinens LAN-IP från valfri enhet i nätverket.

Porten kan konfigureras i Inställningar → Allmänt; 5900 är standardvärdet.

Autentisering

Ingen. API:t har ingen token, ingen nyckel och ingen inloggning.

• Vid localhost-bindning är operativsystemets åtkomstmodell gränsen: alla processer på din dator kan kommunicera med API:t.
• När nätverksbindning är aktiverad kan alla i samma nätverk kommunicera med API:t. Använd inte nätverksbindningsläget i otillförlitliga Wi-Fi-nätverk.

Begärandeformat

Alla POST-/PATCH-/PUT-bodies är JSON:

Content-Type: application/json

Frågesträngar är platta nyckel=värde. Sökvägssegment URL-kodas på vanligt sätt.

Svarskuvert

Lyckade svar returnerar resursens body direkt, utan omslag:

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

Fel returnerar ett enhetligt kuvert:

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

error.code är ett av följande:

Fel som kräver bekräftelse

Ett mindre antal åtgärder kan flytta maskinen eller aktivera lasern. Dessa endpoints kräver en uttrycklig bekräftelseflagga i request-bodyn. Om den saknas returnerar API:t 428 Precondition Required:

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

Skicka begäran igen med den angivna flaggan satt till true. Flaggorna som används för närvarande är confirm_motion, confirm_laser_on, confirm_raw_gcode och confirm_air_assist.

Endpointgrupper

Referenssidor för enskilda resurser är under utveckling; använd agentens funktionsschema under tiden.

Upptäck det aktiva gränssnittet

Det snabbaste sättet att se vad din installerade version exponerar:

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

Detta returnerar hela funktionsschemat, inklusive varje endpoint, dess parametrar och svarsformat. Schemat är den auktoritativa beskrivningen; den här sidan är en guide till det.

För inspektion av tillstånd:

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

För en skriftlig introduktion till hur du styr appen:

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

Versionshantering

Alla rutter finns under /api/v1. Bakåtinkompatibla ändringar hamnar i /api/v2 när de sker. Tillägg (nya endpoints och nya valfria fält) levereras i v1 utan versionsändring.

Relaterat

• Guiden till HTTP API: en introduktion i handledningsformat med genomarbetade exempel.
• Så delar CLI:t och appen tillstånd: konsekvensmodellen bakom dessa endpoints.
• Inställningar → Allmänt: där du aktiverar API:t och väljer port.