REST API 참조¶
모든 업무 API는 JSON 기반 /v1 REST입니다. App Backend는 WebSocket 엔드포인트를 제공하지
않습니다. 회원 JWT와 워크스페이스 API key는 모두 Authorization: Bearer ...를 사용하며,
필요한 경로에는 X-Workspace-Id: <uuid>를 함께 보냅니다.
표의 JWT는 회원 access token, API key는 SCOPE_WORKSPACE_READ를 뜻합니다.
인증과 회원¶
| 메서드·경로 | 인증 | 설명 |
|---|---|---|
POST /v1/auth/signup |
공개 | 회원가입, 201 |
POST /v1/auth/login |
공개 | access/refresh 발급 |
POST /v1/auth/refresh |
공개 | refresh 검증·회전 |
GET /v1/members/me |
JWT | 내 프로필 |
PUT /v1/members/me |
JWT | 프로필·회사·동의 수정 |
PATCH /v1/members/me/password |
JWT | 현재 비밀번호 확인 후 변경 |
DELETE /v1/members/me |
JWT | soft delete, refresh 전체 폐기 |
GET /v1/members/me/configs |
JWT | 내 설정 목록 |
GET /v1/members/me/configs/{configCode} |
JWT | 내 설정 단건 |
PUT /v1/members/me/configs/{configCode} |
JWT | 멱등 upsert, 신규 201·갱신 200 |
DELETE /v1/members/me/configs/{configCode} |
JWT | 멱등 해제 |
현재 지원하는 configCode는 TTS_VOICE입니다.
워크스페이스와 credential¶
| 메서드·경로 | 인증·테넌트 | 설명 |
|---|---|---|
POST /v1/workspaces |
JWT | 생성자 OWNER 부트스트랩, 헤더 불요 |
GET /v1/workspaces |
JWT | 내 ACTIVE 소속 페이지, 헤더 불요 |
POST /v1/workspaces/api-keys |
JWT + 헤더 + OWNER | API key 발급, 원본 1회 노출 |
GET /v1/workspaces/api-keys |
JWT + 헤더 + OWNER | 상태 포함 목록, 원본·해시 제외 |
DELETE /v1/workspaces/api-keys/{keyId} |
JWT + 헤더 + OWNER | REVOKED 전환 |
POST /v1/workspaces/client-secrets |
JWT + 헤더 + ACTIVE 멤버 | Ed25519 단기 JWT 발급, 201 |
client-secret 요청 body는 생략 가능하며 expiresInSeconds는 300..10,800초로 clamp됩니다.
시나리오¶
| 메서드·경로 | 인증·테넌트 | 설명 |
|---|---|---|
POST /v1/scenarios |
JWT + 헤더 | 신규 201, 기존 slug 이력 append 200; Graph Builder 검증 없음 |
GET /v1/scenarios |
JWT + 헤더 | 워크스페이스 시나리오 페이지 |
GET /v1/scenarios/{id} |
JWT + 헤더 | 상세 |
GET /v1/scenarios/{scenarioId}/histories |
JWT + 헤더 | 이력 페이지, scenarioStatus 선택 |
GET /v1/scenarios/{scenarioId}/histories/{historyId} |
JWT + 헤더 | content 포함 이력 상세 |
POST /v1/scenario-templates |
ROLE_ADMIN JWT |
전역 템플릿 검증·등록, 201 |
GET /v1/scenario-templates |
JWT 또는 API key | 전역 템플릿 메타데이터 페이지 |
scenarioStatus 허용값은 DRAFT, NEEDS_REVIEW, PUBLISHED, ERROR입니다.
템플릿 등록은 Graph Builder /v1/session/validate를 호출하지만 deploy/publish는 호출하지
않습니다. 템플릿 본문 단건 GET·수정·삭제는 없습니다.
공개 기본·더미 시나리오¶
| 메서드·경로 | 인증 | 설명 |
|---|---|---|
GET /v1/base-scenarios/{language} |
공개 | 언어별 기본 시나리오 |
GET /v1/dummy-scenarios |
공개 | 더미 목록 |
GET /v1/dummy-scenarios/{id} |
공개 | 더미 상세 |
POST /v1/dummy-scenarios |
공개 | 더미 생성 |
PUT /v1/dummy-scenarios/{id} |
공개 | 더미 수정 |
DELETE /v1/dummy-scenarios/{id} |
공개 | 더미 삭제 |
POST /v1/dummy-scenarios/validate |
공개 | Graph Builder 검증, 저장 없음 |
공개 mutation은 현재 구현이지만 안전한 기본값은 아닙니다. 운영 전 보안 격차를 확인하세요.
대화·분석·음성¶
| 메서드·경로 | 인증·테넌트 | 설명 |
|---|---|---|
GET /v1/dialogs |
JWT 또는 API key | 목록; externalUserId, scenarioId, 페이지 |
GET /v1/dialogs/{dialogId} |
JWT 또는 API key | 상세; detail=false 기본 |
GET /v1/dialogs/sessions/{sessionId} |
JWT 또는 API key | 세션 ID 상세 |
GET /v1/dialogs/statistics |
JWT OWNER 또는 API key | groupId, 선택 날짜 범위 |
GET /v1/dialogs/statistics/users |
JWT OWNER 또는 API key | 구성원별 통계 페이지 |
GET /v1/dialogs/{dialogId}/messages/{messageId}/audio |
JWT + 헤더 또는 API key | GCS 음성 프록시 |
API key는 항상 귀속 워크스페이스로 격리됩니다. JWT 대화 목록·상세는 현재 헤더를 강제하지 않는 구현 경로가 있으므로 호출자는 헤더를 보내야 합니다. 음성 프록시는 JWT 헤더를 강제합니다.
사용자 그룹¶
모든 경로는 JWT, X-Workspace-Id, 해당 워크스페이스 OWNER가 필요합니다.
| 메서드·경로 | 설명 |
|---|---|
POST /v1/end-user-groups |
그룹 생성, 201 |
GET /v1/end-user-groups |
그룹 목록 |
POST /v1/end-user-groups/{groupId}/members |
externalUserIds 일괄 등록 |
GET /v1/end-user-groups/{groupId}/members |
구성원·매칭 여부 페이지 |
DELETE /v1/end-user-groups/{groupId}/members/{memberId} |
구성원 제외 |
음색 프리셋¶
| 메서드·경로 | 인증 | 설명 |
|---|---|---|
GET /v1/voice-presets |
JWT 또는 API key | 활성 프리셋 목록, 헤더 불요 |
응답은 선택용 presetCode, 표시명, 성별, 연령대만 제공합니다. 엔진 provider/model/parameter는
노출하지 않습니다.
상태와 관리¶
| 메서드·경로 | 노출 | 설명 |
|---|---|---|
GET /healthz |
8080, 공개 | 고정 ok, 의존성 확인 없음 |
/actuator/** |
배포 시 9090, 공개 인증 없음 | 네트워크 격리 전제 |
/swagger-ui/**, /v3/api-docs/** |
공통 permitAll | prod 프로파일에서는 기능 비활성 |