POST /items/upload

Endpoint

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

Upload Methods

File Only
Text/JSON Only
File + Text (Merged)

Upload a file. Creates a file type item.

curl -X POST "https://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\"}"

Upload text or JSON content. Creates a text or json type item.

curl -X POST "https://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\"}"

Upload a file with additional text content. The text is merged with the file. Creates a file type item.

curl -X POST "https://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}"

Request Parameters (Form Data)

file

File to upload. Either file or content must be provided.

string

Item type: file, text, or json. Required when only content is provided. Ignored when file is provided.

string

Display name (defaults to filename or auto-generated)

string

Text or JSON content. Either file or content must be provided.

string (JSON)

Custom metadata as a JSON string

Response (201 Created)

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

string | null

Original file URL. Only included in upload/update responses, not in list or detail queries.

object | null

Auto-detected file info: contentType, extension, fileCategory

string | null

OCR-extracted text. null on creation, populated after processing completes.

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)

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

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

Overview

API Reference

Endpoint

Upload Methods

Request Parameters (Form Data)

Response (201 Created)

File Constraints

Supported File Formats

Processing

Error Codes

​Endpoint

​Upload Methods

​Request Parameters (Form Data)

​Response (201 Created)

​File Constraints

​Supported File Formats

​Processing

​Error Codes

Endpoint

Upload Methods

Request Parameters (Form Data)

Response (201 Created)

File Constraints

Supported File Formats

Processing

Error Codes