HTTP API

모든 HTTP 클라이언트에서 Beam Bench를 제어합니다. CLI가 통신하는 것과 동일한 인터페이스입니다.

HTTP API는 Beam Bench의 통합 인터페이스입니다. 대부분의 CLI 명령과 외부 클라이언트는 이 경로를 사용합니다. 데스크톱 프런트엔드는 Tauri IPC를 통해 공유 서비스를 호출하므로 일반적인 사용에는 HTTP 서버가 필요하지 않습니다. 웹 앱, 통합 서버, 모바일 앱 또는 자체 도구처럼 CLI가 아닌 환경에서 Beam Bench를 사용해야 한다면 API를 직접 사용하세요.

API는 데스크톱 앱에 포함되어 프로세스 내부에서 실행됩니다. 별도로 설치할 서비스는 없습니다.

기본값 및 보안

현재 빌드의 로컬 API 서버에는 다음 설정이 적용됩니다.

로컬 API: 꺼짐.
API 포트: 5900.
네트워크 장치 연결 허용: 꺼짐. API를 활성화하면 127.0.0.1에 바인딩되어 이 컴퓨터에서만 연결을 허용합니다.

API는 사용자가 명시적으로 활성화하기 전까지 연결을 수신하지 않습니다. API에는 인증이 없고 머신을 이동하거나 레이저를 작동시킬 수 있는 작업이 포함되므로 네트워크 액세스 활성화는 별도의 명시적 선택입니다.

API를 사용하려면 설정 → 일반에서 설정을 변경하세요.

데스크톱 앱을 엽니다.
편집 → 설정 → 일반을 선택합니다.
로컬 API를 켭니다.
다른 신뢰할 수 있는 장치가 연결해야 하는 경우가 아니면 네트워크 장치 연결 허용을 꺼진 상태로 둡니다.

변경 사항은 즉시 적용되며 다시 시작할 필요가 없습니다.

기본 URL

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

네트워크 장치 연결 허용이 꺼져 있으면 <host>는 localhost 또는 127.0.0.1입니다. 켜져 있으면 네트워크의 모든 장치에서 머신의 LAN IP로 서버에 연결할 수 있습니다.

포트는 설정 → 일반에서 구성할 수 있으며 기본값은 5900입니다.

인증

없습니다. API에는 토큰, 키 또는 로그인 기능이 없습니다.

localhost 바인딩에서는 운영 체제 수준의 액세스 모델이 경계입니다. 머신의 모든 프로세스가 API와 통신할 수 있습니다.
네트워크 바인딩을 활성화하면 같은 네트워크의 누구나 API와 통신할 수 있습니다. 신뢰할 수 없는 Wi-Fi에서는 네트워크 바인딩 모드를 사용하지 마세요.

요청 형식

모든 POST/PATCH/PUT 본문은 JSON입니다.

Content-Type: application/json

쿼리 문자열은 평면적인 key=value 형식입니다. 경로 세그먼트는 일반적인 방식으로 URL 인코딩됩니다.

응답 봉투

성공한 응답은 래퍼 없이 리소스 본문을 직접 반환합니다.

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

오류는 통일된 봉투로 반환됩니다.

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

error.code는 다음 중 하나입니다.

코드	HTTP	의미
`not_found`	404	요청한 리소스가 존재하지 않습니다.
`invalid_input`	400	요청 본문 또는 매개변수의 형식이 잘못되었거나 거부되었습니다.
`invalid_state`	412	앱이 이 작업을 수행할 수 있는 상태가 아닙니다(예: 열린 프로젝트 없음).
`busy`	409	충돌하는 작업이 이미 진행 중입니다.
`conflict`	409	마지막으로 읽은 후 다른 작성자가 리소스를 변경했습니다.
`stale_revision`	412	수정 토큰이 현재 토큰보다 뒤처져 있습니다. 다시 읽고 재시도하세요.
`machine_io`	502	머신 연결에 실패했습니다(연결 끊김, 시간 초과, 전송 오류).
`persistence`	500	디스크 쓰기 또는 읽기에 실패했습니다.
`internal`	500	예기치 않은 서버 오류입니다. 버그로 보고하세요.

