POST /items/upload

Adds an item to a folder. You can upload a file, send text or JSON content directly, or send both together.

Endpoint

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

Send it as multipart/form-data.

Request

Path parameters

Parameter	Type	Description
`folderId`	`string`	ID of the folder to add the item to (`fd_` prefix)

Form fields

Field	Type	Required	Description
`file`	file	Conditional	The file to upload. One of `file` or `content` is required
`content`	string	Conditional	Text or a JSON string. One of `file` or `content` is required
`type`	string	Conditional	`text` or `json`. Required when you send only `content`, ignored when `file` is present
`name`	string		Display name (max 255 characters). Defaults to the file name or a generated value
`metadata`	string (JSON)		Your own metadata, as a JSON string

Three ways to add an item

File only
Text or JSON only
File and text

Creates a file type item.

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\"}"

Creates a text or json type item, depending on 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"

The text is merged with the body extracted from the file. Creates a file type item.

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."

Response (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"
}

Response fields

Field	Type	Description
`id`	`string`	Item ID (`item_` prefix)
`folderId`	`string`	ID of the folder it belongs to
`type`	`string`	`file` · `text` · `json`
`name`	`string`	Display name
`content`	`string \| object \| null`	Body of a `text` or `json` item. `null` for the `file` type
`contentType`	`string \| null`	MIME type
`sizeBytes`	`number \| null`	File size in bytes
`url`	`string \| null`	S3 URL of the extracted text. Always `null` in the add response; it is filled in once `status` becomes `ACTIVE` and you read the item
`s3OriginalUrl`	`string \| null`	Original file URL. Present only in the add and update responses, never in a list or read response
`detected`	`object \| null`	Auto-detected info (`contentType`, `extension`, `fileCategory`). File type only
`metadata`	`object \| null`	Your own metadata
`status`	`string`	`PENDING` · `ACTIVE` · `FAILED`. Always `PENDING` right after adding
`processedAt`	`string \| null`	Time processing finished. `null` while `PENDING`
`rag`	`string \| null`	The extracted, cleaned body. Always `null` in the add response; filled in once the item is `ACTIVE`
`createdAt`	`string`	Creation time

Supported file formats

Category	Extensions	How it is processed
Images	jpg, jpeg, png, gif, bmp, webp, tif, tiff	OCR (Korean and English)
PDF	pdf	The text layer first, OCR when there is none
Text documents	txt, md, markdown, csv, html, htm, eml	Read directly
Office documents	docx, xlsx, pptx	Text extraction

A format missing from this list is rejected at upload — 400 OMNI_2105. That covers HWP and HWPX, the legacy doc, xls, and ppt formats, RAW, ICO, ZIP, and video and audio files. Convert legacy Office documents to docx, xlsx, or pptx before uploading.

A file whose extension disagrees with its actual content is rejected the same way, with OMNI_2105. Renaming a PDF to .md does not get it through.

Limits

Item	Value	When exceeded
Size of a single file	10MB	`400` `OMNI_2101`
Total upload size per profile	100MB	`409` `OMNI_2005`
Items per folder	No limit	—

The 100MB is the combined size of the files uploaded to one profile. Splitting them across folders does not change the total. Items added as text are not files and barely count toward it.

What happens after adding

An added item goes through asynchronous text extraction and moves from PENDING to ACTIVE (or FAILED). An analysis can only run once every item in the profile is ACTIVE.

Poll item status once per second and watch for isRagReady to turn true. If an item is not ACTIVE within 60 seconds, delete it and add it again.

Error codes

Status	Code	Description
400	`OMNI_2106`	Neither `file` nor `content` was sent
400	`OMNI_2107`	`content` was sent without `type`
400	`OMNI_2101`	The file is larger than 10MB
400	`OMNI_2105`	Unsupported file format, or the extension disagrees with the actual content
404	`OMNI_3009`	Folder not found
409	`OMNI_2005`	Over the 100MB total upload size for the profile

Common errors (401 authentication · 403 permission · 500 server) are listed in the API overview.

Overview

API Reference

Endpoint

Request

Path parameters

Form fields

Three ways to add an item

Response (201 Created)

Response fields

Supported file formats

Limits

What happens after adding

Error codes

​Endpoint

​Request

​Path parameters

​Form fields

​Three ways to add an item

​Response (201 Created)

​Response fields

​Supported file formats

​Limits

​What happens after adding

​Error codes

Endpoint

Request

Path parameters

Form fields

Three ways to add an item

Response (201 Created)

Response fields

Supported file formats

Limits

What happens after adding

Error codes