API Reference

Complete API documentation for Aetherfy. 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
idnumber | stringYesPoint identifier — an unsigned integer (≤ 2^53 − 1) or a UUID string
vectornumber[]YesDense vector embeddings
payloadobjectNoAdditional data to store with the point

Example Request

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

Example Response

// upsert() resolves to true on success
true
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', queryEmbedding, {
  limit: 10,
  withPayload: true,
  queryFilter: {
    must: [
      { key: 'agent_id', match: { value: 'claude' } },
      { key: 'timestamp', range: { gte: Date.now() - 86400000 } }
    ]
  }
})

Example Response

// search() resolves to an array of SearchResult
[
  {
    "id": 123,
    "score": 0.95,
    "payload": { "agent_id": "claude" }
  }
]
POST/collections

Create a new vector collection

Parameters

NameTypeRequiredDescription
sizenumberYesDimension of vectors in this collection
distancestringYesDistanceMetric.COSINE, .EUCLIDEAN, or .DOT
indexobjectNoIndex configuration options

Example Request

JavaScript SDK
await client.createCollection('agent-memory', {
  size: 1536,
  distance: DistanceMetric.COSINE
})

Example Response

// createCollection() resolves to the Collection
{
  "name": "agent-memory",
  "config": { "size": 1536, "distance": "Cosine" },
  "pointsCount": 0,
  "status": "green"
}
GET/collections/{collection}/retrieve

Retrieve specific vectors by ID

Parameters

NameTypeRequiredDescription
ids(number | string)[]YesPoint IDs to retrieve — unsigned integers or UUID strings
withVectorsbooleanNoInclude vector data in response
withPayloadbooleanNoInclude payload in response

Example Request

JavaScript SDK
const vectors = await client.retrieve('memories', [123, 124], {
  withVectors: true,
  withPayload: true
})

Example Response

// retrieve() resolves to an array of Point
[
  {
    "id": 123,
    "vector": [0.1, 0.2],
    "payload": { "agent_id": "claude" }
  }
]

Advanced Filtering & Query Patterns

Aetherfy 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', queryVector, {
  limit: 10,
  queryFilter: {
    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', queryVector, {
  queryFilter: {
    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', queryVector, {
  queryFilter: {
    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', queryVector, {
  queryFilter: {
    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', queryVector, {
  queryFilter: {
    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', queryVector, {
  queryFilter: {
    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