> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /items/upload

> 폴더에 파일, 텍스트 또는 JSON 데이터를 업로드합니다.

## 엔드포인트

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

## 업로드 방법

<Tabs>
  <Tab title="파일만">
    파일을 업로드합니다. `file` 타입 아이템이 생성됩니다.

    ```bash theme={null}
    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\"}"
    ```
  </Tab>

  <Tab title="텍스트/JSON만">
    텍스트 또는 JSON 콘텐츠를 업로드합니다. `text` 또는 `json` 타입 아이템이 생성됩니다.

    ```bash theme={null}
    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\"}"
    ```
  </Tab>

  <Tab title="파일 + 텍스트 (병합)">
    추가 텍스트 콘텐츠와 함께 파일을 업로드합니다. 텍스트는 파일과 병합됩니다. `file` 타입 아이템이 생성됩니다.

    ```bash theme={null}
    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}"
    ```
  </Tab>
</Tabs>

## 요청 파라미터 (Form Data)

<ResponseField name="file" type="file">
  업로드할 파일. `file` 또는 `content` 중 하나는 반드시 제공해야 합니다.
</ResponseField>

<ResponseField name="type" type="string">
  아이템 타입: `file`, `text` 또는 `json`. `content`만 제공할 때 필수입니다. `file`이 제공되면 무시됩니다.
</ResponseField>

<ResponseField name="name" type="string">
  표시 이름 (기본값: 파일명 또는 자동 생성)
</ResponseField>

<ResponseField name="content" type="string">
  텍스트 또는 JSON 콘텐츠. `file` 또는 `content` 중 하나는 반드시 제공해야 합니다.
</ResponseField>

<ResponseField name="metadata" type="string (JSON)">
  JSON 문자열 형태의 사용자 정의 메타데이터
</ResponseField>

## 응답 (201 Created)

```json theme={null}
{
  "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"
}
```

<ResponseField name="s3OriginalUrl" type="string | null">
  원본 파일 URL. 업로드/업데이트 응답에만 포함되며, 목록 또는 상세 조회에는 포함되지 않습니다.
</ResponseField>

<ResponseField name="detected" type="object | null">
  자동 감지된 파일 정보: `contentType`, `extension`, `fileCategory`
</ResponseField>

<ResponseField name="rag" type="string | null">
  OCR로 추출된 텍스트. 생성 시 `null`이며, 처리 완료 후 채워집니다.
</ResponseField>

## 파일 제약사항

| 제약사항       | 값     |
| ---------- | ----- |
| 최대 파일 크기   | 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`)

<Tip>
  `GET /v1/profiles/{profileId}/items/status`를 **1초 간격**으로 폴링(최대 60초)하여 모든 아이템이 분석 준비 완료되었는지 확인하세요.
</Tip>

## 에러 코드

| 상태  | 코드                         | 설명                                     |
| --- | -------------------------- | -------------------------------------- |
| 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`    | 지원하지 않는 파일 형식                          |