Skip to main content

​
Endpoint

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

​
Upload Methods

Upload a file. Creates a file type item.
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\"}"

​
Request Parameters (Form Data)

​
file
file
File to upload. Either file or content must be provided.
​
type
string
Item type: file, text, or json. Required when only content is provided. Ignored when file is provided.
​
name
string
Display name (defaults to filename or auto-generated)
​
content
string
Text or JSON content. Either file or content must be provided.
​
metadata
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"
}
​
s3OriginalUrl
string | null
Original file URL. Only included in upload/update responses, not in list or detail queries.
​
detected
object | null
Auto-detected file info: contentType, extension, fileCategory
​
rag
string | null
OCR-extracted text. null on creation, populated after processing completes.

​
File Constraints

ConstraintValue
Max file size10 MB
Max items per folder5

​
Supported File Formats

File TypeExtensionsProcessing
Imagesjpg, jpeg, png, bmp, tiff, webpOCR (auto text extraction)
PDFpdfOCR (auto text extraction)
Text documentstxt, md, html, htm, csvDirect read
Office documentsdoc, docx, xls, xlsxAuto 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

StatusCodeDescription
400FILE_OR_CONTENT_REQUIREDEither file or content must be provided
400TYPE_REQUIREDtype is required when only content is provided
404FOLDER_NOT_FOUNDFolder not found
409ITEM_LIMIT_EXCEEDEDMax 5 items per folder exceeded
413FILE_TOO_LARGEFile exceeds 10 MB limit
415UNSUPPORTED_FILE_TYPEFile format not supported