HTTP API Reference

REST endpoints for vector search, file upload, and collection management

Base URL

https://api.vectorpanda.com

All endpoints are served from this base URL.

Authentication

The API uses API keys for authentication. Authentication method varies by endpoint:

Endpoint Auth method
POST /api/query api_key field in JSON body
All /api/v1/ endpoints Authorization: Bearer <api_key> header
GET /health None

Errors

Errors return a JSON body with an error field. 

{
    "error": "Invalid API key"
}
Status Meaning
400 Bad request (invalid distance metric, malformed body)
401 Invalid or missing API key
404 Collection or file not found
402 Payment required (hot tier needs payment method)
429 Rate limit exceeded. Check Retry-After header
503 Service unavailable (no workers, queue full)

Rate limits

Rate limits are per API key. When exceeded, the server returns 429 with a Retry-After header indicating seconds to wait.

Tier Queries/sec Uploads/min
Free105
Warm5020
Hot20060

POST /api/query

Search a collection for similar vectors.

Request body (JSON)

Field Type Required Default Description
api_key string yes Your API key
collection string yes Collection name
vector float[] yes Query vector
top_k integer no 1000 Maximum results
similarity_threshold float no 0.7 Minimum similarity score
distance_metric string no "cosine" "cosine", "euclidean", or "dot_product"
include_metadata boolean no false Include metadata in results
use_index string no null Index type (e.g. "pca")
index_params object no null Index-specific parameters

Example request

curl -X POST https://api.vectorpanda.com/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_your_key",
    "collection": "products",
    "vector": [0.1, 0.2, 0.3],
    "top_k": 5,
    "similarity_threshold": 0.8,
    "distance_metric": "cosine",
    "include_metadata": true
  }'

Response (200)

{
    "results": [
        {
            "key": "product_42",
            "score": 0.9534,
            "metadata": {
                "name": "Widget Pro",
                "price": 29.99
            }
        },
        {
            "key": "product_17",
            "score": 0.9102,
            "metadata": {
                "name": "Widget Basic",
                "price": 14.99
            }
        }
    ],
    "worker_stats": [
        {"worker_id": "w1", "vectors_scanned": 50000, "duration_ms": 12}
    ]
}

Results are sorted by score descending. The worker_stats array shows per-worker scan metrics for performance debugging.

POST /api/v1/collections/{collection}/files/{filename}

Upload a vector file to a collection. The file body is sent as raw binary. Supported formats: Parquet (.parquet), CSV (.csv), and binary vectors (.fvecs, .bvecs, .ivecs). Format is detected from the filename extension.

Headers

Header Value
Authorization Bearer <api_key>
Content-Type application/octet-stream

Path parameters

Parameter Description
collection Collection name
filename File name (alphanumeric, dots, hyphens, underscores)

Example request

curl -X POST https://api.vectorpanda.com/api/v1/collections/products/files/embeddings.parquet \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @embeddings.parquet

Response (201)

{
    "status": "uploaded",
    "collection": "products",
    "file": "embeddings.parquet",
    "bytes": 4821504
}
Ingestion is automatic

After upload, the file is automatically detected by the ingestion pipeline, processed, and distributed to workers. Vectors become queryable within seconds.

DELETE /api/v1/collections/{collection}/files/{filename}

Delete a previously uploaded file from a collection.

Headers

Header Value
Authorization Bearer <api_key>

Example request

curl -X DELETE https://api.vectorpanda.com/api/v1/collections/products/files/embeddings.parquet \
  -H "Authorization: Bearer sk_live_your_key"

Response (200)

{
    "status": "deleted",
    "collection": "products",
    "file": "embeddings.parquet"
}

GET /api/v1/collections

List all collections accessible to your API key.

Headers

Header Value
Authorization Bearer <api_key>

Example request

curl https://api.vectorpanda.com/api/v1/collections \
  -H "Authorization: Bearer sk_live_your_key"

Response (200)

{
    "collections": [
        {
            "collection_name": "products",
            "tier": "hot",
            "is_active": true,
            "vector_count": 150000,
            "storage_gb": 2.34
        }
    ]
}

GET /health

Health check. No authentication required.

Example request

curl https://api.vectorpanda.com/health

Response (200)

OK

Returns plain text OK with status 200 if the service is running.