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

> Suba un archivo, texto o datos JSON a una carpeta.

## Endpoint

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

## Métodos de carga

<Tabs>
  <Tab title="Solo archivo">
    Suba un archivo. Crea un item de tipo `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="Solo texto/JSON">
    Suba contenido de texto o JSON. Crea un item de tipo `text` o `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="Archivo + texto (combinado)">
    Suba un archivo con contenido de texto adicional. El texto se combina con el archivo. Crea un item de tipo `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>

## Parámetros de solicitud (Form Data)

<ResponseField name="file" type="file">
  Archivo a subir. Se debe proporcionar `file` o `content`.
</ResponseField>

<ResponseField name="type" type="string">
  Tipo de item: `file`, `text` o `json`. Requerido cuando solo se proporciona `content`. Se ignora cuando se proporciona `file`.
</ResponseField>

<ResponseField name="name" type="string">
  Nombre visible (por defecto usa el nombre del archivo o se genera automáticamente)
</ResponseField>

<ResponseField name="content" type="string">
  Contenido de texto o JSON. Se debe proporcionar `file` o `content`.
</ResponseField>

<ResponseField name="metadata" type="string (JSON)">
  Metadata personalizado como cadena JSON
</ResponseField>

## Respuesta (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 del archivo original. Solo se incluye en las respuestas de carga/actualización, no en consultas de lista o detalle.
</ResponseField>

<ResponseField name="detected" type="object | null">
  Información del archivo detectada automáticamente: `contentType`, `extension`, `fileCategory`
</ResponseField>

<ResponseField name="rag" type="string | null">
  Texto extraído por OCR. `null` en la creación; se completa después del procesamiento.
</ResponseField>

## Restricciones de archivo

| Restricción                | Valor |
| -------------------------- | ----- |
| Tamaño máximo de archivo   | 10 MB |
| Máximo de items por folder | 5     |

### Formatos de archivo compatibles

| Tipo de archivo       | Extensiones                     | Procesamiento                        |
| --------------------- | ------------------------------- | ------------------------------------ |
| Imágenes              | jpg, jpeg, png, bmp, tiff, webp | OCR (extracción automática de texto) |
| PDF                   | pdf                             | OCR (extracción automática de texto) |
| Documentos de texto   | txt, md, html, htm, csv         | Lectura directa                      |
| Documentos de oficina | doc, docx, xls, xlsx            | Extracción automática de texto       |

## Procesamiento

Después de la carga, los items se procesan automáticamente:

* **Imágenes y PDFs**: Extracción OCR (coreano e inglés)
* **Documentos de oficina**: Extracción de texto y datos
* **Flujo de estado**: `PENDING` → `ACTIVE` (o `FAILED`)

<Tip>
  Haga polling de `GET /v1/profiles/{profileId}/items/status` cada **1 segundo** (máx. 60 segundos) para verificar cuándo todos los items están listos para el análisis.
</Tip>

## Códigos de error

| Status | Code                       | Descripción                                              |
| ------ | -------------------------- | -------------------------------------------------------- |
| 400    | `FILE_OR_CONTENT_REQUIRED` | Se debe proporcionar `file` o `content`                  |
| 400    | `TYPE_REQUIRED`            | `type` es requerido cuando solo se proporciona `content` |
| 404    | `FOLDER_NOT_FOUND`         | Folder no encontrado                                     |
| 409    | `ITEM_LIMIT_EXCEEDED`      | Se superó el máximo de 5 items por folder                |
| 413    | `FILE_TOO_LARGE`           | El archivo supera el límite de 10 MB                     |
| 415    | `UNSUPPORTED_FILE_TYPE`    | Formato de archivo no compatible                         |