> ## 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 to a vector namespace. Returns an async job id.

## Overview

Upload one or more vectors to a **vector** namespace. Each vector length must match the namespace `vector_dimension` set at creation.

The upload runs asynchronously. Poll [Upload job status](/on-prem/api-references/data/upload-job-status) with the returned `job_id`.

<Note>
  Any extra fields on each vector object (for example `source`, `category`) are stored as metadata and can be used in search filters.
</Note>

## Path parameters

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

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Body

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

<RequestExample>
  ```bash theme={null}
  curl -X POST "http://localhost:8080/namespaces/my-embeddings/vectors" \
    -H "Content-Type: application/json" \
    -d '{
      "vectors": [
        {
          "id": "vec-1",
          "vector": [0.1, 0.2, 0.3, 0.4, 0.5],
          "source": "demo"
        }
      ]
    }'
  ```
</RequestExample>

<Note>
  The `vector` array length must match `vector_dimension` for `my-embeddings` (for example `768` or `5` depending on how the namespace was created).
</Note>

## Response fields

<ResponseField name="status" type="string">
  Request outcome. `"success"` when the upload job was started; `"failure"` on error.
</ResponseField>

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

<ResponseField name="job_id" type="string">
  Id of the async upload job. Poll [Upload job status](/on-prem/api-references/data/upload-job-status) with this value. Present when the upload job was started.
</ResponseField>

<ResponseField name="namespace_name" type="string">
  Namespace the vectors are being uploaded to. Present when the upload job was started.
</ResponseField>

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

<ResponseField name="items" type="number">
  Current total item count on the instance. Present on **409** item limit errors.
</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>

<ResponseExample>
  ```json 202 - Accepted theme={null}
  {
    "status": "success",
    "message": "Vectors upload started. Poll job status for progress.",
    "job_id": "job-d044a3bf6c0e4380bf6ad7e9df7999d0",
    "namespace_name": "my-embeddings",
    "total": 1
  }
  ```

  ```json 400 - Empty vectors array theme={null}
  {
    "status": "failure",
    "message": "Bad Request: vectors must be a non-empty array."
  }
  ```

  ```json 400 - Missing id or vector theme={null}
  {
    "status": "failure",
    "message": "Bad Request: each vector item must include non-empty 'id' and 'vector'."
  }
  ```

  ```json 400 - Non-finite values theme={null}
  {
    "status": "failure",
    "message": "Bad Request: vector values must be finite numbers."
  }
  ```

  ```json 400 - Dimension mismatch theme={null}
  {
    "status": "failure",
    "message": "Bad Request: all vectors must match namespace dimension 768."
  }
  ```

  ```json 400 - Wrong namespace type theme={null}
  {
    "status": "failure",
    "message": "Namespace 'my-documents' is not a vector namespace."
  }
  ```

  ```json 404 - Namespace not found theme={null}
  {
    "status": "failure",
    "message": "Namespace 'my-embeddings' not found."
  }
  ```

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

## Important Notes

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

## Next Steps

* [Upload job status](/on-prem/api-references/data/upload-job-status)
* [Search with vector query](/on-prem/api-references/search/query)

## Related

* [CLI: moorcheh upload-vectors](/on-prem/cli/data/upload-vectors)
* [Python: vectors.upload()](/on-prem/python-client/data/upload-vectors)