Skip to content

API_REFERENCE.md

Latest commit

 

History

History
executable file
·
2261 lines (1754 loc) · 53.2 KB

API_REFERENCE.md

File metadata and controls

executable file
·
2261 lines (1754 loc) · 53.2 KB
title REST API Reference
module api
id api-reference
order 1
description Complete REST API reference for Vectorizer
tags
api
rest
endpoints
reference

REST API Reference

Complete reference for all Vectorizer REST API endpoints.

Base URL

All API requests should be made to:

http://localhost:15002

Or your configured host and port.

Authentication

Currently, Vectorizer does not require authentication. All endpoints are publicly accessible.

Note: For production deployments, consider using a reverse proxy with authentication.

Response Format

Success Response

{
  "status": "success",
  "data": { ... }
}

Error Response

{
  "error": {
    "type": "error_type",
    "message": "Error message",
    "status_code": 400
  }
}

System Endpoints

Health Check

Check if the server is running and healthy.

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2024-11-16T10:30:00Z",
  "version": "1.3.0",
  "cache": {
    "size": 123,
    "capacity": 1000,
    "hits": 500,
    "misses": 200,
    "evictions": 50,
    "hit_rate": 0.714
  }
}

Example:

curl http://localhost:15002/health

System Statistics

Get system-wide statistics.

Endpoint: GET /stats

Response:

{
  "collections": 5,
  "total_vectors": 125000,
  "memory_usage_bytes": 512000000,
  "disk_usage_bytes": 256000000
}

Collection Endpoints

List Collections

Get a list of all collections.

Endpoint: GET /collections

Response:

{
  "collections": [
    {
      "name": "my_collection",
      "vector_count": 1250,
      "dimension": 384,
      "metric": "cosine"
    }
  ]
}

Example:

curl http://localhost:15002/collections

Create Collection

Create a new collection.

Endpoint: POST /collections

Request Body:

{
  "name": "my_collection",
  "dimension": 384,
  "metric": "cosine",
  "hnsw_config": {
    "m": 16,
    "ef_construction": 200,
    "ef_search": 64
  },
  "quantization": {
    "enabled": true,
    "type": "scalar",
    "bits": 8
  }
}

Response:

{
  "status": "created",
  "collection": {
    "name": "my_collection",
    "dimension": 384,
    "metric": "cosine"
  }
}

Example:

curl -X POST http://localhost:15002/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_collection",
    "dimension": 384,
    "metric": "cosine"
  }'

Get Collection

Get information about a specific collection.

Endpoint: GET /collections/{name}

Response:

{
  "name": "my_collection",
  "vector_count": 1250,
  "dimension": 384,
  "metric": "cosine",
  "hnsw_config": {
    "m": 16,
    "ef_construction": 200,
    "ef_search": 64
  },
  "quantization": {
    "enabled": true,
    "type": "scalar",
    "bits": 8
  }
}

Example:

curl http://localhost:15002/collections/my_collection

Delete Collection

Delete a collection and all its vectors.

Endpoint: DELETE /collections/{name}

Response:

{
  "status": "deleted",
  "collection": "my_collection"
}

Example:

curl -X DELETE http://localhost:15002/collections/my_collection

Vector Endpoints

Insert Vector

Insert a single vector into a collection.

Endpoint: POST /collections/{name}/insert

Request Body:

{
  "id": "vector_001",
  "text": "Vectorizer is a high-performance vector database",
  "metadata": {
    "source": "readme",
    "category": "documentation"
  }
}

Or with pre-computed vector:

{
  "id": "vector_001",
  "vector": [0.1, 0.2, 0.3, ...],
  "metadata": {
    "source": "custom"
  }
}

Response:

{
  "id": "vector_001",
  "status": "inserted"
}

Example:

curl -X POST http://localhost:15002/collections/my_collection/insert \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Vectorizer is awesome!",
    "metadata": {"source": "readme"}
  }'

Get Vector

Retrieve a specific vector by ID.

Endpoint: GET /collections/{name}/vectors/{id}

Query Parameters:

  • with_vector (boolean): Include vector data in response
  • with_payload (boolean): Include metadata in response

Response:

{
  "id": "vector_001",
  "vector": [0.1, 0.2, 0.3, ...],
  "payload": {
    "source": "readme",
    "category": "documentation"
  }
}

Example:

curl "http://localhost:15002/collections/my_collection/vectors/vector_001?with_vector=true&with_payload=true"

Update Vector

Update an existing vector.

Endpoint: PATCH /collections/{name}/vectors/{id}

Request Body:

{
  "text": "Updated content",
  "metadata": {
    "last_modified": "2024-11-16"
  }
}

Response:

{
  "id": "vector_001",
  "status": "updated"
}

Example:

curl -X PATCH http://localhost:15002/collections/my_collection/vectors/vector_001 \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Updated content",
    "metadata": {"last_modified": "2024-11-16"}
  }'

Delete Vector

Delete a vector from a collection.

Endpoint: DELETE /collections/{name}/vectors/{id}

Response:

{
  "id": "vector_001",
  "status": "deleted"
}

Example:

curl -X DELETE http://localhost:15002/collections/my_collection/vectors/vector_001

Move Vectors Between Collections

