API 개요
HTTP 라우트, WebSocket 프로토콜, 이벤트 타입을 한곳에서 봅니다.
이 섹션은 와이어 레퍼런스입니다. 각 형태가 왜 이렇게 설계되었는지는 핵심 모델에서 다룹니다. SNA의 HTTP/WebSocket API와 ACP를 비교하고 있다면 SNA와 ACP 도 같이 보세요.
엔드포인트 레퍼런스
모든 HTTP 엔드포인트의 요청 필드, 응답, 비고.
HTTP 라우트
서버 엔드포인트를 표면별로 묶은 목록.
WebSocket 프로토콜
Request/response op, 푸시 채널, 재연결 규칙.
이벤트
15가지 AgentEvent 타입, 델타, 최종 이벤트.
OpenAPI 스펙
실행 중인 서버가 직접 제공하는 라이브 스펙.
계약의 기준
서버의 Hono 앱은 @hono/zod-openapi 라우트 정의로 빌드됩니다. 실행 중인
서버는 같은 Zod 스키마에서 생성한 OpenAPI 3.1 스펙을 직접 제공합니다.
따라서 이 문서의 와이어 형태, SDK 타입, 라이브 스펙은 같은 소스에서
파생됩니다.
| URL | 용도 |
|---|---|
GET /openapi.json | 원시 스펙 JSON |
GET /docs | Swagger UI |
GET /spec | 평문 스펙 |
인증
GET /health를 제외한 모든 런타임 HTTP 라우트는
Authorization: Bearer <authToken>을 요구합니다. SSE 스트림과 WebSocket
upgrade도 같은 토큰으로 보호됩니다. SDK 런처는 이 값을
handle.connection.authToken으로 반환하므로 클라이언트에는
handle.connection을 그대로 전달하는 편이 안전합니다.
OpenAPI 문서는 전역 bearerAuth를 선언하고, /health의 보안 요구사항은
비우며, 보호된 라우트에 401/403 응답을 표시합니다.
정확한 계약을 확인해야 할 때는 라이브 서버의 스펙을 직접 조회하세요. 라이브 스펙이 항상 최종 기준입니다.