POST /items/upload

엔드포인트

POST /v1/folders/{folderId}/items/upload

업로드 방법

파일만
텍스트/JSON만
파일 + 텍스트 (병합)

파일을 업로드합니다. file 타입 아이템이 생성됩니다.

curl -X POST "https://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 "https://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 "https://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}"

요청 파라미터 (Form Data)

file

업로드할 파일. file 또는 content 중 하나는 반드시 제공해야 합니다.

string

아이템 타입: file, text 또는 json. content만 제공할 때 필수입니다. file이 제공되면 무시됩니다.

string

표시 이름 (기본값: 파일명 또는 자동 생성)

string

텍스트 또는 JSON 콘텐츠. file 또는 content 중 하나는 반드시 제공해야 합니다.

string (JSON)

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"
}

string | null

원본 파일 URL. 업로드/업데이트 응답에만 포함되며, 목록 또는 상세 조회에는 포함되지 않습니다.

object | null

자동 감지된 파일 정보: contentType, extension, fileCategory

string | null

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`	지원하지 않는 파일 형식

개요

API 참조

엔드포인트

업로드 방법

요청 파라미터 (Form Data)

응답 (201 Created)

파일 제약사항

지원 파일 형식

처리

에러 코드

​엔드포인트

​업로드 방법

​요청 파라미터 (Form Data)

​응답 (201 Created)

​파일 제약사항

​지원 파일 형식

​처리

​에러 코드

엔드포인트

업로드 방법

요청 파라미터 (Form Data)

응답 (201 Created)

파일 제약사항

지원 파일 형식

처리

에러 코드