Qdrant API

Use the Qdrant REST API via direct curl calls to store and search vector embeddings for RAG, semantic search, and recommendations.

Official docs: https://qdrant.tech/documentation/

When to Use

Use this skill when you need to:

Store vector embeddings for semantic search
Search for similar vectors using cosine, dot product, or euclidean distance
Build RAG applications with retrieval from vector store
Implement recommendations based on similarity
Filter search results by metadata/payload

Prerequisites

Option 1: Qdrant Cloud (Recommended)

Sign up at Qdrant Cloud
Create a cluster and get your URL and API key
Store credentials in environment variables

export QDRANT_URL="https://xyz-example.aws.cloud.qdrant.io:6333"
export QDRANT_API_KEY="your-api-key"

Option 2: Self-hosted

Run Qdrant locally with Docker:

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

export QDRANT_URL="http://localhost:6333"
export QDRANT_API_KEY="" # Optional for local

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

All examples below assume you have QDRANT_URL and QDRANT_API_KEY set.

1. Check Server Status

Verify connection to Qdrant:

bash -c 'curl -s -X GET "${QDRANT_URL}" --header "api-key: ${QDRANT_API_KEY}"' | jq .

2. List Collections

Get all collections:

bash -c 'curl -s -X GET "${QDRANT_URL}/collections" --header "api-key: ${QDRANT_API_KEY}"' | jq .

3. Create a Collection

Create a collection for storing vectors:

bash -c 'curl -s -X PUT "${QDRANT_URL}/collections/my_collection" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "vectors": {
  "size": 1536,
  "distance": "Cosine"
  }
  }'"'"' | jq .'

Distance metrics:

Cosine - Cosine similarity (recommended for normalized vectors)
Dot - Dot product
Euclid - Euclidean distance
Manhattan - Manhattan distance

Common vector sizes:

OpenAI text-embedding-3-small: 1536
OpenAI text-embedding-3-large: 3072
Cohere: 1024

4. Get Collection Info

Get details about a collection:

bash -c 'curl -s -X GET "${QDRANT_URL}/collections/my_collection" --header "api-key: ${QDRANT_API_KEY}"' | jq .

5. Upsert Points (Insert/Update Vectors)

Add vectors with payload (metadata):

bash -c 'curl -s -X PUT "${QDRANT_URL}/collections/my_collection/points" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "points": [
  {
  "id": 1,
  "vector": [0.05, 0.61, 0.76, 0.74],
  "payload": {"text": "Hello world", "source": "doc1"}
  },
  {
  "id": 2,
  "vector": [0.19, 0.81, 0.75, 0.11],
  "payload": {"text": "Goodbye world", "source": "doc2"}
  }
  ]
  }'"'"' | jq .'

6. Search Similar Vectors

Find vectors similar to a query vector:

bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/query" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "query": [0.05, 0.61, 0.76, 0.74],
  "limit": 5,
  "with_payload": true
  }'"'"' | jq .'

Response:

{
  "result": {
  "points": [
  {"id": 1, "score": 0.99, "payload": {"text": "Hello world"}}
  ]
  }
}

7. Search with Filters

Filter results by payload fields:

bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/query" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "query": [0.05, 0.61, 0.76, 0.74],
  "limit": 5,
  "filter": {
  "must": [
  {"key": "source", "match": {"value": "doc1"}}
  ]
  },
  "with_payload": true
  }'"'"' | jq .'

Filter operators:

must - All conditions must match (AND)
should - At least one must match (OR)
must_not - None should match (NOT)

8. Get Points by ID

Retrieve specific points:

bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "ids": [1, 2],
  "with_payload": true,
  "with_vector": true
  }'"'"' | jq .'

9. Delete Points

Delete by IDs:

bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/delete" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "points": [1, 2]
  }'"'"' | jq .'

Delete by filter:

bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/delete" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "filter": {
  "must": [
  {"key": "source", "match": {"value": "doc1"}}
  ]
  }
  }'"'"' | jq .'

10. Delete Collection

Remove a collection entirely:

bash -c 'curl -s -X DELETE "${QDRANT_URL}/collections/my_collection" --header "api-key: ${QDRANT_API_KEY}"' | jq .

11. Count Points

Get total count or filtered count:

bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/count" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d '"'"'{
  "exact": true
  }'"'"' | jq .'

Filter Syntax

Common filter conditions:

{
  "filter": {
  "must": [
  {"key": "city", "match": {"value": "London"}},
  {"key": "price", "range": {"gte": 100, "lte": 500}},
  {"key": "tags", "match": {"any": ["electronics", "sale"]}}
  ]
  }
}

Match types:

match.value - Exact match
match.any - Match any in list
match.except - Match none in list
range - Numeric range (gt, gte, lt, lte)

Guidelines

Match vector size: Collection vector size must match your embedding model output
Use Cosine for normalized vectors: Most embedding models output normalized vectors
Add payload for filtering: Store metadata with vectors for filtered searches
Batch upserts: Insert multiple points in one request for efficiency
Use score_threshold: Filter out low-similarity results in search

qdrant