API Reference

GoVector provides a Qdrant-compatible REST API for managing vector collections and performing similarity search. This document provides a comprehensive reference for all API endpoints, request/response formats, and usage examples.

📡 API Endpoints

Collection Management

Method	Endpoint	Description
POST	/collections	Create a new collection
DELETE	/collections/{name}	Delete a collection
GET	/collections	List all collections
GET	/collections/{name}	Get collection information

Point Operations

Method	Endpoint	Description
PUT	/collections/{name}/points	Upsert points
POST	/collections/{name}/points/search	Search for similar vectors
POST	/collections/{name}/points/delete	Delete points

📝 Endpoint Details

POST /collections

Create a new collection with specified configuration.

Request Body:

{
  "name": "documents",
  "vector_size": 384,
  "distance": "cosine",
  "hnsw": true,
  "parameters": {
    "m": 16,
    "ef_construction": 100,
    "ef_search": 10,
    "k": 10
  }
}

Parameters: - name: (required) Name of the collection - vector_size: (required) Vector dimension - distance: (required) Distance metric, supports "cosine", "euclidean", "dot" - hnsw: (optional) Whether to enable HNSW index (default: true) - parameters: (optional) HNSW index parameters

Response:

{
  "status": "ok",
  "result": {
    "name": "documents",
    "vector_size": 384,
    "distance": "cosine",
    "hnsw": true,
    "parameters": {
      "m": 16,
      "ef_construction": 100,
      "ef_search": 10,
      "k": 10
    },
    "operation": "completed"
  }
}

Errors: - 400 Bad Request: Invalid parameters - 409 Conflict: Collection already exists - 500 Internal Server Error: Internal error

DELETE /collections/{name}

Delete a collection and all its data.

Response:

{
  "status": "ok",
  "result": {
    "operation": "completed",
    "collection": "documents"
  }
}

Errors: - 404 Not Found: Collection does not exist

GET /collections

List all collections with basic information.

Response:

{
  "status": "ok",
  "result": [
    {
      "name": "documents",
      "vector_size": 384,
      "distance": "cosine",
      "points_count": 100
    }
  ]
}

GET /collections/{name}

Get detailed information about a collection.

Response:

{
  "status": "ok",
  "result": {
    "name": "documents",
    "vector_size": 384,
    "distance": "cosine",
    "points_count": 100
  }
}

Errors: - 404 Not Found: Collection does not exist

PUT /collections/{name}/points

Upsert points into a collection.

Request Body:

{
  "points": [
    {
      "id": "doc_1",
      "vector": [0.1, 0.2, 0.3, /* ... */],
      "payload": {"category": "tech", "author": "John"}
    }
  ]
}

Response:

{
  "status": "ok",
  "result": {
    "operation": "completed"
  }
}

Errors: - 400 Bad Request: Invalid parameters - 404 Not Found: Collection does not exist

POST /collections/{name}/points/search

Search for similar vectors.

Request Body:

{
  "vector": [0.1, 0.2, 0.3, /* ... */],
  "filter": {
    "must": [
      {
        "key": "category",
        "type": "exact",
        "match": {"value": "tech"}
      }
    ]
  },
  "limit": 10
}

Response:

{
  "status": "ok",
  "result": [
    {
      "id": "doc_1",
      "score": 0.999,
      "payload": {"category": "tech", "author": "John"}
    }
  ]
}

Errors: - 400 Bad Request: Invalid parameters - 404 Not Found: Collection does not exist

POST /collections/{name}/points/delete

Delete points by ID or filter.

Request Body (by ID):

{
  "points": ["doc_1", "doc_2"]
}

Request Body (by filter):

{
  "filter": {
    "must": [
      {
        "key": "category",
        "type": "exact",
        "match": {"value": "tech"}
      }
    ]
  }
}

Response:

{
  "status": "ok",
  "result": {
    "operation": "completed",
    "deleted": 2
  }
}

