Upload Vector Data

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"
      }
    ]
  }'

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": "prod_001",
        "vector": [0.1, -0.2, 0.3, 0.4],
        "text": "Wireless bluetooth headphones",
        "category": "electronics",
        "price": 99.99,
        "brand": "TechCorp"
      },
      {
        "id": "prod_002",
        "vector": [0.2, 0.1, -0.4, 0.3],
        "text": "Professional gaming mouse",
        "category": "electronics",
        "price": 79.99,
        "brand": "GameGear"
      }
    ]
  }'

{
  "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"
    }
  ]
}

{
  "status": "partial_success",
  "message": "1 out of 2 vectors uploaded successfully. 1 vector failed validation.",
  "upload_id": "upload_vec_1234567891",
  "namespace_name": "my-embeddings",
  "vectors_processed": 1,
  "vectors_failed": 1,
  "uploaded_vectors": [
    {
      "id": "vec_001",
      "status": "completed",
      "dimension": 1536
    }
  ],
  "failed_vectors": [
    {
      "id": "vec_002",
      "error": "Dimension mismatch",
      "message": "Vector dimension (768) does not match namespace dimension (1536)",
      "expected_dimension": 1536,
      "provided_dimension": 768
    }
  ]
}

{
  "error": "Invalid request parameters",
  "message": "Vector dimension mismatch. All vectors must have dimension 1536.",
  "details": {
    "namespace_dimension": 1536,
    "provided_dimensions": [1536, 768, 1536],
    "invalid_vectors": ["vectors[1]"]
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key. Please check your x-api-key header.",
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "Forbidden",
  "message": "Vector upload limit reached for your current tier. Upgrade your plan or delete unused vectors.",
  "details": {
    "current_count": 49950,
    "tier_limit": 50000,
    "tier": "professional",
    "vectors_attempted": 100
  }
}

{
  "error": "Namespace not found",
  "message": "No vector namespace found with the name 'my-embeddings' in your account.",
  "namespace_name": "my-embeddings",
  "suggestion": "Create a vector namespace first or check the namespace name."
}

{
  "error": "Internal server error",
  "message": "An unexpected error occurred while uploading vectors. Please try again later.",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_1234567890"
}

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"
      }
    ]
  }'

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": "prod_001",
        "vector": [0.1, -0.2, 0.3, 0.4],
        "text": "Wireless bluetooth headphones",
        "category": "electronics",
        "price": 99.99,
        "brand": "TechCorp"
      },
      {
        "id": "prod_002",
        "vector": [0.2, 0.1, -0.4, 0.3],
        "text": "Professional gaming mouse",
        "category": "electronics",
        "price": 79.99,
        "brand": "GameGear"
      }
    ]
  }'

{
  "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"
    }
  ]
}

{
  "status": "partial_success",
  "message": "1 out of 2 vectors uploaded successfully. 1 vector failed validation.",
  "upload_id": "upload_vec_1234567891",
  "namespace_name": "my-embeddings",
  "vectors_processed": 1,
  "vectors_failed": 1,
  "uploaded_vectors": [
    {
      "id": "vec_001",
      "status": "completed",
      "dimension": 1536
    }
  ],
  "failed_vectors": [
    {
      "id": "vec_002",
      "error": "Dimension mismatch",
      "message": "Vector dimension (768) does not match namespace dimension (1536)",
      "expected_dimension": 1536,
      "provided_dimension": 768
    }
  ]
}

{
  "error": "Invalid request parameters",
  "message": "Vector dimension mismatch. All vectors must have dimension 1536.",
  "details": {
    "namespace_dimension": 1536,
    "provided_dimensions": [1536, 768, 1536],
    "invalid_vectors": ["vectors[1]"]
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key. Please check your x-api-key header.",
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "Forbidden",
  "message": "Vector upload limit reached for your current tier. Upgrade your plan or delete unused vectors.",
  "details": {
    "current_count": 49950,
    "tier_limit": 50000,
    "tier": "professional",
    "vectors_attempted": 100
  }
}

{
  "error": "Namespace not found",
  "message": "No vector namespace found with the name 'my-embeddings' in your account.",
  "namespace_name": "my-embeddings",
  "suggestion": "Create a vector namespace first or check the namespace name."
}

{
  "error": "Internal server error",
  "message": "An unexpected error occurred while uploading vectors. Please try again later.",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_1234567890"
}

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

string

required

Your API key for authentication

string

required

Must be application/json

Path Parameters

string

required

Name of the vector namespace to upload vectors to

Body Parameters

array

required

Array of vector objects to upload

Vector Object

string

required

Unique identifier for the vector.

array

required

Array of numbers representing the vector embedding

string

Optional original text that generated this vector

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"
      }
    ]
  }'

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": "prod_001",
        "vector": [0.1, -0.2, 0.3, 0.4],
        "text": "Wireless bluetooth headphones",
        "category": "electronics",
        "price": 99.99,
        "brand": "TechCorp"
      },
      {
        "id": "prod_002",
        "vector": [0.2, 0.1, -0.4, 0.3],
        "text": "Professional gaming mouse",
        "category": "electronics",
        "price": 79.99,
        "brand": "GameGear"
      }
    ]
  }'

{
  "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"
    }
  ]
}

{
  "status": "partial_success",
  "message": "1 out of 2 vectors uploaded successfully. 1 vector failed validation.",
  "upload_id": "upload_vec_1234567891",
  "namespace_name": "my-embeddings",
  "vectors_processed": 1,
  "vectors_failed": 1,
  "uploaded_vectors": [
    {
      "id": "vec_001",
      "status": "completed",
      "dimension": 1536
    }
  ],
  "failed_vectors": [
    {
      "id": "vec_002",
      "error": "Dimension mismatch",
      "message": "Vector dimension (768) does not match namespace dimension (1536)",
      "expected_dimension": 1536,
      "provided_dimension": 768
    }
  ]
}

{
  "error": "Invalid request parameters",
  "message": "Vector dimension mismatch. All vectors must have dimension 1536.",
  "details": {
    "namespace_dimension": 1536,
    "provided_dimensions": [1536, 768, 1536],
    "invalid_vectors": ["vectors[1]"]
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key. Please check your x-api-key header.",
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "Forbidden",
  "message": "Vector upload limit reached for your current tier. Upgrade your plan or delete unused vectors.",
  "details": {
    "current_count": 49950,
    "tier_limit": 50000,
    "tier": "professional",
    "vectors_attempted": 100
  }
}

{
  "error": "Namespace not found",
  "message": "No vector namespace found with the name 'my-embeddings' in your account.",
  "namespace_name": "my-embeddings",
  "suggestion": "Create a vector namespace first or check the namespace name."
}

{
  "error": "Internal server error",
  "message": "An unexpected error occurred while uploading vectors. Please try again later.",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_1234567890"
}

Response Fields

Success Response

string

Status of the upload (“success” for successful uploads)

string

Human-readable confirmation message

string

Unique identifier for tracking this upload batch

string

Name of the namespace where vectors were uploaded

number

Number of vectors successfully processed

string

Current status: “completed” (vectors process immediately)

array

Array of uploaded vector status objects

Vector Status Object

string

Vector identifier

string

Processing status: “completed” or “failed”

number

Dimension of the uploaded vector

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

Getting Started

Namespace Management

Search & Discovery

AI Generation

Data Operations

File storage

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

​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