Space Guide.

POST /v1/tour/course · Content-Type: application/json. 두 모드 모두 같은 API를 사용합니다. 필드별 전체 스키마는 API Docs ↗에서 확인하세요.

Modes

aiChatEnabled는 올림플래닛(XROO)이 제어할 예정인 설정이며, 이 화면에서는 직접 선택합니다. JSON boolean만 받으며 "true", 1, null은 허용하지 않습니다.

Request fields

Progress context

• current: {sceneId, position?}는 실제 현재 위치, history: [sceneId, …]는 방문 기록, themeId는 사용할 Theme ID입니다. 위치·기록은 전체 공간에 존재해야 합니다. 코스 생성의 Theme은 안내 범위 전체와 실제 출발 위치에서 공통으로 사용 가능해야 합니다. 정보 질문의 조회 범위는 그대로 유지합니다.
• 출발점이 허용된 미방문 안내 공간이면 그곳부터 안내합니다. 그렇지 않으면 출발점에서 직접 연결된 허용 미방문 공간부터 안내하며, 제외된 중간 공간을 자동 경유하지 않습니다. 안내하지 않는 출발점은 maxScenes에 세지 않습니다.
• 직접 코스 생성 시 current와 history는 함께 보내고, 현재 위치가 있으면 themeId도 필요합니다. Q&A 정보 질문은 current만으로 가능합니다. 진행 상태가 있는 Q&A에서 코스까지 생성하려면 세 필드가 모두 필요합니다.
• history가 비어 있지 않거나 activeCourse를 보내면 current가 필수입니다. current·history·themeId는 null 대신 생략하고, 방문 기록이 없음을 명시하려면 []를 보냅니다.
• previousCourse는 직전 제안, activeCourse는 실제 진행 중인 코스입니다. 둘 다 {themeId, scenes: [{sceneId, actions?}]} 형태이며 현재 공간·범위의 유효한 코스를 보내야 합니다. activeCourse.themeId는 함께 보낸 themeId와 같아야 합니다.

Response fields

‘이 제안을 다음 요청에서 참조’는 previousCourse만 설정합니다. 실제 승인·XR 재생·방문 기록 갱신은 XROO가 담당합니다. 이 화면은 Scene 순서와 DISPLAY_TEXT를 표시하며 전체 actions는 Response JSON에서 확인할 수 있습니다. course: null이면 이전 제안은 별도 표시로 유지됩니다.

RAG lifecycle

RAG가 활성화된 서버는 코스·Q&A의 성공 응답 후 spaceContext.id와 JSON 내용의 버전으로 저장 여부를 확인합니다. 같은 버전이 완전히 저장되어 있으면 재임베딩을 건너뛰고, 미적재·변경·부분 적재된 자료는 백그라운드에서 보완합니다. 기본 샘플에도 같은 규칙이 적용됩니다.

새 JSON의 첫 응답은 적재 완료를 기다리지 않습니다. 해당 버전의 적재가 끝난 뒤 후속 Q&A에서 검색할 수 있으며, 검색을 사용할 수 없을 때는 요청의 공간정보를 직접 조회하도록 안내합니다. 적재 실패는 이미 보낸 응답을 바꾸지 않고 다음 성공 요청 후 재시도합니다. 현재 API는 RAG 활성화·적재 완료·검색 성공 상태를 응답에 포함하지 않습니다.

Errors & diagnostics

‘연결 확인’은 GET /health/live로 API 프로세스 응답만 확인합니다. GET /health/ready는 모델 연결을 확인하지만 RAG 준비 상태는 검사하지 않습니다. 표시 시간은 브라우저가 응답 본문을 받을 때까지의 시간이며 백그라운드 적재 시간은 포함하지 않습니다. 이 화면은 최대 150초 동안 응답을 기다립니다. ‘대기 중단’ 후에도 서버 처리는 계속될 수 있습니다.