확인이 필요한 오류

머신을 이동하거나 레이저를 작동시킬 수 있는 작업이 일부 있습니다. 이러한 엔드포인트는 요청 본문에 명시적인 확인 플래그가 필요합니다. 플래그가 없으면 API는 428 Precondition Required를 반환합니다.

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

이름이 지정된 플래그를 true로 설정하여 요청을 다시 전송하세요. 현재 사용되는 플래그는 confirm_motion, confirm_laser_on, confirm_raw_gcode, confirm_air_assist입니다.

동시 프로젝트 편집

디자인 트랜잭션은 커밋 시 캡처한 프로젝트를 비교합니다. 동시에 발생한 편집, 프로젝트 전환 또는 닫기로 인해 stale_revision이 반환될 수 있습니다. 상태를 새로 고치고 변경 사항을 다시 검토한 후 재시도하세요. 이전 프로젝트 스냅샷을 최신 작업 위에 무조건 다시 적용하지 마세요.

엔드포인트 그룹

경로	범위
`/api/v1/app`	앱 수준 정보: 버전, 가동 시간, 기능.
`/api/v1/agent`	에이전트 기능 스키마, 상태 스냅샷, 운영 안내.
`/api/v1/projects`	열기, 저장, 닫기. 레이어, 객체, 실행 취소 및 다시 실행.
`/api/v1/projects/import`	LightBurn, SVG, DXF, PDF, AI, EPS 및 래스터 파일 가져오기. 제한된 G-code 도형 가져오기는 전용 경로에서 처리합니다.
`/api/v1/export`	프로젝트를 SVG, DXF, PDF, EPS, AI로 렌더링.
`/api/v1/design`	현재 디자인 설명, PNG 렌더링, 트랜잭션 편집 적용.
`/api/v1/preview`	컷 미리보기와 통계 생성.
`/api/v1/jobs`	사전 검사, 실행, 드라이 런, 일시중지, 재개, 프레임, 중지.
`/api/v1/machine`	연결, 연결 해제, 상태, 조그, 홈 이동.
`/api/v1/camera`	장치, 상태, 캡처, 오버레이(표시, 변환, 렌더링), 보정, 정렬.
`/api/v1/console`	원시 G-code 전송. 최근 콘솔 로그 읽기.
`/api/v1/macros`	사용자 매크로 나열, 저장 및 실행.
`/api/v1/materials`	재료 라이브러리: 재료와 두께를 키로 사용하는 프리셋.
`/api/v1/profiles`	머신 프로필: 생성, 나열, 적용.
`/api/v1/assets`	아트 라이브러리 에셋 액세스.
`/api/v1/vector`	벡터 작업: 변환, 부울, 그룹, 경로.
`/api/v1/events`	상태 변경 및 머신 이벤트의 WebSocket 스트림.

리소스별 참조 페이지는 현재 작성 중입니다. 그동안에는 에이전트 기능 스키마를 참조하세요.

현재 인터페이스 확인

설치된 버전에서 제공하는 기능을 확인하는 가장 빠른 방법은 다음과 같습니다.

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

이 명령은 모든 엔드포인트, 매개변수 및 응답 형태를 포함한 전체 기능 스키마를 반환합니다. 스키마가 권위 있는 설명이며 이 페이지는 이를 안내하는 문서입니다.

상태를 확인하려면 다음을 실행하세요.

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

앱을 제어하는 방법을 설명한 안내를 보려면 다음을 실행하세요.

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

버전 관리

모든 경로는 /api/v1 아래에 있습니다. 호환성이 깨지는 변경 사항이 발생하면 /api/v2에 추가됩니다. 추가적 변경 사항(새 엔드포인트, 새로운 선택적 필드)은 버전 증가 없이 v1에 포함됩니다.