Aetherfy Logo

API Reference

Complete API documentation for VectorsDB. Compatible with qdrant-client for easy migration.

Qdrant Compatible

Drop-in replacement for existing Qdrant code

Global Edge

Automatic routing to nearest region

Rate Limits

10,000 requests/minute per key

POST/collections/{collection}/upsert

Insert or update vectors in a collection

Parameters

NameTypeRequiredDescription
idstringYesUnique identifier for the vector
vectornumber[]YesDense vector embeddings
metadataobjectNoAdditional data to store with vector

Example Request

JavaScript SDK
const response = await client.upsert('memories', {
  id: 'conv-123',
  vector: [0.1, 0.2, 0.3, ...],
  metadata: {
    agent_id: 'claude',
    timestamp: Date.now(),
    type: 'conversation'
  }
})

Example Response

{
  "status": "success",
  "operation_id": "op_123",
  "points_processed": 1
}
POST/collections/{collection}/search

Perform similarity search with optional filtering

Parameters

NameTypeRequiredDescription
vectornumber[]YesQuery vector for similarity search
limitnumberNoMaximum number of results (default: 10)
filterobjectNoMetadata filtering conditions

Example Request

JavaScript SDK
const results = await client.search('memories', {
  vector: queryEmbedding,
  limit: 10,
  filter: {
    agent_id: 'claude',
    timestamp: { $gte: Date.now() - 86400000 }
  }
})

Example Response

{
  "results": [
    {
      "id": "conv-123",
      "score": 0.95,
      "metadata": { ... }
    }
  ],
  "latency_ms": 47
}
POST/collections

Create a new vector collection

Parameters

NameTypeRequiredDescription
vector_sizenumberYesDimension of vectors in this collection
distancestringYesDistance metric: cosine, euclidean, or dot
indexobjectNoIndex configuration options

Example Request

JavaScript SDK
await client.createCollection('agent-memory', {
  vector_size: 1536,
  distance: 'cosine',
  index: {
    type: 'hnsw',
    m: 16,
    ef_construct: 100
  }
})

Example Response

{
  "status": "success",
  "collection": "agent-memory",
  "created_at": "2025-01-20T10:30:00Z"
}
GET/collections/{collection}/retrieve

Retrieve specific vectors by ID

Parameters

NameTypeRequiredDescription
idsstring[]YesArray of vector IDs to retrieve
with_vectorbooleanNoInclude vector data in response
with_metadatabooleanNoInclude metadata in response

Example Request

JavaScript SDK
const vectors = await client.retrieve('memories', {
  ids: ['conv-123', 'conv-124'],
  with_vector: true,
  with_metadata: true
})

Example Response

{
  "vectors": [
    {
      "id": "conv-123",
      "vector": [0.1, 0.2, ...],
      "metadata": { ... }
    }
  ]
}

Advanced Filtering & Query Patterns

VectorsDB supports powerful Qdrant-compatible filtering for precise vector searches. Combine similarity search with metadata filtering for optimal results.

Basic Filtering Examples

Match Specific Values
Find documents by category
// Find all documents with category "research"
const results = await client.search('knowledge-base', {
  vector: queryVector,
  limit: 10,
  filter: {
    must: [
      { key: "category", match: { value: "research" } }
    ]
  }
})
Multiple Conditions (AND)
Find active user conversations
// Find conversations for specific user that are still active
const results = await client.search('conversations', {
  vector: queryVector,
  filter: {
    must: [
      { key: "user_id", match: { value: "user_123" } },
      { key: "status", match: { value: "active" } }
    ]
  }
})
Multiple Options (OR)
Find images or videos
// Find content that is either image or video
const results = await client.search('media', {
  vector: queryVector,
  filter: {
    should: [
      { key: "type", match: { value: "image" } },
      { key: "type", match: { value: "video" } }
    ]
  }
})
Exclude Results (NOT)
Exclude deleted content
// Find content but exclude deleted items
const results = await client.search('content', {
  vector: queryVector,
  filter: {
    must_not: [
      { key: "status", match: { value: "deleted" } }
    ]
  }
})
Range Queries
Find recent content
// Find content from the last 7 days
const lastWeek = Date.now() - (7 * 24 * 60 * 60 * 1000);
const results = await client.search('content', {
  vector: queryVector,
  filter: {
    must: [
      { 
        key: "created_at", 
        range: { gte: lastWeek } 
      }
    ]
  }
})
Complex Nested Queries
Advanced filtering
// Complex query: active user content (images OR videos) from last week
const results = await client.search('user-content', {
  vector: queryVector,
  filter: {
    must: [
      { key: "user_id", match: { value: "user_123" } },
      { key: "status", match: { value: "active" } },
      { 
        key: "created_at", 
        range: { gte: Date.now() - (7 * 24 * 60 * 60 * 1000) } 
      }
    ],
    should: [
      { key: "type", match: { value: "image" } },
      { key: "type", match: { value: "video" } }
    ],
    must_not: [
      { key: "flagged", match: { value: true } }
    ]
  }
})

Additional SDK Methods

Collection Management

  • • listCollections() - List all collections
  • • deleteCollection(name) - Delete a collection
  • • getCollection(name) - Get collection info

Vector Operations

  • • delete(collection, ids) - Delete vectors
  • • scroll(collection, options) - Paginate vectors
  • • count(collection, filter) - Count vectors