Knowledge base uploads

Upload datasheets, manuals, certificates, policies, and price lists to the knowledge base. Agents and product enrichment search indexed documents for evidence, the same as files uploaded on the workspace Documents page.

Authentication

Endpoint	Required scope
`POST /api/v1/documents`	`documents:write`
`GET /api/v1/documents/{documentId}`	`documents:read`

Upload a document

Send the file as multipart/form-data in a part named file:

curl -sS -X POST "https://omnicommerce.sg/api/v1/documents" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -F "file=@./lamp-datasheet.pdf" \
  -F "documentType=datasheet"

Field	Description
`file`	Required. PDF, Word (`.docx`), and PowerPoint (`.pptx`) up to 20 MB, Excel (`.xlsx`/`.xlsm`) up to 10 MB, images up to 8 MB, CSV and Markdown up to 2 MB.
`documentType`	`datasheet`, `invoice`, `packing_list`, `compliance_certificate`, `test_report`, `sds`, `manual`, `warranty`, `authorization_letter`, `shipping_doc`, `regulation`, `policy`, `bank_statement`, or `other` (default).
`productId`	Attach the document to one product instead of the whole organization.
`fileName`	File name to store. Defaults to the uploaded file’s name.

The response is 202:

{
  "ok": true,
  "status": "accepted",
  "data": {
    "document": {
      "id": "7d1f…",
      "fileName": "lamp-datasheet.pdf",
      "documentType": "datasheet",
      "status": "pending",
      "indexedChunkCount": null
    },
    "queued": true
  }
}

bank_statement documents are stored but never shown to AI.

Wait for indexing

PDFs, Word, PowerPoint, Markdown, and images are indexed in the background. Word and PowerPoint files are converted to PDF first, so they are searched and read by page. Poll the document until status is completed (or completed_with_warnings); failed includes errorMessage.

GET /api/v1/documents/{documentId}

CSV and Excel files are stored for agents to read row by row, but they are not indexed, so they return completed with indexedChunkCount: 0 straight away.

SDK and CLI

import { readFile } from "node:fs/promises";

const upload = await client.documents.upload({
  file: new File([await readFile("lamp-datasheet.pdf")], "lamp-datasheet.pdf", {
    type: "application/pdf",
  }),
  documentType: "datasheet",
});
const { data } = await client.documents.get({
  documentId: upload.data.document.id,
});

with open("lamp-datasheet.pdf", "rb") as file:
    upload = client.documents.upload(file=file, document_type="datasheet")

omni documents upload --file ./lamp-datasheet.pdf --json '{"documentType":"datasheet"}'

To add product photos instead, see Product image uploads.

Get started

Guides

SDK

CLI

Webhooks

MCP

Authentication

Upload a document

Wait for indexing

SDK and CLI

​Authentication

​Upload a document

​Wait for indexing

​SDK and CLI

Authentication

Upload a document

Wait for indexing

SDK and CLI