Skip to main content
POST
https://api.moorcheh.ai
/
v1
/
namespaces
/
{namespace_name}
/
vectors
curl -X POST "https://api.moorcheh.ai/v1/namespaces/my-vectors/vectors" \
  -H "Content-Type: application/json" \
  -H "x-api-Key: your-api-key-here" \
  -d '{
    "vectors": [
      {
        "vector": [0.1, -0.2, 0.3, 0.4, -0.5],
        "text": "Machine learning algorithms",
        "metadata": {
          "source": "openai",
          "model": "text-embedding-3-small",
          "category": "tech"
        }
      }
    ]
  }'

{
  "status": "success",
  "message": "2 vectors uploaded successfully to namespace 'product-embeddings'",
  "upload_id": "upload_vec_1234567890",
  "namespace_name": "product-embeddings",
  "vectors_processed": 2,
  "processing_status": "completed",
  "uploaded_vectors": [
    {
      "id": "prod_001",
      "status": "completed",
      "dimension": 4,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "prod_002",
      "status": "completed",
      "dimension": 4,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Overview

Upload pre-computed vector embeddings to a vector namespace for high-performance similarity search. This endpoint is ideal when you have your own embeddings or want to use specific embedding models.
Vectors must match the exact dimension specified when the namespace was created. All vectors in a batch must have the same dimension.

​
Authentication

​
x-api-Key
string
required
Your API key for authentication
​
Content-Type
string
required
Must be application/json

​
Path Parameters

​
namespace_name
string
required
Name of the vector namespace to upload vectors to

​
Body Parameters

​
vectors
array
required
Array of vector objects to upload

​
Vector Object

​
vectors[].id
string
Optional unique identifier for the vector. Auto-generated if not provided.
​
vectors[].vector
array
required
Array of numbers representing the vector embedding
​
vectors[].metadata
object
Optional metadata object for filtering and organization
​
vectors[].text
string
Optional original text that generated this vector
curl -X POST "https://api.moorcheh.ai/v1/namespaces/my-vectors/vectors" \
  -H "Content-Type: application/json" \
  -H "x-api-Key: your-api-key-here" \
  -d '{
    "vectors": [
      {
        "vector": [0.1, -0.2, 0.3, 0.4, -0.5],
        "text": "Machine learning algorithms",
        "metadata": {
          "source": "openai",
          "model": "text-embedding-3-small",
          "category": "tech"
        }
      }
    ]
  }'

{
  "status": "success",
  "message": "2 vectors uploaded successfully to namespace 'product-embeddings'",
  "upload_id": "upload_vec_1234567890",
  "namespace_name": "product-embeddings",
  "vectors_processed": 2,
  "processing_status": "completed",
  "uploaded_vectors": [
    {
      "id": "prod_001",
      "status": "completed",
      "dimension": 4,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "prod_002",
      "status": "completed",
      "dimension": 4,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Response Fields

​
Success Response

​
status
string
Status of the upload (“success” for successful uploads)
​
message
string
Human-readable confirmation message
​
upload_id
string
Unique identifier for tracking this upload batch
​
namespace_name
string
Name of the namespace where vectors were uploaded
​
vectors_processed
number
Number of vectors successfully processed
​
processing_status
string
Current status: “completed” (vectors process immediately)
​
uploaded_vectors
array
Array of uploaded vector status objects

​
Vector Status Object

​
id
string
Vector identifier
​
status
string
Processing status: “completed” or “failed”
​
dimension
number
Dimension of the uploaded vector
​
created_at
string
ISO 8601 timestamp when vector was uploaded

​
Vector Requirements

Dimension Match

Must match namespace dimension exactly Common: 384, 768, 1536, 3072

Value Range

Normalized vectors preferred Range: -1.0 to 1.0 (typical)

Batch Size

Max: 1000 vectors per request Recommended: 100-500 for optimal performance

Precision

Float32 precision Up to 7 decimal places

​
Dimension Guidelines

OpenAI text-embedding-3-large: 3072 dimensions OpenAI text-embedding-3-small: 1536 dimensions OpenAI text-embedding-ada-002: 1536 dimensions Sentence-BERT: 384 or 768 dimensions Universal Sentence Encoder: 512 dimensions
  • Ensure consistent preprocessing across all vectors
  • Normalize vectors for better similarity calculations
  • Use the same model/settings for all vectors in a namespace
  • Document your embedding generation process
  • Higher dimensions generally capture more semantic information
  • Ensure vectors represent meaningful semantic content
  • Consider domain-specific fine-tuned models for specialized content
  • Test similarity search quality with sample queries

​
Processing Pipeline

1

Dimension Validation

Verify all vectors match the namespace dimension
2

Format Validation

Check vector format and numeric precision
3

Index Insertion

Add vectors to high-performance similarity search index
4

Metadata Storage

Store associated metadata and text for retrieval
5

Immediate Availability

Vectors are immediately available for search

​
Best Practices

  • Use high-quality, domain-appropriate embedding models
  • Normalize vectors to unit length for cosine similarity
  • Ensure consistent preprocessing and tokenization
  • Test with sample searches before large uploads
  • Upload 100-500 vectors per request for best performance
  • Use meaningful IDs for easier management and updates
  • Include original text when possible for result display
  • Group related vectors in single uploads
  • Include filterable metadata for refined searches
  • Store embedding model information for reference
  • Add timestamps and source information
  • Consider access control metadata

​
Use Cases

  • Semantic Search: Build powerful semantic search over documents
  • Recommendation Systems: Find similar products, content, or users
  • Content Discovery: Enable “more like this” functionality
  • Duplicate Detection: Identify similar or duplicate content
  • Clustering & Analysis: Group similar items for analysis
  • RAG Applications: Retrieval-augmented generation for AI applications