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

# Upload

> Upload or replace items by id (text or vector store).

## Overview

Upload or replace items keyed by id. Re-uploading an existing id updates the embedding and does **not** consume additional quota.

On the **first upload** to an empty store, `store_mode` is required. Dimension and mode are locked afterward.

<ParamField body="store_mode" type="string">
  Required when the store is empty: `"text"` or `"vector"`.
</ParamField>

<ParamField body="embedding_model" type="string">
  Optional for text stores. Defaults to `BAAI/bge-base-en-v1.5`.
</ParamField>

<ParamField body="items" type="array" required>
  Non-empty array of item objects.
</ParamField>

Each item object:

<ParamField body="id" type="string" required>
  Item id. Alias: `item_id`.
</ParamField>

<ParamField body="vector" type="array" required>
  Float embedding matching the store dimension (768 for text mode).
</ParamField>

<ParamField body="text" type="string">
  Optional text stored with the item and returned in search results.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "http://localhost:8080/upload" \
    -H "Content-Type: application/json" \
    -d '{
      "store_mode": "text",
      "embedding_model": "BAAI/bge-base-en-v1.5",
      "items": [
        {
          "id": "doc-1",
          "text": "Hello world",
          "vector": [0.01, -0.02, "... 768 floats ..."]
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "status": "success",
    "message": "Items uploaded successfully.",
    "total": 1,
    "dimension": 768,
    "store_mode": "text"
  }
  ```

  ```json 409 - Quota exceeded theme={null}
  {
    "status": "failure",
    "message": "Item limit exceeded: max 10000, current 10000, requested 1 new items.",
    "items": 10000,
    "max_items": 10000,
    "requested_new": 1
  }
  ```
</ResponseExample>

## Related

* [Health](/api-references/health)
* [Export store](/api-references/export)
* [CLI: upload-documents](/cli/upload-documents)
* [CLI: upload-vectors](/cli/upload-vectors)