> ## 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

> Upload a file, text, or JSON data to a folder.

## Endpoint

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

## Upload Methods

<Tabs>
  <Tab title="File Only">
    Upload a file. Creates a `file` type item.

    ```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="Text/JSON Only">
    Upload text or JSON content. Creates a `text` or `json` type item.

    ```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 + Text (Merged)">
    Upload a file with additional text content. The text is merged with the file. Creates a `file` type item.

    ```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>

## Request Parameters (Form Data)

<ResponseField name="file" type="file">
  File to upload. Either `file` or `content` must be provided.
</ResponseField>

<ResponseField name="type" type="string">
  Item type: `file`, `text`, or `json`. Required when only `content` is provided. Ignored when `file` is provided.
</ResponseField>

<ResponseField name="name" type="string">
  Display name (defaults to filename or auto-generated)
</ResponseField>

<ResponseField name="content" type="string">
  Text or JSON content. Either `file` or `content` must be provided.
</ResponseField>

<ResponseField name="metadata" type="string (JSON)">
  Custom metadata as a JSON string
</ResponseField>

## Response (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">
  Original file URL. Only included in upload/update responses, not in list or detail queries.
</ResponseField>

<ResponseField name="detected" type="object | null">
  Auto-detected file info: `contentType`, `extension`, `fileCategory`
</ResponseField>

<ResponseField name="rag" type="string | null">
  OCR-extracted text. `null` on creation, populated after processing completes.
</ResponseField>

## File Constraints

| Constraint           | Value |
| -------------------- | ----- |
| Max file size        | 10 MB |
| Max items per folder | 5     |

### Supported File Formats

| File Type        | Extensions                      | Processing                 |
| ---------------- | ------------------------------- | -------------------------- |
| Images           | jpg, jpeg, png, bmp, tiff, webp | OCR (auto text extraction) |
| PDF              | pdf                             | OCR (auto text extraction) |
| Text documents   | txt, md, html, htm, csv         | Direct read                |
| Office documents | doc, docx, xls, xlsx            | Auto text extraction       |

## Processing

After upload, items are automatically processed:

* **Images & PDFs**: OCR extraction (Korean & English)
* **Office documents**: Text and data extraction
* **Status flow**: `PENDING` → `ACTIVE` (or `FAILED`)

<Tip>
  Poll `GET /v1/profiles/{profileId}/items/status` at **1-second intervals** (max 60 seconds) to check when all items are ready for analysis.
</Tip>

## Error Codes

| Status | Code                       | Description                                        |
| ------ | -------------------------- | -------------------------------------------------- |
| 400    | `FILE_OR_CONTENT_REQUIRED` | Either `file` or `content` must be provided        |
| 400    | `TYPE_REQUIRED`            | `type` is required when only `content` is provided |
| 404    | `FOLDER_NOT_FOUND`         | Folder not found                                   |
| 409    | `ITEM_LIMIT_EXCEEDED`      | Max 5 items per folder exceeded                    |
| 413    | `FILE_TOO_LARGE`           | File exceeds 10 MB limit                           |
| 415    | `UNSUPPORTED_FILE_TYPE`    | File format not supported                          |