Relocate vectors from one collection to another without re-embedding (issue #265). The destination must already exist; the handler reads each vector by id, inserts into dst carrying the raw vector data + payload as-is, then deletes from src. The dst-insert-before-src-delete ordering is the documented invariant: a mid-batch crash leaves a recoverable duplicate, never data loss.

Per-id failures populate results without aborting the batch. Operators chasing tier-demotion sweeps want partial progress, not abort-on-first-error.

Endpoint: POST /collections/{src}/vectors/move

Request Body:

{
  "destination": "cortex.consolidation.pq",
  "ids": ["vec-1", "vec-2"]
}

Response:

{
  "src": "cortex.consolidation.fp32",
  "dst": "cortex.consolidation.pq",
  "requested": 2,
  "moved": 2,
  "failed": 0,
  "results": [
    { "id": "vec-1", "status": "ok" },
    { "id": "vec-2", "status": "ok" }
  ]
}

Per-id status values:

Status Meaning
ok Inserted into dst and deleted from src.
missing_in_src Vector id not found in source.
dst_insert_failed Destination rejected the insert (typical: dim/encoding mismatch). Source vector preserved.
src_delete_failed Insert succeeded but source delete failed. Vector exists in BOTH collections (recoverable on retry).

Errors:

  • 400 validation_error — ids is empty, missing, or destination equals the source collection.

List Vectors

List all vectors in a collection.

Endpoint: GET /collections/{name}/vectors

Query Parameters:

  • limit (integer): Maximum number of vectors to return
  • offset (integer): Number of vectors to skip
  • with_vector (boolean): Include vector data
  • with_payload (boolean): Include metadata

Response:

{
  "vectors": [
    {
      "id": "vector_001",
      "payload": {
        "source": "readme"
      }
    }
  ],
  "total": 1250
}

Search Endpoints

Basic Search

Search for similar vectors.

Endpoint: POST /collections/{name}/search

Request Body:

{
  "query": "vector database",
  "limit": 10,
  "similarity_threshold": 0.5,
  "with_vector": false,
  "with_payload": true
}

Or with vector:

{
  "vector": [0.1, 0.2, 0.3, ...],
  "limit": 10
}

Response:

{
  "results": [
    {
      "id": "vector_001",
      "score": 0.95,
      "payload": {
        "source": "readme"
      }
    }
  ]
}

Example:

curl -X POST http://localhost:15002/collections/my_collection/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "vector database",
    "limit": 10
  }'

Intelligent Search

Advanced search with query expansion and MMR.

Endpoint: POST /collections/{name}/intelligent_search

Request Body:

{
  "query": "neural networks for image recognition",
  "max_results": 15,
  "domain_expansion": true,
  "technical_focus": true,
  "mmr_enabled": true,
  "mmr_lambda": 0.7
}

Response:

{
  "results": [
    {
      "id": "vector_001",
      "score": 0.92,
      "payload": { ... }
    }
  ],
  "expanded_queries": [
    "neural networks",
    "image recognition",
    "deep learning"
  ]
}

Semantic Search

High-precision semantic search with reranking.

Endpoint: POST /collections/{name}/semantic_search

Request Body:

{
  "query": "deep learning architectures",
  "max_results": 10,
  "semantic_reranking": true,
  "similarity_threshold": 0.75
}

Hybrid Search

Combine dense and sparse vector search.

Endpoint: POST /collections/{name}/hybrid_search

Request Body:

{
  "query": "vector database for large-scale applications",
  "query_sparse": {
    "indices": [0, 5, 10],
    "values": [0.8, 0.6, 0.9]
  },
  "alpha": 0.7,
  "algorithm": "rrf",
  "dense_k": 20,
  "sparse_k": 20,
  "final_k": 10
}

Multi-Collection Search

Search across multiple collections.

Endpoint: POST /multi_collection_search

Request Body:

{
  "collections": ["docs", "code", "wiki"],
  "query": "authentication mechanism",
  "max_per_collection": 5,
  "max_total_results": 20,
  "cross_collection_reranking": true
}

Batch Operations

Batch Insert

Insert multiple vectors efficiently.

Endpoint: POST /collections/{name}/batch_insert

Request Body:

{
  "vectors": [
    {
      "id": "vec_001",
      "text": "First document",
      "metadata": { "doc_id": 1 }
    },
    {
      "id": "vec_002",
      "text": "Second document",
      "metadata": { "doc_id": 2 }
    }
  ]
}

Response:

{
  "status": "success",
  "inserted_count": 2,
  "failed_count": 0,
  "errors": []
}

Batch Update

Update multiple vectors.

Endpoint: POST /collections/{name}/batch_update

Request Body:

{
  "vectors": [
    {
      "id": "vec_001",
      "text": "Updated document 1",
      "metadata": { "updated": true }
    }
  ]
}

Batch Delete

Delete multiple vectors.

Endpoint: POST /collections/{name}/batch_delete

Request Body:

{
  "ids": ["vec_001", "vec_002", "vec_003"]
}

Response:

{
  "status": "success",
  "deleted_count": 3,
  "failed_count": 0,
  "errors": []
}

Batch Search

Search with multiple queries.

Endpoint: POST /collections/{name}/batch_search

Request Body:

{
  "queries": [
    { "query": "vector database", "limit": 5 },
    { "query": "semantic search", "limit": 5 }
  ]
}

Response:

{
  "results": [
    [
      {"id": "vec_001", "score": 0.95, ...},
      {"id": "vec_002", "score": 0.92, ...}
    ],
    [
      {"id": "vec_003", "score": 0.88, ...}
    ]
  ]
}

MCP (Model Context Protocol)

Vectorizer implements a comprehensive MCP server using StreamableHTTP (v0.9.0) for AI-powered IDE integration.

Base URL

http://localhost:15002/mcp

Protocol

  • Transport: StreamableHTTP (bi-directional HTTP streaming)
  • Protocol: JSON-RPC 2.0
  • Format: Server-Sent Events (SSE) for streaming

Connection

Endpoint: POST /mcp

Establishes an MCP session and handles JSON-RPC 2.0 requests.

Request Format:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1",
      "param2": "value2"
    }
  },
  "id": 1
}

Response Format:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Result data"
      }
    ]
  },
  "id": 1
}

Available MCP Tools (38+ tools)

Collection Management

  • list_collections - List all collections
  • create_collection - Create a new collection
  • get_collection_info - Get collection details
  • delete_collection - Delete a collection

Vector Operations

  • insert_text - Insert text (auto-embed)
  • get_vector - Retrieve vector by ID
  • update_vector - Update existing vector
  • delete_vectors - Delete vectors
  • embed_text - Generate embedding for text

Search Operations

  • search - Basic semantic search
  • search_intelligent - Intelligent multi-query search
  • search_semantic - Pure semantic search
  • search_extra - Extended search with filters
  • search_hybrid - Hybrid dense + sparse search
  • multi_collection_search - Cross-collection search