Errors: - 400 Bad Request: Invalid parameters - 404 Not Found: Collection does not exist

📊 Data Models

Point

{
  "id": "doc_1",
  "vector": [0.1, 0.2, 0.3],
  "payload": {"category": "tech", "author": "John"}
}

Scored Point

{
  "id": "doc_1",
  "score": 0.999,
  "payload": {"category": "tech", "author": "John"}
}

Filter

{
  "must": [
    {
      "key": "category",
      "type": "exact",
      "match": {"value": "tech"}
    },
    {
      "key": "age",
      "type": "range",
      "range": {"gte": 18, "lte": 30}
    }
  ],
  "must_not": [
    {
      "key": "status",
      "type": "exact",
      "match": {"value": "inactive"}
    }
  ]
}

Condition Types

• exact: Exact value match
• range: Range comparison (gt, gte, lt, lte)
• prefix: Prefix match (strings)
• contains: Contains match (arrays or strings)
• regex: Regular expression match (strings)

🚀 Usage Examples

Create Collection

curl -X POST http://localhost:18080/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "documents",
    "vector_size": 384,
    "distance": "cosine",
    "hnsw": true
  }'

Upsert Points

curl -X PUT http://localhost:18080/collections/documents/points \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "id": "doc_1",
        "vector": [0.1, 0.2, 0.3, /* ... 384 dimensions ... */],
        "payload": {"category": "tech", "author": "John"}
      },
      {
        "id": "doc_2",
        "vector": [0.4, 0.5, 0.6, /* ... 384 dimensions ... */],
        "payload": {"category": "business", "author": "Jane"}
      }
    ]
  }'

Search Vectors

curl -X POST http://localhost:18080/collections/documents/points/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.15, 0.25, 0.35, /* ... 384 dimensions ... */],
    "filter": {
      "must": [
        {
          "key": "category",
          "type": "exact",
          "match": {"value": "tech"}
        }
      ]
    },
    "limit": 10
  }'

Delete Points

curl -X POST http://localhost:18080/collections/documents/points/delete \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "must": [
        {
          "key": "category",
          "type": "exact",
          "match": {"value": "tech"}
        }
      ]
    }
  }'

⚠️ Error Codes

Status Code	Description
400	Bad Request - Invalid parameters
404	Not Found - Collection does not exist
409	Conflict - Collection already exists
500	Internal Server Error - Internal error

🔧 Configuration

Server Startup

# Start the server
./govector serve [database_path] [options]

# Options:
# -port: Port to listen on (default: 18080)
# -db: Database file path (default: govector.db)

Example

# Start server on port 8080 with database file "myvectors.db"
./govector serve myvectors.db -port 8080

📚 Qdrant Compatibility

GoVector provides a Qdrant-compatible API, meaning you can use the same client libraries and code that you would use with Qdrant.

Key Compatibility Features

• Same API endpoints and request/response formats
• Same filter syntax and semantics
• Same distance metrics (cosine, euclidean, dot)

Differences

• GoVector is lightweight and embedded, while Qdrant is a distributed system
• GoVector uses BoltDB for storage instead of RocksDB
• GoVector has built-in support for SQ8 quantization
• GoVector doesn't include built-in authentication or rate limiting (recommended to implement via reverse proxy)

🤔 Troubleshooting

Common Issues

1. Collection not found
2. Ensure the collection exists before performing operations

3. Check the collection name for typos

4. Vector dimension mismatch

5. Ensure the vector length matches the collection's vector_size

6. Port occupied

7. Use the -port parameter to specify a different port

8. Permission issues

9. Ensure the database directory is readable/writable

10. Empty search results

11. Check if the vector dimension matches
12. Check if the filter conditions are too strict

📖 Next Steps

• Collection Management API - Detailed collection management API
• Point Operations API - Detailed point operations API
• Data Models - Detailed data model documentation
• Error Handling - Error handling best practices