Upload Vector Data - Moorcheh Documentation

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": [
      {
        "id": "vec_001",
        "vector": [0.1, -0.2, 0.3, 0.4, -0.5],
        "text": "Machine learning algorithms",
        "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"
    }
  ]
}

POST

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": [
      {
        "id": "vec_001",
        "vector": [0.1, -0.2, 0.3, 0.4, -0.5],
        "text": "Machine learning algorithms",
        "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

required

Unique identifier for the vector.

vectors[].vector

array

required

Array of numbers representing the vector embedding

vectors[].text

string

Optional original text that generated this vector

vectors[].*

any

Optional metadata fields for filtering and organization. Any additional fields beyond id, vector, and text are treated as metadata.

Metadata:

All key-value pairs other than id and vector are considered as metadata
Recommended metadata is text (optional) to store the original text that generated this vector
You can add any additional metadata fields as key-value pairs according to your preference for filtering and organization

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": [
      {
        "id": "vec_001",
        "vector": [0.1, -0.2, 0.3, 0.4, -0.5],
        "text": "Machine learning algorithms",
        "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

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

Common Embedding Models

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

Custom Embeddings

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

Quality Considerations

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

Dimension Validation

Verify all vectors match the namespace dimension

Format Validation

Check vector format and numeric precision

Index Insertion

Add vectors to high-performance similarity search index

Metadata Storage

Store associated metadata and text for retrieval

Immediate Availability

Vectors are immediately available for search

Best Practices

Vector Quality

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

Batch Optimization

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

Metadata Strategy

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

Search - Search uploaded vector embeddings
Get Documents - Retrieve vector information
Delete Data - Remove uploaded vectors
Create Namespace - Create vector namespaces for uploads

Upload Text Data Get Documents

​Overview

​Authentication

​Path Parameters

​Body Parameters

​Vector Object

​Response Fields

​Success Response

​Vector Status Object

​Vector Requirements

Dimension Match

Value Range

Batch Size

Precision

​Dimension Guidelines

​Processing Pipeline

​Best Practices

​Use Cases

​Related Endpoints

Overview

Authentication

Path Parameters

Body Parameters

Vector Object

Response Fields

Success Response

Vector Status Object

Vector Requirements

Dimension Guidelines

Processing Pipeline

Best Practices

Use Cases

Related Endpoints