POST /items/upload - ARGOS Identity

폴더에 아이템을 등록합니다. 파일을 올리거나, 텍스트·JSON 콘텐츠를 직접 보내거나, 둘을 함께 보낼 수 있습니다.

엔드포인트

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

multipart/form-data로 보냅니다.

요청

경로 파라미터

파라미터	타입	설명
`folderId`	`string`	아이템을 넣을 폴더 ID (`fd_` 접두사)

폼 필드

필드	타입	필수	설명
`file`	file	조건부	업로드할 파일. `file`과 `content` 중 하나는 반드시 필요
`content`	string	조건부	텍스트 또는 JSON 문자열. `file`과 `content` 중 하나는 반드시 필요
`type`	string	조건부	`text` 또는 `json`. `content`만 보낼 때 필수, `file`이 있으면 무시됨
`name`	string		표시 이름(최대 255자). 생략하면 파일명 또는 자동 생성값
`metadata`	string (JSON)		사용자 정의 메타데이터를 JSON 문자열로

세 가지 등록 방식

파일만
텍스트·JSON만
파일 + 텍스트

file 타입 아이템이 생성됩니다.

curl -X POST "https://client-omni-api.argosidentity.com/v1/folders/fd_dvh8axwowi4v/items/upload" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@/path/to/business_registration.pdf" \
  -F "name=사업자등록증" \
  -F "metadata={\"doc_type\":\"business_registration\"}"

type에 따라 text 또는 json 타입 아이템이 생성됩니다.

curl -X POST "https://client-omni-api.argosidentity.com/v1/folders/fd_dvh8axwowi4v/items/upload" \
  -H "x-api-key: your-api-key-here" \
  -F "type=text" \
  -F "name=통장 사본 (계좌 확인서)" \
  -F "content=은행명: 가온은행 / 예금주: 주식회사 에이씨엠이 트레이딩"

텍스트가 파일에서 추출한 본문과 병합됩니다. file 타입 아이템이 생성됩니다.

curl -X POST "https://client-omni-api.argosidentity.com/v1/folders/fd_dvh8axwowi4v/items/upload" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@/path/to/business_registration.pdf" \
  -F "content=담당자 확인 완료. 원본 대조 이상 없음."

응답 (201 Created)

{
  "id": "item_ieoravdq3jp3",
  "folderId": "fd_dvh8axwowi4v",
  "type": "file",
  "name": "사업자등록증",
  "content": null,
  "contentType": "application/pdf",
  "sizeBytes": 245678,
  "url": null,
  "s3OriginalUrl": "https://omni-kb-documents.s3.us-east-1.amazonaws.com/.../original.pdf",
  "detected": {
    "contentType": "application/pdf",
    "extension": "pdf",
    "fileCategory": "document"
  },
  "metadata": { "doc_type": "business_registration" },
  "status": "PENDING",
  "processedAt": null,
  "rag": null,
  "createdAt": "2026-09-09T09:05:31.412Z"
}

응답 필드

필드	타입	설명
`id`	`string`	아이템 ID (`item_` 접두사)
`folderId`	`string`	소속 폴더 ID
`type`	`string`	`file` · `text` · `json`
`name`	`string`	표시 이름
`content`	`string \| object \| null`	`text`·`json` 타입의 본문. `file` 타입은 `null`
`contentType`	`string \| null`	MIME 타입
`sizeBytes`	`number \| null`	파일 크기(바이트)
`url`	`string \| null`	추출 텍스트의 S3 URL. 등록 응답에서는 항상 `null`이고 `status`가 `ACTIVE`가 된 뒤 조회하면 채워짐
`s3OriginalUrl`	`string \| null`	원본 파일 URL. 등록·수정 응답에만 포함되고 목록·상세 조회에는 없음
`detected`	`object \| null`	자동 감지 정보(`contentType`, `extension`, `fileCategory`). 파일 타입만
`metadata`	`object \| null`	사용자 정의 메타데이터
`status`	`string`	`PENDING` · `ACTIVE` · `FAILED`. 등록 직후는 항상 `PENDING`
`processedAt`	`string \| null`	처리 완료 시각. `PENDING`이면 `null`
`rag`	`string \| null`	추출·정제된 본문. 등록 응답에서는 항상 `null`이고 `ACTIVE`가 된 뒤 채워짐
`createdAt`	`string`	생성 시각

지원 파일 형식

분류	확장자	처리 방식
이미지	jpg, jpeg, png, gif, bmp, webp, tif, tiff	OCR(한국어·영어)
PDF	pdf	텍스트 레이어 우선, 없으면 OCR
텍스트 문서	txt, md, markdown, csv, html, htm, eml	직접 읽기
오피스 문서	docx, xlsx, pptx	텍스트 추출

목록에 없는 형식은 업로드 시점에 거부됩니다 — 400 OMNI_2105. HWP·HWPX, 구형 doc·xls·ppt, RAW, ICO, ZIP, 영상·음성 파일이 여기 해당합니다. 구형 오피스 문서는 docx·xlsx·pptx로 변환해 올리세요.

확장자와 파일의 실제 내용이 다르면 역시 OMNI_2105로 거부됩니다. PDF를 .md로 이름만 바꿔 올리는 식은 통과하지 않습니다.

제한

항목	값	초과 시
파일 하나 크기	10MB	`400` `OMNI_2101`
프로파일당 누적 업로드 용량	100MB	`409` `OMNI_2005`
폴더당 아이템 수	제한 없음	—

100MB는 프로파일 하나에 올린 파일 용량의 합계입니다. 폴더를 나눠도 합산됩니다. 텍스트로 넣은 아이템은 파일이 아니므로 이 한도에 거의 영향을 주지 않습니다.

등록 후 처리

등록된 아이템은 비동기로 텍스트 추출을 거쳐 PENDING → ACTIVE(또는 FAILED)로 바뀝니다. 분석은 프로파일의 모든 아이템이 ACTIVE일 때만 실행할 수 있습니다.

아이템 상태 조회를 1초 간격으로 폴링해 isRagReady가 true가 되는지 확인하세요. 60초 안에 ACTIVE가 되지 않으면 삭제 후 다시 등록하세요.

에러 코드

상태	코드	설명
400	`OMNI_2106`	`file`과 `content`가 둘 다 없음
400	`OMNI_2107`	`content`만 보내면서 `type`을 누락
400	`OMNI_2101`	파일이 10MB를 초과
400	`OMNI_2105`	지원하지 않는 파일 형식, 또는 확장자와 실제 내용 불일치
404	`OMNI_3009`	폴더를 찾을 수 없음
409	`OMNI_2005`	프로파일 누적 업로드 용량(100MB) 초과

공통 에러(401 인증 · 403 권한 · 500 서버 오류)는 API 개요를 참조하세요.

​엔드포인트

​요청

​경로 파라미터

​폼 필드

​세 가지 등록 방식

​응답 (201 Created)

​응답 필드

​지원 파일 형식

​제한

​등록 후 처리

​에러 코드

엔드포인트

요청

경로 파라미터

폼 필드

세 가지 등록 방식

응답 (201 Created)

응답 필드

지원 파일 형식

제한

등록 후 처리

에러 코드