Batch Operations

  • batch_insert_texts - Batch insert texts
  • insert_texts - Insert multiple texts
  • batch_search_vectors - Batch search
  • batch_update_vectors - Batch update
  • batch_delete_vectors - Batch delete

Discovery Operations

  • filter_collections - Filter collections by query
  • expand_queries - Expand query terms
  • discover - Discovery pipeline
  • score_collections - Score collection relevance
  • broad_discovery - Broad search across collections
  • semantic_focus - Focused semantic search
  • compress_evidence - Compress search results
  • build_answer_plan - Build answer plan
  • render_llm_prompt - Render LLM prompt
  • promote_readme - Promote README files

File Operations

  • get_file_content - Get file content
  • list_files - List files in collection
  • get_file_chunks - Get file chunks
  • get_project_outline - Get project outline
  • get_related_files - Find related files
  • search_by_file_type - Search by file type

Example: MCP Tool Call

Search Vectors:

curl -X POST http://localhost:15002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "collection": "documents",
        "query": "machine learning",
        "limit": 5
      }
    },
    "id": 1
  }'

Create Collection:

curl -X POST http://localhost:15002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_collection",
      "arguments": {
        "name": "my_collection",
        "dimension": 384,
        "metric": "cosine"
      }
    },
    "id": 2
  }'

UMICP (Universal Multi-Agent Communication Protocol)

Vectorizer supports UMICP v0.2.1 for high-performance envelope-based communication.

Base URL

http://localhost:15002/umicp

Protocol

  • Version: UMICP v0.2.1
  • Transport: HTTP POST with envelope format
  • Format: JSON envelope with capabilities

Endpoints

Main UMICP Handler

Endpoint: POST /umicp

Handles UMICP envelope requests and routes to MCP tools.

Request Format:

{
  "envelope_id": "unique-id",
  "operation": "DATA",
  "capabilities": {
    "operation": "search",
    "collection": "documents",
    "query": "machine learning",
    "limit": 5
  },
  "metadata": {
    "timestamp": "2024-11-16T10:00:00Z"
  }
}

Response Format:

{
  "envelope_id": "unique-id",
  "operation": "DATA",
  "status": "success",
  "result": {
    "results": [
      {
        "id": "vec_001",
        "score": 0.95,
        "text": "..."
      }
    ]
  },
  "metadata": {
    "timestamp": "2024-11-16T10:00:01Z"
  }
}

Health Check

Endpoint: GET /umicp/health

Returns UMICP protocol information and health status.

Response:

{
  "protocol": "UMICP",
  "version": "0.2.1",
  "status": "healthy",
  "server": "vectorizer-server",
  "server_version": "1.3.0"
}

Tool Discovery

Endpoint: GET /umicp/discover

Discovers all available operations with schemas.

Response:

{
  "protocol": "UMICP",
  "version": "0.2.1",
  "server_info": {
    "server": "vectorizer-server",
    "version": "1.3.0",
    "protocol": "UMICP/2.0",
    "features": [
      "semantic-search",
      "vector-storage",
      "intelligent-discovery",
      "file-operations",
      "batch-operations",
      "workspace-management",
      "mcp-compatible"
    ],
    "operations_count": 38,
    "mcp_compatible": true
  },
  "operations": [
    {
      "name": "search",
      "description": "Semantic search in collection",
      "parameters": {
        "collection": {"type": "string", "required": true},
        "query": {"type": "string", "required": true},
        "limit": {"type": "integer", "required": false, "default": 10}
      },
      "read_only": true,
      "idempotent": false,
      "destructive": false
    }
    // ... more operations
  ],
  "total_operations": 38
}

Example: UMICP Request

Search:

curl -X POST http://localhost:15002/umicp \
  -H "Content-Type: application/json" \
  -d '{
    "envelope_id": "req-001",
    "operation": "DATA",
    "capabilities": {
      "operation": "search",
      "collection": "documents",
      "query": "vector database",
      "limit": 10
    }
  }'

Discover Operations:

curl http://localhost:15002/umicp/discover

Supported Operations via UMICP

All 38+ MCP tools are available through UMICP:

  • Collection Management (4): list_collections, create_collection, get_collection_info, delete_collection
  • Vector Operations (6): search, insert_text, embed_text, get_vector, update_vector, delete_vectors
  • Batch Operations (5): batch_insert_texts, insert_texts, batch_search_vectors, batch_update_vectors, batch_delete_vectors
  • Intelligent Search (4): search_intelligent, multi_collection_search, search_semantic, search_extra
  • Discovery Pipeline (9): discover, filter_collections, score_collections, expand_queries, broad_discovery, semantic_focus, compress_evidence, build_answer_plan, render_llm_prompt, promote_readme
  • File Operations (7): get_file_content, list_files, get_file_chunks, get_project_outline, get_related_files, search_by_file_type

Qdrant-Compatible REST API

Vectorizer provides full Qdrant REST API compatibility under the /qdrant prefix for easy migration.

Base URL

http://localhost:15002/qdrant

Collection Management

List Collections

Endpoint: GET /qdrant/collections

Lists all collections in Qdrant format.

Response:

{
  "result": {
    "collections": [
      {
        "name": "my_collection",
        "status": "green"
      }
    ]
  },
  "status": "ok",
  "time": 0.001
}

Get Collection Info

Endpoint: GET /qdrant/collections/{name}

Gets detailed collection information.

Response:

{
  "result": {
    "status": "green",
    "optimizer_status": "ok",
    "vectors_count": 1000,
    "indexed_vectors_count": 1000,
    "points_count": 1000,
    "segments_count": 1,
    "config": {
      "params": {
        "vectors": {
          "size": 384,
          "distance": "Cosine"
        }
      },
      "hnsw_config": {
        "m": 16,
        "ef_construct": 200,
        "full_scan_threshold": 10000
      },
      "optimizer_config": {
        "deleted_threshold": 0.2,
        "vacuum_min_vector_number": 1000,
        "default_segment_number": 0,
        "max_segment_size": null,
        "memmap_threshold": null,
        "indexing_threshold": 20000,
        "flush_interval_sec": 5,
        "max_optimization_threads": 0
      },
      "quantization_config": {
        "scalar": {
          "type": "int8",
          "quantile": 0.99,
          "always_ram": false
        }
      }
    }
  },
  "status": "ok",
  "time": 0.001
}

