Skip to main content
POST
/
namespaces
/
{namespace_name}
/
vectors
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"
      }
    ]
  }'

{
  "status": "success",
  "message": "Vectors upload started. Poll job status for progress.",
  "job_id": "job-d044a3bf6c0e4380bf6ad7e9df7999d0",
  "namespace_name": "my-embeddings",
  "total": 1
}

​
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 with the returned job_id.
Any extra fields on each vector object (for example source, category) are stored as metadata and can be used in search filters.

​
Path parameters

​
namespace_name
string
required
Target vector namespace.

​
Headers

​
Content-Type
string
required
Must be application/json

​
Body

​
vectors
array
required
Non-empty array of vector objects.
​
vectors[].id
string
required
Item id, unique within this namespace.
​
vectors[].vector
array
required
Array of finite numbers. Length must equal the namespace vector_dimension.
​
vectors[].{metadata}
any
Optional additional keys on each vector are saved as metadata (for example "source": "demo").
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"
      }
    ]
  }'
The vector array length must match vector_dimension for my-embeddings (for example 768 or 5 depending on how the namespace was created).

​
Response fields

​
status
string
Request outcome. "success" when the upload job was started; "failure" on error.
​
message
string
Human-readable result or error description.
​
job_id
string
Id of the async upload job. Poll Upload job status with this value. Present when the upload job was started.
​
namespace_name
string
Namespace the vectors are being uploaded to. Present when the upload job was started.
​
total
number
Number of vectors accepted into the upload job. Present when the upload job was started.
​
items
number
Current total item count on the instance. Present on 409 item limit errors.
​
max_items
number
Global item cap for this instance. Present on 409 item limit errors.
​
requested_new
number
Number of new item ids in the request that would exceed the cap. Present on 409 item limit errors.
{
  "status": "success",
  "message": "Vectors upload started. Poll job status for progress.",
  "job_id": "job-d044a3bf6c0e4380bf6ad7e9df7999d0",
  "namespace_name": "my-embeddings",
  "total": 1
}

​
Important Notes

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

​
Next Steps