전역 규칙

API 사용을 위한 전역 규칙, 헤더, 오류 처리 및 모범 사례

필수 헤더 (인증이 필요한 엔드포인트)

모든 보호된 엔드포인트에는 Authorization 헤더가 필요합니다. 다음 헤더가 필요합니다:

헤더	값	필수 여부
`Authorization`	`Bearer <token>`	필수 — `/api/v1/auths/signin` 및 `/api/v1/auths/signup` 을 제외한 모든 엔드포인트
`Content-Type`	`application/json`	JSON 본문 요청에 필수
`Content-Type`	(multipart 자동 설정)	파일 업로드 요청에 필수 — 수동으로 설정하지 마세요, 브라우저가 자동으로 설정합니다

오류 응답 형식

백엔드의 모든 오류는 다음 구조를 따릅니다:

json

{
"detail": "사람이 읽을 수 있는 오류 메시지"
}

일반 HTTP 상태 코드

상태 코드	의미
`400`	잘못된 요청 — 필드 누락 또는 유효하지 않음
`401`	Authorization 헤더 누락 또는 토큰 유효하지 않음/만료됨
`403`	금지됨 — 역할 또는 권한 부족
`404`	리소스를 찾을 수 없음
`500`	내부 서버 오류

성공 응답 형식

대부분의 엔드포인트는 리소스 객체를 JSON으로 반환합니다. 삭제 작업은 일반적으로 다음을 반환합니다:

json

true

또는 삭제된 객체를 반환합니다. 각 엔드포인트별 구체적인 응답 형태를 확인하세요.

SSE (Server-Sent Events) — 스트리밍 응답

채팅 완성 및 일부 작업 엔드포인트는 text/event-stream 으로 응답을 스트리밍합니다. 각 청크는 표준 SSE 프레임입니다:

text

data: {"id":"...","choices":[{"delta":{"content":"hello"}}]}


data: [DONE]

중요: 인증이 필요한 스트림에는 브라우저 EventSource API를 사용하지 마세요 — EventSource 는 커스텀 헤더를 설정할 수 없습니다. ReadableStream 리더와 함께 fetch 를 사용하세요.

자세한 스트리밍 예제는 SSE 소비 가이드를 참조하세요.

WebSocket / Socket.IO — 실시간 상태 이벤트

백엔드는 Socket.IO(일반 WebSocket이 아님)를 통해 실시간 상태 이벤트를 전송합니다. 이 이벤트는 RAG 검색 및 에이전틱 툴 호출 중 진행 상황 업데이트를 전송하는 데 사용됩니다.

연결

javascript

import { io } from 'socket.io-client';

const socket = io('https://<backend-host>', {
auth: { token: '<jwt_or_api_key>' },
transports: ['websocket'],
});

서버가 전송하는 주요 이벤트

이벤트	페이로드	설명
`status`	`{ action, description, done }`	검색 / 툴 실행 중 단계별 진행 상황
`source`	소스 객체 배열	응답에 연결된 검색된 지식 청크
`follow-up`	문자열 배열	응답 후 후속 질문 제안

이벤트 수신

이벤트를 놓치지 않도록 채팅 요청을 보내기 전에 수신을 설정하세요:

javascript

socket.on('status', (data) => console.log(data.description));
socket.on('source', (sources) => renderSources(sources));
socket.on('follow-up', (questions) => renderFollowUps(questions));

중요: Socket.IO 연결 시 사용하는 session_id 는 채팅 완성 요청 본문의 session_id 필드와 일치해야 합니다. 서버는 이를 통해 올바른 클라이언트로 이벤트를 라우팅합니다.