엔드포인트
POST /v1/folders/{folderId}/items/upload
업로드 방법
파일만
텍스트/JSON만
파일 + 텍스트 (병합)
파일을 업로드합니다. file 타입 아이템이 생성됩니다.curl -X POST "http://client-omni-api.argosidentity.com/v1/folders/{folderId}/items/upload" \
-H "x-api-key: your-api-key-here" \
-F "file=@/path/to/business_registration.pdf" \
-F "metadata={\"documentType\":\"business_registration\"}"
텍스트 또는 JSON 콘텐츠를 업로드합니다. text 또는 json 타입 아이템이 생성됩니다.curl -X POST "http://client-omni-api.argosidentity.com/v1/folders/{folderId}/items/upload" \
-H "x-api-key: your-api-key-here" \
-F "type=text" \
-F "name=verification_notes" \
-F "content=Document appears valid. No signs of tampering." \
-F "metadata={\"author\":\"compliance_officer\"}"
추가 텍스트 콘텐츠와 함께 파일을 업로드합니다. 텍스트는 파일과 병합됩니다. file 타입 아이템이 생성됩니다.curl -X POST "http://client-omni-api.argosidentity.com/v1/folders/{folderId}/items/upload" \
-H "x-api-key: your-api-key-here" \
-F "file=@/path/to/contract.pdf" \
-F "content=Additional notes: This contract has been verified." \
-F "metadata={\"verified\":true}"
업로드할 파일. file 또는 content 중 하나는 반드시 제공해야 합니다.
아이템 타입: file, text 또는 json. content만 제공할 때 필수입니다. file이 제공되면 무시됩니다.
표시 이름 (기본값: 파일명 또는 자동 생성)
텍스트 또는 JSON 콘텐츠. file 또는 content 중 하나는 반드시 제공해야 합니다.
JSON 문자열 형태의 사용자 정의 메타데이터
응답 (201 Created)
{
"id": "item_abc123",
"folderId": "fld_default001",
"type": "file",
"name": "business_registration.pdf",
"content": null,
"contentType": "application/pdf",
"sizeBytes": 245678,
"url": "https://omni-kb-documents.s3.us-east-1.amazonaws.com/.../extracted.txt",
"s3OriginalUrl": "https://omni-kb-documents.s3.us-east-1.amazonaws.com/.../original.pdf",
"detected": {
"contentType": "application/pdf",
"extension": "pdf",
"fileCategory": "document"
},
"metadata": {
"documentType": "business_registration"
},
"status": "PENDING",
"processedAt": null,
"rag": null,
"createdAt": "2026-03-15T10:10:00Z"
}
원본 파일 URL. 업로드/업데이트 응답에만 포함되며, 목록 또는 상세 조회에는 포함되지 않습니다.
자동 감지된 파일 정보: contentType, extension, fileCategory
OCR로 추출된 텍스트. 생성 시 null이며, 처리 완료 후 채워집니다.
파일 제약사항
| 제약사항 | 값 |
|---|
| 최대 파일 크기 | 10 MB |
| 폴더당 최대 아이템 | 5 |
지원 파일 형식
| 파일 타입 | 확장자 | 처리 방식 |
|---|
| 이미지 | jpg, jpeg, png, bmp, tiff, webp | OCR (자동 텍스트 추출) |
| PDF | pdf | OCR (자동 텍스트 추출) |
| 텍스트 문서 | txt, md, html, htm, csv | 직접 읽기 |
| 오피스 문서 | doc, docx, xls, xlsx | 자동 텍스트 추출 |
- 이미지 및 PDF: OCR 추출 (한국어 & 영어)
- 오피스 문서: 텍스트 및 데이터 추출
- 상태 흐름:
PENDING → ACTIVE (또는 FAILED)
GET /v1/profiles/{profileId}/items/status를 1초 간격으로 폴링(최대 60초)하여 모든 아이템이 분석 준비 완료되었는지 확인하세요.
에러 코드
| 상태 | 코드 | 설명 |
|---|
| 400 | FILE_OR_CONTENT_REQUIRED | file 또는 content 중 하나는 반드시 제공해야 합니다 |
| 400 | TYPE_REQUIRED | content만 제공할 때 type은 필수입니다 |
| 404 | FOLDER_NOT_FOUND | 폴더를 찾을 수 없음 |
| 409 | ITEM_LIMIT_EXCEEDED | 폴더당 최대 5개 아이템 초과 |
| 413 | FILE_TOO_LARGE | 파일이 10 MB 제한을 초과함 |
| 415 | UNSUPPORTED_FILE_TYPE | 지원하지 않는 파일 형식 |
