POST /items/upload

Añade un ítem a una carpeta. Puede subir un archivo, enviar contenido de texto o JSON directamente, o enviar ambos a la vez.

Endpoint

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

Se envía como multipart/form-data.

Petición

Parámetros de ruta

Parámetro	Tipo	Descripción
`folderId`	`string`	ID de la carpeta a la que añadir el ítem (prefijo `fd_`)

Campos del formulario

Campo	Tipo	Obligatorio	Descripción
`file`	file	Condicional	El archivo a subir. Se requiere `file` o `content`
`content`	string	Condicional	Texto o una cadena JSON. Se requiere `file` o `content`
`type`	string	Condicional	`text` o `json`. Obligatorio cuando envía solo `content`; se ignora si hay `file`
`name`	string		Nombre para mostrar (máx. 255 caracteres). Por defecto, el nombre del archivo o un valor generado
`metadata`	string (JSON)		Sus propios metadatos, como cadena JSON

Tres formas de añadir un ítem

Solo archivo
Solo texto o JSON
Archivo y texto

Crea un ítem de tipo file.

curl -X POST "https://client-omni-api.argosidentity.com/v1/folders/fd_9pq2mklt83bx/items/upload" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@/path/to/certificate_of_good_standing.pdf" \
  -F "name=certificate of good standing" \
  -F "metadata={\"doc_type\":\"certificate_of_good_standing\"}"

Crea un ítem de tipo text o json, según type.

curl -X POST "https://client-omni-api.argosidentity.com/v1/folders/fd_9pq2mklt83bx/items/upload" \
  -H "x-api-key: your-api-key-here" \
  -F "type=text" \
  -F "name=Bank verification" \
  -F "content=Bank: First State Bank / Account holder: ACME TRADING LLC"

El texto se fusiona con el cuerpo extraído del archivo. Crea un ítem de tipo file.

curl -X POST "https://client-omni-api.argosidentity.com/v1/folders/fd_9pq2mklt83bx/items/upload" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@/path/to/certificate_of_good_standing.pdf" \
  -F "content=Reviewer checked this against the original. No discrepancies."

Respuesta (201 Created)

{
  "id": "item_axfkh2noof85",
  "folderId": "fd_9pq2mklt83bx",
  "type": "file",
  "name": "certificate of good standing",
  "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": "certificate_of_good_standing" },
  "status": "PENDING",
  "processedAt": null,
  "rag": null,
  "createdAt": "2026-09-10T05:35:31.412Z"
}

Campos de la respuesta

Campo	Tipo	Descripción
`id`	`string`	ID del ítem (prefijo `item_`)
`folderId`	`string`	ID de la carpeta a la que pertenece
`type`	`string`	`file` · `text` · `json`
`name`	`string`	Nombre para mostrar
`content`	`string \| object \| null`	Cuerpo de un ítem `text` o `json`. `null` para el tipo `file`
`contentType`	`string \| null`	Tipo MIME
`sizeBytes`	`number \| null`	Tamaño del archivo en bytes
`url`	`string \| null`	URL en S3 del texto extraído. Siempre `null` en la respuesta de creación; se rellena cuando `status` pasa a `ACTIVE` y se lee el ítem
`s3OriginalUrl`	`string \| null`	URL del archivo original. Presente solo en las respuestas de creación y actualización, nunca en una de lista o lectura
`detected`	`object \| null`	Datos detectados automáticamente (`contentType`, `extension`, `fileCategory`). Solo para el tipo archivo
`metadata`	`object \| null`	Metadatos propios
`status`	`string`	`PENDING` · `ACTIVE` · `FAILED`. Siempre `PENDING` justo después de añadirlo
`processedAt`	`string \| null`	Fin del procesamiento. `null` mientras está `PENDING`
`rag`	`string \| null`	El cuerpo extraído y depurado. Siempre `null` en la respuesta de creación; se rellena cuando el ítem está `ACTIVE`
`createdAt`	`string`	Fecha de creación

Formatos de archivo admitidos

Categoría	Extensiones	Cómo se procesa
Imágenes	jpg, jpeg, png, gif, bmp, webp, tif, tiff	OCR (coreano e inglés)
PDF	pdf	Primero la capa de texto; OCR cuando no la hay
Documentos de texto	txt, md, markdown, csv, html, htm, eml	Lectura directa
Documentos de ofimática	docx, xlsx, pptx	Extracción de texto

Un formato que no esté en esta lista se rechaza en el momento de la subida — 400 OMNI_2105. Eso incluye HWP y HWPX, los formatos antiguos doc, xls y ppt, RAW, ICO, ZIP y los archivos de vídeo y audio. Convierta los documentos de ofimática antiguos a docx, xlsx o pptx antes de subirlos.

Un archivo cuya extensión no concuerda con su contenido real se rechaza igual, con OMNI_2105. Renombrar un PDF a .md no sirve para colarlo.

Límites

Elemento	Valor	Al superarlo
Tamaño de un archivo	10MB	`400` `OMNI_2101`
Tamaño total subido por perfil	100MB	`409` `OMNI_2005`
Ítems por carpeta	Sin límite	—

Los 100MB son el tamaño combinado de los archivos subidos a un perfil. Repartirlos entre carpetas no cambia el total. Los ítems añadidos como texto no son archivos y apenas cuentan.

Qué ocurre después de añadirlo

Un ítem añadido pasa por una extracción de texto asíncrona y avanza de PENDING a ACTIVE (o FAILED). Un análisis solo puede ejecutarse cuando todos los ítems del perfil están ACTIVE.

Sondee el estado de los ítems una vez por segundo y espere a que isRagReady pase a true. Si un ítem no está ACTIVE en 60 segundos, elimínelo y vuelva a añadirlo.

Códigos de error

Estado	Código	Descripción
400	`OMNI_2106`	No se envió ni `file` ni `content`
400	`OMNI_2107`	Se envió `content` sin `type`
400	`OMNI_2101`	El archivo supera los 10MB
400	`OMNI_2105`	Formato no admitido, o la extensión no concuerda con el contenido real
404	`OMNI_3009`	Carpeta no encontrada
409	`OMNI_2005`	Superado el tamaño total subido por perfil (100MB)

Los errores comunes (401 autenticación · 403 permisos · 500 servidor) están en la descripción general de la API.

Descripción General

Referencia API

Endpoint

Petición

Parámetros de ruta

Campos del formulario

Tres formas de añadir un ítem

Respuesta (201 Created)

Campos de la respuesta

Formatos de archivo admitidos

Límites

Qué ocurre después de añadirlo

Códigos de error

​Endpoint

​Petición

​Parámetros de ruta

​Campos del formulario

​Tres formas de añadir un ítem

​Respuesta (201 Created)

​Campos de la respuesta

​Formatos de archivo admitidos

​Límites

​Qué ocurre después de añadirlo

​Códigos de error

Endpoint

Petición

Parámetros de ruta

Campos del formulario

Tres formas de añadir un ítem

Respuesta (201 Created)

Campos de la respuesta

Formatos de archivo admitidos

Límites

Qué ocurre después de añadirlo

Códigos de error