HTTP API

HTTP API är integrationsgränssnittet för Beam Bench. De flesta CLI-kommandon och externa klienter använder dessa rutter. Skrivbordsfrontend anropar den delade tjänsten via Tauri IPC och behöver inte HTTP-servern vid normal användning. Om du har ett användningsfall som kräver Beam Bench i en miljö som inte använder CLI (webbapp, integrationsserver, mobilapp, 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.

Standardinställningar och säkerhet

I den aktuella versionen levereras den lokala API-servern med dessa 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 själv aktiverar det. Nätverksåtkomst kräver ett separat aktivt val eftersom API:t saknar autentisering och innehåller åtgärder som kan flytta maskinen och avfyra lasern.

Om du vill använda API:t ändrar du inställningarna från 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 direkt, 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 på 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.

• Med localhost-bindning är åtkomstmodellen på OS-nivå gränsen: alla processer på din maskin 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 på otillförlitligt Wi-Fi.

Begärandeformat

Alla POST/PATCH/PUT-innehåll är JSON:

Content-Type: application/json

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

Svarskuvert

Lyckade svar returnerar resursens innehåll direkt, utan omslag:

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

Fel returnerar ett enhetligt kuvert:

{
  "error": {
    "code": "invalid_input",
    "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 avfyra lasern. Dessa slutpunkter kräver en uttrycklig bekräftelseflagga i begärans innehåll. 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.

Samtidiga projektändringar

Designtransaktioner jämför sitt avbildade projekt när ändringarna verkställs. En samtidig ändring, ett projektbyte eller en stängning kan returnera stale_revision. Uppdatera tillståndet och bedöm ändringen på nytt innan du försöker igen. Spela inte blint upp en äldre projektavbild ovanpå nyare arbete.

Slutpunktsgrupper

Referenssidor för enskilda resurser är under utveckling. Läs tills vidare schemat för agentfunktioner.

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 schemat för funktionerna, inklusive varje slutpunkt, dess parametrar och dess svarsformat. Schemat är den auktoritativa beskrivningen; den här sidan är en vägledning.

För att granska tillståndet:

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

För en skriftlig introduktion till hur appen styrs:

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

Versionshantering

Alla rutter ligger under /api/v1. Brytande ändringar hamnar i /api/v2 när de sker. Tillägg (nya slutpunkter, nya valfria fält) levereras i v1 utan versionsändring.

Relaterat

• Guiden Använda HTTP API: en handledningslik introduktion med genomarbetade exempel.
• Så delar CLI och app tillstånd: konsekvensmodellen bakom dessa slutpunkter.
• Inställningar → Allmänt: där du aktiverar API:t och väljer port.