> ## 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 Vectors

> Upload precomputed vectors using the Python client

## vectors.upload

Uploads one or more precomputed vectors to a **vector** namespace. Each vector length must match the namespace `vector_dimension` set at creation. Poll [Upload Job Status](/on-prem/python-client/data/upload-job-status) with the returned `job_id`.

```python theme={null}
client.vectors.upload(
    namespace_name: str,
    *,
    vectors: list[dict],
) -> dict[str, Any]
```

<Note>
  The `*` means `vectors` is **keyword-only**. Extra fields on each vector (for example `source`) are stored as metadata for search filters.
</Note>

**API:** `POST /namespaces/{namespace_name}/vectors` — see [Upload vectors](/on-prem/api-references/data/upload-vectors)

### Parameters

<ParamField path="namespace_name" type="string" required>
  Target vector namespace.
</ParamField>

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

<ParamField body="vectors[].id" type="string" required>
  Item id, unique within this namespace.
</ParamField>

<ParamField body="vectors[].vector" type="array" required>
  Array of finite numbers. Length must equal the namespace `vector_dimension`.
</ParamField>

<ParamField body="vectors[].{metadata}" type="any">
  Optional additional keys on each vector are saved as metadata (for example `"source": "demo"`).
</ParamField>

### Examples

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    try:
        resp = client.vectors.upload(
            "my-embeddings",
            vectors=[
                {
                    "id": "vec-1",
                    "vector": [0.1] * 768,
                    "source": "demo",
                },
            ],
        )
        job_id = resp["job_id"]
    except MoorchehApiError as e:
        if e.is_item_limit_exceeded:
            print(e.body)
        else:
            raise
```

Poll with [vectors.upload\_job\_status](/on-prem/python-client/data/upload-job-status).

## Returns

<ResponseField name="status" type="string">
  `"success"` when the upload job was started.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result description.
</ResponseField>

<ResponseField name="job_id" type="string">
  Id of the async upload job. Poll [vectors.upload\_job\_status](/on-prem/python-client/data/upload-job-status) with this value.
</ResponseField>

<ResponseField name="namespace_name" type="string">
  Namespace the vectors are being uploaded to.
</ResponseField>

<ResponseField name="total" type="number">
  Number of vectors accepted into the upload job.
</ResponseField>

<ResponseField name="items" type="number">
  Current total item count on the instance. Present on **409** item limit errors in `MoorchehApiError.body`.
</ResponseField>

<ResponseField name="max_items" type="number">
  Global item cap for this instance. Present on **409** item limit errors.
</ResponseField>

<ResponseField name="requested_new" type="number">
  Number of new item ids in the request that would exceed the cap. Present on **409** item limit errors.
</ResponseField>

```python Example return value theme={null}
{
  "status": "success",
  "message": "Vectors upload started. Poll job status for progress.",
  "job_id": "job-d044a3bf6c0e4380bf6ad7e9df7999d0",
  "namespace_name": "my-embeddings",
  "total": 1,
}
```

### Error Handling

Non-2xx responses raise `MoorchehApiError`. Use `e.is_item_limit_exceeded` for **409** quota errors.

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        client.vectors.upload("my-embeddings", vectors=[...])
except MoorchehApiError as e:
    print(e.status_code, e.body)
```

| Status | Cause                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------ |
| 400    | Empty `vectors`, missing `id`/`vector`, non-finite values, dimension mismatch, or wrong namespace type |
| 404    | Namespace not found                                                                                    |
| 409    | Global item limit would be exceeded (job not started)                                                  |

<Warning>
  * At most **100,000 items** total across all namespaces
  * **409** is returned before the job starts if new ids would exceed the cap
  * Re-uploading an existing id in the same namespace updates the item and does not consume extra quota
  * Vector values must be finite (no `NaN` or `Infinity`)
</Warning>

## Related Operations

* [Upload Job Status](/on-prem/python-client/data/upload-job-status)
* [API: Upload vectors](/on-prem/api-references/data/upload-vectors)
* [CLI: moorcheh upload-vectors](/on-prem/cli/data/upload-vectors)