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

{
  "status": "failure",
  "message": "Bad Request: vectors must be a non-empty array."
}

{
  "status": "failure",
  "message": "Bad Request: each vector item must include non-empty 'id' and 'vector'."
}

{
  "status": "failure",
  "message": "Bad Request: vector values must be finite numbers."
}

{
  "status": "failure",
  "message": "Bad Request: all vectors must match namespace dimension 768."
}

{
  "status": "failure",
  "message": "Namespace 'my-documents' is not a vector namespace."
}

{
  "status": "failure",
  "message": "Namespace 'my-embeddings' not found."
}

{
  "status": "failure",
  "message": "Item limit exceeded: max 100000, current 100000, requested 1 new items.",
  "items": 100000,
  "max_items": 100000,
  "requested_new": 1
}

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
}

{
  "status": "failure",
  "message": "Bad Request: vectors must be a non-empty array."
}

{
  "status": "failure",
  "message": "Bad Request: each vector item must include non-empty 'id' and 'vector'."
}

{
  "status": "failure",
  "message": "Bad Request: vector values must be finite numbers."
}

{
  "status": "failure",
  "message": "Bad Request: all vectors must match namespace dimension 768."
}

{
  "status": "failure",
  "message": "Namespace 'my-documents' is not a vector namespace."
}

{
  "status": "failure",
  "message": "Namespace 'my-embeddings' not found."
}

{
  "status": "failure",
  "message": "Item limit exceeded: max 100000, current 100000, requested 1 new items.",
  "items": 100000,
  "max_items": 100000,
  "requested_new": 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

string

required

Target vector namespace.

Headers

string

required

Must be application/json

Body

array

required

Non-empty array of vector objects.

string

required

Item id, unique within this namespace.

array

required

Array of finite numbers. Length must equal the namespace vector_dimension.

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

string

Request outcome. "success" when the upload job was started; "failure" on error.

string

Human-readable result or error description.

string

Id of the async upload job. Poll Upload job status with this value. Present when the upload job was started.

string

Namespace the vectors are being uploaded to. Present when the upload job was started.

number

Number of vectors accepted into the upload job. Present when the upload job was started.

number

Current total item count on the instance. Present on 409 item limit errors.

number

Global item cap for this instance. Present on 409 item limit errors.

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
}

{
  "status": "failure",
  "message": "Bad Request: vectors must be a non-empty array."
}

{
  "status": "failure",
  "message": "Bad Request: each vector item must include non-empty 'id' and 'vector'."
}

{
  "status": "failure",
  "message": "Bad Request: vector values must be finite numbers."
}

{
  "status": "failure",
  "message": "Bad Request: all vectors must match namespace dimension 768."
}

{
  "status": "failure",
  "message": "Namespace 'my-documents' is not a vector namespace."
}

{
  "status": "failure",
  "message": "Namespace 'my-embeddings' not found."
}

{
  "status": "failure",
  "message": "Item limit exceeded: max 100000, current 100000, requested 1 new items.",
  "items": 100000,
  "max_items": 100000,
  "requested_new": 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)

System

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

Overview

Path parameters

Headers

Body

Response fields

Important Notes

Next Steps

​Overview

​Path parameters

​Headers

​Body

​Response fields

​Important Notes

​Next Steps

​Related

Overview

Path parameters

Headers

Body

Response fields

Important Notes

Next Steps

Related