ID 지정하여 파일 추가

VPC 환경에서 이용 가능합니다.

파일 ID를 지정하여 색인 시스템에 파일을 업로드합니다. 시스템이 자동 생성하는 ID 대신 사용자가 원하는 ID로 문서를 생성할 수 있습니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/api/v1/svc/{serviceId}/file/{fileId}

요청 헤더

RAG API 에서 공통으로 사용하는 헤더에 대한 정보는 RAG 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`serviceId`	String	Required	서비스의 고유 식별자
`fileId`	String	Required	파일의 고유 식별자 영문자, 숫자, 특수문자 '-', '_' 허용

요청 쿼리 파라미터

파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`background`	Boolean	Optional	텍스트 추출을 백그라운드에서 처리할지 여부 `true` \| `false` (기본값) `true`: 파일을 업로드하면 즉시 응답을 반환하고, 텍스트 추출은 백그라운드에서 비동기 처리 `false`: 텍스트 추출까지 마친 후 응답 반환 (동기 처리)

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`file`	파일	Required	업로드할 파일 (최대 1개) 지원 형식 이미지: JPG, PNG, TIFF 문서: PDF, PPTX, DOCX, HWP, HWPX, TXT 데이터 파일: MD, JSON, XML 파일 크기: 최대 100MB
`document`	문서	Optional	업로드할 파일의 메타데이터를 포함한 문서 문서추가/교체 와 동일한 형식의 object를 json 문자열로 전달 document.body는 파일에서 추출한 문자열로 대체 참고: 요청 바디

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://kr-pub-gateway.rag.naverncp.com/api/v1/svc/{serviceId}/file/12345?background=true' \
--header 'Authorization: Bearer {apiKey}' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"filePath"' \
--form 'document={"id":"string","orgid":"string","title":"string","file_name":"string","body":"","url":"string","created_at":"2025-07-25T06:43:53.863Z","extra":{"additionalProp1":{}}}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`status`	Object	-	API 처리 결과
`status.code`	Integer	-	API 응답 상태 코드
`status.message`	String	-	API 응답 상태 메시지
`result`	Object	-	파일 처리 결과
`result.inserted`	Array	-	생성된 파일 ID
`result.deleted`	Array	-	삭제된 파일 ID (항상 `null`)
`result.updated`	Array	-	수정된 파일 ID (항상 `null`)

응답 상태 코드

RAG API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 RAG 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

{
    "status": {
        "code": 200,
        "message": ""
    },
    "result": {
        "inserted": [
            "12345"
        ],
        "deleted": null,
        "updated": null
    }
}