Create Collection

Endpoint: PUT /qdrant/collections/{name}

Creates a new collection.

Request Body:

{
  "vectors": {
    "size": 384,
    "distance": "Cosine"
  },
  "optimizers_config": {
    "default_segment_number": 2
  },
  "hnsw_config": {
    "m": 16,
    "ef_construct": 200
  },
  "quantization_config": {
    "scalar": {
      "type": "int8",
      "quantile": 0.99
    }
  }
}

Response:

{
  "result": true,
  "status": "ok",
  "time": 0.001
}

Update Collection

Endpoint: PATCH /qdrant/collections/{name}

Updates collection configuration.

Request Body:

{
  "optimizers_config": {
    "indexing_threshold": 10000
  }
}

Delete Collection

Endpoint: DELETE /qdrant/collections/{name}

Deletes a collection.

Response:

{
  "result": true,
  "status": "ok",
  "time": 0.001
}

Point Operations

Upsert Points

Endpoint: PUT /qdrant/collections/{name}/points

Upserts (insert or update) points in a collection.

Request Body:

{
  "points": [
    {
      "id": "point-1",
      "vector": [0.1, 0.2, 0.3, ...],
      "payload": {
        "text": "Document content",
        "category": "docs"
      }
    },
    {
      "id": "point-2",
      "vector": [0.4, 0.5, 0.6, ...],
      "payload": {
        "text": "Another document",
        "category": "tutorial"
      }
    }
  ]
}

Response:

