> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge base uploads

> Upload documents to the organization knowledge base that agents and enrichment search.

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`:

```bash theme={null}
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`:

```json theme={null}
{
  "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`.

```http theme={null}
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

```ts theme={null}
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,
});
```

```python theme={null}
with open("lamp-datasheet.pdf", "rb") as file:
    upload = client.documents.upload(file=file, document_type="datasheet")
```

```bash theme={null}
omni documents upload --file ./lamp-datasheet.pdf --json '{"documentType":"datasheet"}'
```

To add product photos instead, see [Product image uploads](/guides/product-images).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.