HTTP 라우트

HTTP API는 표면별로 묶여 있습니다. 아래 각 경로는 엔드포인트별 상세 명세 페이지로 연결됩니다.

인증

GET /health는 공개되어 있습니다. SNA 런타임의 그 밖의 모든 라우트는 /api/sna-port, SSE 라우트, chat image 조회를 포함해 Authorization: Bearer <authToken>을 요구합니다. 토큰이 없거나 맞지 않으면 401, 허용되지 않은 browser origin이면 403을 반환합니다.

SDK가 관리하는 host는 handle.connection을 SnaClient나 SnaProvider에 전달하면 됩니다. 별도의 앱 소유 discovery endpoint가 신뢰된 renderer에 { baseUrl, authToken }을 반환할 수 있지만, SNA 런타임 자체의 /api/sna-port 라우트는 계속 보호됩니다.

시스템

메서드	경로	용도
`GET`	`/health`	Health check
`GET`	`/api/sna-port`	현재 SNA API 포트 조회

세션

메서드	경로	용도
`POST`	`/agent/sessions`	세션 레코드 생성
`GET`	`/agent/sessions`	세션 목록 조회
`PATCH`	`/agent/sessions/{id}`	label, meta, cwd 갱신
`DELETE`	`/agent/sessions/{id}`	세션, 히스토리, runtime chain, 대기 중인 권한 삭제

에이전트 라이프사이클

메서드	경로	용도
`POST`	`/agent/start`	세션 안에 에이전트 spawn
`POST`	`/agent/send`	메시지 전송
`POST`	`/agent/restart`	종료 후 re-spawn
`POST`	`/agent/resume`	정규화 히스토리로 재개
`POST`	`/agent/interrupt`	현재 턴 취소
`POST`	`/agent/set-model`	런타임 중 모델 변경
`POST`	`/agent/set-permission-mode`	런타임 중 권한 모드 변경
`PATCH`	`/agent/session`	통합 설정 mutator
`POST`	`/agent/kill`	에이전트 프로세스 종료
`GET`	`/agent/status`	상태 스냅샷

단발 호출

메서드	경로	용도
`POST`	`/agent/run-once`	한 번 실행하고 결과 반환
`POST`	`/agent/run-once/stream`	SSE 이벤트로 단발 실행
`POST`	`/agent/completion`	단발 completion

권한

메서드	경로	용도
`POST`	`/agent/permission-request`	권한 요청 제출 후 대기
`POST`	`/agent/permission-respond`	승인 또는 거부
`GET`	`/agent/permission-pending`	pending 요청 목록 조회

모델과 이벤트

메서드	경로	용도
`POST`	`/agent/list-models`	런타임 모델 introspection
`GET`	`/agent/events`	세션 이벤트 SSE 스트림

Chat (정규화 히스토리 표면)

메서드	경로	용도
`GET`	`/chat/sessions`	DB의 chat 세션 목록
`POST`	`/chat/sessions`	chat 세션 생성
`DELETE`	`/chat/sessions/{id}`	chat 세션 삭제
`GET`	`/chat/sessions/{id}/messages`	메시지 목록 조회
`POST`	`/chat/sessions/{id}/messages`	메시지 추가
`DELETE`	`/chat/sessions/{id}/messages`	메시지 삭제
`GET`	`/chat/images/{sessionId}/{filename}`	이미지 embed 제공

응답 모양

대부분의 SDK-facing 응답은 server/api-types.ts의 envelope을 따릅니다. streaming 및 binary 엔드포인트는 wire-native 응답 본문을 사용합니다. 정확한 schema는 라이브 OpenAPI 문서에서 확인하세요.

type ApiResponse<T> =
  | { status: "ok"; data: T }
  | { status: "error"; message: string; code?: string };

HTTP 라우트

목차