{
  "result": {
    "operation_id": 0,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.001
}

Retrieve Points

Endpoint: GET /qdrant/collections/{name}/points

Retrieves points by IDs.

Query Parameters:

  • ids (required): Comma-separated point IDs or JSON array
  • with_payload (optional): Include payload (default: true)
  • with_vector (optional): Include vector (default: false)

Example:

curl "http://localhost:15002/qdrant/collections/my_collection/points?ids=point-1,point-2&with_payload=true"

Response:

{
  "result": {
    "points": [
      {
        "id": "point-1",
        "payload": {
          "text": "Document content",
          "category": "docs"
        },
        "vector": [0.1, 0.2, 0.3, ...]
      }
    ]
  },
  "status": "ok",
  "time": 0.001
}

Delete Points

Endpoint: POST /qdrant/collections/{name}/points/delete

Deletes points by IDs or filter.

Request Body (by IDs):

{
  "points": ["point-1", "point-2"]
}

Request Body (by filter):

{
  "filter": {
    "must": [
      {
        "key": "category",
        "match": {
          "value": "docs"
        }
      }
    ]
  }
}

Response:

{
  "result": {
    "operation_id": 0,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.001
}

Count Points

Endpoint: POST /qdrant/collections/{name}/points/count

Counts points matching a filter.

Request Body:

{
  "filter": {
    "must": [
      {
        "key": "category",
        "match": {
          "value": "docs"
        }
      }
    ]
  },
  "exact": true
}

Response:

{
  "result": {
    "count": 150
  },
  "status": "ok",
  "time": 0.001
}

Scroll Points

Endpoint: POST /qdrant/collections/{name}/points/scroll

Scrolls through points with pagination.

Request Body:

{
  "filter": {
    "must": [
      {
        "key": "category",
        "match": {
          "value": "docs"
        }
      }
    ]
  },
  "limit": 10,
  "offset": null,
  "with_payload": true,
  "with_vector": false
}

Response:

{
  "result": {
    "points": [
      {
        "id": "point-1",
        "payload": {
          "category": "docs"
        }
      }
    ],
    "next_page_offset": "offset-token"
  },
  "status": "ok",
  "time": 0.001
}

Search Operations

Search Points

Endpoint: POST /qdrant/collections/{name}/points/search

Searches for similar points.

Request Body:

{
  "vector": [0.1, 0.2, 0.3, ...],
  "limit": 10,
  "offset": 0,
  "with_payload": true,
  "with_vector": false,
  "filter": {
    "must": [
      {
        "key": "category",
        "match": {
          "value": "docs"
        }
      }
    ]
  },
  "score_threshold": 0.5
}

Response:

{
  "result": [
    {
      "id": "point-1",
      "score": 0.95,
      "payload": {
        "text": "Document content",
        "category": "docs"
      }
    }
  ],
  "status": "ok",
  "time": 0.001
}

Batch Search

Endpoint: POST /qdrant/collections/{name}/points/search/batch

Performs multiple searches in one request.

Request Body:

{
  "searches": [
    {
      "vector": [0.1, 0.2, 0.3, ...],
      "limit": 5
    },
    {
      "vector": [0.4, 0.5, 0.6, ...],
      "limit": 5
    }
  ]
}

Response:

{
  "result": [
    [
      {"id": "point-1", "score": 0.95, ...},
      {"id": "point-2", "score": 0.92, ...}
    ],
    [
      {"id": "point-3", "score": 0.88, ...}
    ]
  ],
  "status": "ok",
  "time": 0.002
}

Recommend Points

Endpoint: POST /qdrant/collections/{name}/points/recommend

Recommends points based on positive/negative examples.

Request Body:

{
  "positive": ["point-1", "point-2"],
  "negative": ["point-3"],
  "limit": 10,
  "with_payload": true
}

Batch Recommend

Endpoint: POST /qdrant/collections/{name}/points/recommend/batch

Batch recommend operation.

Collection Aliases

Update Aliases

Endpoint: POST /qdrant/collections/aliases

Creates or updates collection aliases.

Request Body:

{
  "actions": [
    {
      "create_alias": {
        "collection_name": "my_collection",
        "alias_name": "my_alias"
      }
    },
    {
      "delete_alias": {
        "alias_name": "old_alias"
      }
    },
    {
      "rename_alias": {
        "old_alias_name": "old_name",
        "new_alias_name": "new_name"
      }
    }
  ]
}

List Collection Aliases

Endpoint: GET /qdrant/collections/{name}/aliases

Lists aliases for a collection.

Response:

{
  "result": {
    "aliases": [
      {
        "alias_name": "my_alias",
        "collection_name": "my_collection"
      }
    ]
  },
  "status": "ok",
  "time": 0.001
}

List All Aliases

Endpoint: GET /qdrant/aliases

Lists all aliases across all collections.

Response:

{
  "result": {
    "aliases": [
      {
        "alias_name": "my_alias",
        "collection_name": "my_collection"
      }
    ]
  },
  "status": "ok",
  "time": 0.001
}

Qdrant Compatibility Notes

  • ✅ Full REST API compatibility with Qdrant v1.x
  • ✅ Collection management (create, get, update, delete, list)
  • ✅ Point operations (upsert, retrieve, delete, count, scroll)
  • ✅ Search operations (search, batch search, recommend, batch recommend)
  • ✅ Collection aliases (create, delete, rename, list)
  • ✅ Payload filtering (must, should, must_not, filter)
  • ⚠️ gRPC not supported (REST API only)
  • ⚠️ Some advanced features may have limitations

Migration from Qdrant

To migrate from Qdrant to Vectorizer:

  1. Change base URL: http://qdrant:6333 → http://vectorizer:15002/qdrant
  2. Keep same request/response format: All Qdrant API calls work as-is
  3. Test thoroughly: Verify all operations work correctly
  4. Consider native APIs: For better performance, migrate to Vectorizer native APIs

File Operations

Get File Content

Endpoint: POST /file/content

List Files in Collection

Endpoint: POST /file/list

Get File Summary

Endpoint: POST /file/summary

Get File Chunks

Endpoint: POST /file/chunks

Get Project Outline

Endpoint: POST /file/outline

Get Related Files

Endpoint: POST /file/related

Search by File Type

Endpoint: POST /file/search_by_type

File Upload Endpoints

The File Upload API allows you to upload files for automatic text extraction, chunking, and indexing into a vector collection. Files are automatically processed, chunked, and embedded using the BM25 provider.

Upload File

Upload a file for automatic indexing into a collection.

Endpoint: POST /files/upload

Content-Type: multipart/form-data

Form Fields:

Field Type Required Description
file File Yes The file to upload
collection_name string Yes Target collection name
chunk_size integer No Chunk size in characters (default: 2048)
chunk_overlap integer No Chunk overlap in characters (default: 256)
metadata string No JSON-encoded metadata to attach to all chunks
use_transmutation string No Enable document conversion ("true" or "false", default: "false"). When enabled, PDF, DOCX, XLSX, PPTX, HTML, XML, and images are automatically converted to Markdown before chunking.
public_key string No Public key for payload encryption (optional)

Response:

{
  "success": true,
  "filename": "example.rs",
  "collection_name": "my_code",
  "chunks_created": 15,
  "vectors_created": 15,
  "file_size": 8192,
  "language": "rust",
  "processing_time_ms": 245
}

Example (curl):

curl -X POST http://localhost:15002/files/upload \
  -F "file=@src/main.rs" \
  -F "collection_name=my_code" \
  -F "chunk_size=1024" \
  -F "chunk_overlap=128"

Example (with metadata):

curl -X POST http://localhost:15002/files/upload \
  -F "file=@document.md" \
  -F "collection_name=docs" \
  -F 'metadata={"project":"vectorizer","version":"1.6.0"}'

Example (with transmutation for PDF):

curl -X POST http://localhost:15002/files/upload \
  -F "file=@document.pdf" \
  -F "collection_name=documents" \
  -F "use_transmutation=true"

When use_transmutation=true, supported formats (PDF, DOCX, XLSX, PPTX, HTML, XML, and images) are automatically converted to Markdown before chunking. This enables proper text extraction from binary document formats. See Document Conversion API for more details.

Supported File Extensions:

Code files: .rs, .py, .js, .ts, .tsx, .jsx, .go, .java, .c, .cpp, .h, .hpp, .cs, .rb, .php, .swift, .kt, .scala, .r, .jl, .lua, .pl, .sh, .bash, .zsh, .fish, .ps1, .bat, .cmd

Documentation: .md, .txt, .rst, .adoc, .org, .tex, .html, .xml, .json, .yaml, .yml, .toml, .ini, .cfg, .conf, .csv, .tsv

Transmutation-supported formats (use use_transmutation=true): .pdf, .docx, .xlsx, .pptx, .html, .htm, .xml, .jpg, .jpeg, .png, .tiff, .tif, .bmp, .gif, .webp

Error Responses:

  • 400 Bad Request - File too large, unsupported extension, or binary file detected
  • 404 Not Found - Collection not found
  • 500 Internal Server Error - Processing error

Get Upload Configuration

Retrieve the server's file upload configuration.

Endpoint: GET /files/config

Response:

{
  "max_file_size": 10485760,
  "max_file_size_mb": 10.0,
  "allowed_extensions": [
    ".rs", ".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".java",
    ".c", ".cpp", ".h", ".hpp", ".cs", ".rb", ".php", ".swift",
    ".kt", ".scala", ".r", ".jl", ".lua", ".pl", ".sh", ".bash",
    ".zsh", ".fish", ".ps1", ".bat", ".cmd", ".md", ".txt",
    ".rst", ".adoc", ".org", ".tex", ".html", ".xml", ".json",
    ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf", ".csv", ".tsv"
  ],
  "reject_binary": true,
  "default_chunk_size": 2048,
  "default_chunk_overlap": 256
}

Example:

curl http://localhost:15002/files/config

Configuration

File upload behavior can be configured in config.yml:

file_upload:
  max_file_size: 10485760      # 10MB in bytes
  allowed_extensions:
    - ".rs"
    - ".py"
    - ".js"
    - ".ts"
    - ".md"
    - ".txt"
    # ... add more extensions as needed
  reject_binary: true           # Reject binary files
  default_chunk_size: 2048      # Characters per chunk
  default_chunk_overlap: 256    # Overlap between chunks

SDK Examples

Python:

from vectorizer import VectorizerClient

client = VectorizerClient(base_url="http://localhost:15002")

# Upload a file
result = await client.upload_file(
    collection_name="my_code",
    file_path="src/main.rs",
    chunk_size=1024,
    chunk_overlap=128,
    metadata={"project": "vectorizer"}
)
print(f"Created {result.vectors_created} vectors")

# Upload content directly
result = await client.upload_file_content(
    collection_name="docs",
    content="# My Documentation\n\nThis is the content...",
    filename="README.md"
)

TypeScript:

import { VectorizerClient } from '@hivellm/vectorizer';

const client = new VectorizerClient({ baseURL: 'http://localhost:15002' });

// Upload a file (browser)
const file = document.querySelector('input[type="file"]').files[0];
const result = await client.uploadFile('my_code', file, file.name, {
  chunkSize: 1024,
  chunkOverlap: 128,
  metadata: { project: 'vectorizer' }
});

// Upload content directly
const result = await client.uploadFileContent(
  'docs',
  '# My Documentation\n\nThis is the content...',
  'README.md'
);

TypeScript / JavaScript:

import { VectorizerClient } from '@hivehub/vectorizer-sdk';

const client = new VectorizerClient({ baseURL: 'http://localhost:15002' });

// Upload a file
const result = await client.uploadFile('my_code', file, 'main.rs', {
  chunkSize: 1024,
  metadata: { author: 'john' }
});

// Get upload configuration
const config = await client.getUploadConfig();
console.log(`Max file size: ${config.max_file_size_mb}MB`);

Troubleshooting

Error: "File too large"

  • Check the max_file_size configuration
  • Default limit is 10MB
  • Increase the limit in config.yml if needed

Error: "Unsupported file extension"

  • Check the allowed_extensions list in configuration
  • Add the extension to config.yml if it's a text-based file

Error: "Binary file detected"

  • The file contains binary content (null bytes, non-text data)
  • Only text-based files are supported
  • Set reject_binary: false to disable this check (not recommended)

Error: "Collection not found"

  • The target collection doesn't exist
  • Create the collection first using POST /collections

Large files processing slowly

  • Reduce chunk_size for faster processing
  • Consider splitting very large files before upload

Discovery Endpoints

Discover

Endpoint: POST /discover

Filter Collections

Endpoint: POST /discovery/filter_collections

Score Collections

Endpoint: POST /discovery/score_collections

Expand Queries

Endpoint: POST /discovery/expand_queries

Broad Discovery

Endpoint: POST /discovery/broad_discovery

Semantic Focus

Endpoint: POST /discovery/semantic_focus

Monitoring Endpoints

Prometheus Metrics

Endpoint: GET /prometheus/metrics

Returns Prometheus-formatted metrics.

Example:

curl http://localhost:15002/prometheus/metrics

Error Codes

Status Code Description
200 Success
400 Bad Request - Invalid input
404 Not Found - Resource doesn't exist
409 Conflict - Resource already exists
500 Internal Server Error

Rate Limiting

Currently, Vectorizer does not implement rate limiting. For production deployments, consider using a reverse proxy with rate limiting.

SDK 3.4+ control surface

Phase12-15 added typed wrappers for every server route across all SDKs. Method names below are case-adjusted per language convention (Rust + Python snake_case, TypeScript camelCase, Go/C# PascalCase).

Vector ops + batch

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
POST /update update_vector updateVector update_vector UpdateVector UpdateVectorAsync
POST /insert insert_text insertText insert_text InsertText InsertTextAsync
GET /collections/{n}/vectors list_vectors listVectors list_vectors ListVectors ListVectorsAsync
GET /collections/{n}/vectors/{id} get_vector_by_path getVectorByPath get_vector_by_path GetVector GetVectorAsync
POST /batch_insert batch_insert_texts batchInsertTexts batch_insert_texts BatchInsertTexts BatchInsertRawTextsAsync
POST /insert_vectors insert_vectors insertVectors insert_vectors InsertVectors InsertVectorsAsync
POST /batch_search batch_search batchSearchVectors batch_search_vectors BatchSearchQueries BatchSearchQueriesAsync
POST /batch_update batch_update_vectors batchUpdateVectors batch_update_vectors BatchUpdateVectors BatchUpdateRawVectorsAsync

Search + discovery pipeline

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
POST /collections/{n}/search/text search_vectors_by_text searchVectorsByText search_vectors_by_text SearchByText SearchByTextAsync
POST /collections/{n}/search/file search_by_file searchByFile search_by_file SearchByFile SearchByFileAsync
POST /collections/{n}/hybrid_search hybrid_search hybridSearch hybrid_search HybridSearch HybridSearchAsync
POST /discovery/broad_discovery broad_discovery broadDiscovery broad_discovery BroadDiscovery BroadDiscoveryAsync
POST /discovery/semantic_focus semantic_focus semanticFocus semantic_focus SemanticFocus SemanticFocusAsync
POST /discovery/promote_readme promote_readme promoteReadme promote_readme PromoteReadme PromoteReadmeAsync
POST /discovery/compress_evidence compress_evidence compressEvidence compress_evidence CompressEvidence CompressEvidenceAsync
POST /discovery/build_answer_plan build_answer_plan buildAnswerPlan build_answer_plan BuildAnswerPlan BuildAnswerPlanAsync
POST /discovery/render_llm_prompt render_llm_prompt renderLlmPrompt render_llm_prompt RenderLlmPrompt RenderLlmPromptAsync

Admin + observability

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
GET /stats get_stats getStats get_stats GetServerStats GetServerStatsAsync
GET /status get_status getStatus get_status GetStatus GetStatusAsync
GET /logs get_logs getLogs get_logs GetLogs GetLogsAsync
GET /indexing/progress get_indexing_progress getIndexingProgress get_indexing_progress GetIndexingProgress GetIndexingProgressAsync
POST /collections/{n}/force-save force_save_collection forceSaveCollection force_save_collection ForceSaveCollection ForceSaveCollectionAsync
GET /collections/empty list_empty_collections listEmptyCollections list_empty_collections ListEmptyCollections ListEmptyCollectionsAsync
DELETE /collections/cleanup cleanup_empty_collections cleanupEmptyCollections cleanup_empty_collections CleanupEmptyCollections CleanupEmptyCollectionsAsync
GET /config get_config getConfig get_config GetConfig GetConfigAsync
POST /config (admin) update_config updateConfig update_config UpdateConfig UpdateConfigAsync
GET /backups list_backups listBackups list_backups ListBackups ListBackupsAsync
POST /backups/create (admin) create_backup createBackup create_backup CreateBackup CreateBackupAsync
POST /backups/restore (admin) restore_backup restoreBackup restore_backup RestoreBackup RestoreBackupAsync
POST /admin/restart (admin) restart_server restartServer restart_server RestartServer RestartServerAsync
GET /workspace/list list_workspaces listWorkspaces list_workspaces ListWorkspaces ListWorkspacesAsync
GET /workspace/config get_workspace_config getWorkspaceConfig get_workspace_config GetWorkspaceConfig GetWorkspaceConfigAsync
POST /workspace/add (admin) add_workspace addWorkspace add_workspace AddWorkspace AddWorkspaceAsync
POST /workspace/remove (admin) remove_workspace removeWorkspace remove_workspace RemoveWorkspace RemoveWorkspaceAsync

Auth

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
GET /auth/me me me me Me MeAsync
POST /auth/logout logout logout logout Logout LogoutAsync
POST /auth/refresh refresh_token refreshToken refresh_token RefreshToken RefreshTokenAsync
POST /auth/validate-password validate_password validatePassword validate_password ValidatePassword ValidatePasswordAsync
POST /auth/keys create_api_key createApiKey create_api_key CreateApiKey CreateApiKeyAsync
GET /auth/keys list_api_keys listApiKeys list_api_keys ListApiKeys ListApiKeysAsync
DELETE /auth/keys/{id} revoke_api_key revokeApiKey revoke_api_key RevokeApiKey RevokeApiKeyAsync
POST /auth/users (admin) create_user createUser create_user CreateUser CreateUserAsync
GET /auth/users (admin) list_users listUsers list_users ListUsers ListUsersAsync
DELETE /auth/users/{u} (admin) delete_user deleteUser delete_user DeleteUser DeleteUserAsync
PUT /auth/users/{u}/password change_password changePassword change_password ChangePassword ChangePasswordAsync

Replication

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
GET /replication/status get_replication_status getReplicationStatus get_replication_status GetReplicationStatus GetReplicationStatusAsync
POST /replication/configure configure_replication configureReplication configure_replication ConfigureReplication ConfigureReplicationAsync
GET /replication/stats get_replication_stats getReplicationStats get_replication_stats GetReplicationStats GetReplicationStatsAsync
GET /replication/replicas list_replicas listReplicas list_replicas ListReplicas ListReplicasAsync

Hub backups + usage

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
GET /hub/backups list_user_backups listUserBackups list_user_backups ListUserBackups ListUserBackupsAsync
POST /hub/backups create_user_backup createUserBackup create_user_backup CreateUserBackup CreateUserBackupAsync
POST /hub/backups/restore restore_user_backup restoreUserBackup restore_user_backup RestoreUserBackup RestoreUserBackupAsync
POST /hub/backups/upload upload_user_backup uploadUserBackup upload_user_backup UploadUserBackup UploadUserBackupAsync
GET /hub/backups/{id} get_user_backup getUserBackup get_user_backup GetUserBackup GetUserBackupAsync
DELETE /hub/backups/{id} delete_user_backup deleteUserBackup delete_user_backup DeleteUserBackup DeleteUserBackupAsync
GET /hub/backups/{id}/download download_user_backup downloadUserBackup download_user_backup DownloadUserBackup DownloadUserBackupAsync
GET /hub/usage/statistics get_usage_statistics getUsageStatistics get_usage_statistics GetUsageStatistics GetUsageStatisticsAsync
GET /hub/usage/quota get_quota_info getQuotaInfo get_quota_info GetQuotaInfo GetQuotaInfoAsync
POST /hub/validate-key validate_hub_api_key validateHubApiKey validate_hub_api_key ValidateHubAPIKey ValidateHubApiKeyAsync

Tier control (phase13)

The delete_by_filter and bulk_update_metadata endpoints accept a filter body field. See Filter shape below for the complete wire contract and JSON examples.

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
POST /collections/{n}/vectors/delete_by_filter delete_by_filter deleteByFilter delete_by_filter DeleteByFilter DeleteByFilterAsync
POST /collections/{n}/vectors/bulk_update_metadata bulk_update_metadata bulkUpdateMetadata bulk_update_metadata BulkUpdateMetadata BulkUpdateMetadataAsync
POST /collections/{src}/vectors/copy copy_vectors copyVectors copy_vectors CopyVectors CopyVectorsAsync
POST /collections/{n}/reencode reencode_collection reencodeCollection reencode_collection ReencodeCollection ReencodeCollectionAsync
POST /collections/{n}/ttl set_collection_ttl setCollectionTtl set_collection_ttl SetCollectionTTL SetCollectionTtlAsync
PATCH /collections/{n}/vectors/{id}/expiry set_vector_expiry setVectorExpiry set_vector_expiry SetVectorExpiry SetVectorExpiryAsync

Filter shape

Both delete_by_filter and bulk_update_metadata send their filter in a top-level "filter" JSON field. The server deserializes it as a Qdrant-compatible filter with three optional boolean clauses: must (AND), should (OR), must_not (NOT). At least one clause must be present and non-empty; an all-absent filter returns 400 validation_error with message "filter has no conditions".

Top-level shape:

{
  "filter": {
    "must":     [ <condition>, ... ],
    "should":   [ <condition>, ... ],
    "must_not": [ <condition>, ... ]
  }
}

All three arrays are optional; omit any you don't need. A request with "filter": {} (all arrays absent) is rejected as "filter has no conditions".

Condition types

Each element of a must/should/must_not array is a typed condition object. The "type" discriminant field is required; omitting it produces 400 parse_error with reason "missing field type".

match — exact value match

{ "type": "match", "key": "topic", "match_value": "index" }
{ "type": "match", "key": "active", "match_value": true }
{ "type": "match", "key": "count",  "match_value": 42 }

The match_value field accepts a JSON string, integer, or boolean.

range — numeric range on a payload field

{
  "type": "range",
  "key": "score",
  "range": { "gte": 0.5, "lt": 0.9 }
}

Available range operators (all optional, combined with AND):

Field Meaning
gt strictly greater than
gte greater than or equal
lt strictly less than
lte less than or equal

values_count — count of array elements in a payload field

{
  "type": "values_count",
  "key": "tags",
  "values_count": { "gte": 1, "lte": 5 }
}

Same operator sub-fields as range (gt, gte, lt, lte), but with unsigned-integer values.

geo_bounding_box — geospatial bounding box

{
  "type": "geo_bounding_box",
  "key": "location",
  "geo_bounding_box": {
    "top_right":   { "lat": 48.9, "lon": 2.4 },
    "bottom_left": { "lat": 48.8, "lon": 2.3 }
  }
}

geo_radius — geospatial radius

{
  "type": "geo_radius",
  "key": "location",
  "geo_radius": {
    "center": { "lat": 48.85, "lon": 2.35 },
    "radius": 500.0
  }
}

radius is in metres.

nested — sub-filter applied to a nested object payload field

{
  "type": "nested",
  "filter": {
    "must": [ { "type": "match", "key": "inner_key", "match_value": "value" } ]
  }
}

Full examples

Delete all vectors where topic == "index":

{
  "filter": {
    "must": [
      { "type": "match", "key": "topic", "match_value": "index" }
    ]
  }
}

Delete all vectors where tier == "hot" AND score >= 0.8:

{
  "filter": {
    "must": [
      { "type": "match", "key": "tier",  "match_value": "hot" },
      { "type": "range", "key": "score", "range": { "gte": 0.8 } }
    ]
  }
}

Update metadata for vectors where status == "draft" OR status == "review":

{
  "filter": {
    "should": [
      { "type": "match", "key": "status", "match_value": "draft" },
      { "type": "match", "key": "status", "match_value": "review" }
    ]
  }
}

Common mistakes

Wrong shape Problem Correct shape
{"key": "topic", "topic": "index"} Flat key=value map — the server does not accept this format. Produces parse_error. {"must": [{"type": "match", "key": "topic", "match_value": "index"}]}
{"must": [{"key": "topic", "match": {"value": "index"}}]} Qdrant-client style (match sub-object) — the Vectorizer server uses a flat match_value field, not a nested match object. Produces parse_error: missing field 'type'. {"must": [{"type": "match", "key": "topic", "match_value": "index"}]}
{} All-absent filter — rejected to prevent accidental full-collection wipes. Produces validation_error: filter has no conditions. Always include at least one must, should, or must_not array with at least one condition.

Error responses for filter parsing

Status error_type When
400 parse_error Filter JSON does not match the QdrantFilter schema (wrong shape, missing "type" discriminant, wrong value type). The details.reason field carries the verbatim serde error with field path.
400 validation_error Filter parsed successfully but has no conditions (all arrays absent or empty).

Schema evolution + explain + slow queries (phase14)

POST /collections/{name}/rename — error responses (phase22)

Status error_type When
200 — Success. Body: {old_name, new_name, alias_retained, status:"ok"}. The old name keeps resolving via an in-memory grace-window alias.
400 validation_error new_name missing/empty, contains /, or equals the source name
404 collection_not_found Source collection does not exist
409 collection_already_exists Destination name is already taken (collection or alias)
500 persistence_error Underlying storage write failed
Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
POST /collections/{n}/rename rename_collection renameCollection rename_collection RenameCollection RenameCollectionAsync
POST /collections/{n}/reindex reindex_collection reindexCollection reindex_collection ReindexCollection ReindexCollectionAsync
POST /collections/{n}/snapshot snapshot_collection_native snapshotCollectionNative snapshot_collection_native SnapshotCollectionNative SnapshotCollectionNativeAsync
GET /collections/{n}/snapshots list_collection_snapshots_native listCollectionSnapshotsNative list_collection_snapshots_native ListCollectionSnapshotsNative ListCollectionSnapshotsNativeAsync
POST /collections/{n}/snapshots/{id}/restore restore_collection_snapshot_native restoreCollectionSnapshotNative restore_collection_snapshot_native RestoreCollectionSnapshotNative RestoreCollectionSnapshotNativeAsync
POST /collections/{n}/explain explain_search explainSearch explain_search ExplainSearch ExplainSearchAsync
GET /slow_queries list_slow_queries listSlowQueries list_slow_queries ListSlowQueries ListSlowQueriesAsync
POST /slow_queries/config set_slow_query_config setSlowQueryConfig set_slow_query_config SetSlowQueryConfig SetSlowQueryConfigAsync

Cluster + auth admin (phase15)

Server route Rust SDK TypeScript SDK Python SDK Go SDK C# SDK
POST /cluster/failover cluster_failover clusterFailover cluster_failover ClusterFailover ClusterFailoverAsync
POST /cluster/replicas/{id}/resync cluster_resync_replica clusterResyncReplica cluster_resync_replica ClusterResyncReplica ClusterResyncReplicaAsync
POST /cluster/peers cluster_add_peer clusterAddPeer cluster_add_peer ClusterAddPeer ClusterAddPeerAsync
POST /cluster/rebalance cluster_rebalance clusterRebalance cluster_rebalance ClusterRebalance ClusterRebalanceAsync
GET /cluster/rebalance/status cluster_rebalance_status clusterRebalanceStatus cluster_rebalance_status ClusterRebalanceStatus ClusterRebalanceStatusAsync
POST /auth/keys/{id}/rotate rotate_api_key rotateApiKey rotate_api_key RotateApiKey RotateApiKeyAsync
POST /auth/keys (scoped) create_scoped_api_key createScopedApiKey create_scoped_api_key CreateScopedApiKey CreateScopedApiKeyAsync
POST /auth/introspect introspect_token introspectToken introspect_token IntrospectToken IntrospectTokenAsync
GET /auth/audit list_audit_log listAuditLog list_audit_log ListAuditLog ListAuditLogAsync

Related Topics