HTTP API Reference

Overview

Scintirete provides RESTful API interfaces based on the Gin framework for vector database management and operations. All APIs follow REST design principles and use JSON format for data exchange.

Base URL: /api/v1

Authentication: All APIs require authentication except health check endpoint

Authentication Method

All protected endpoints require authentication information in the request header:

Authorization: Bearer <token>

Response Format

All API responses use JSON format:

{
  "success": true,
  "data": {},
  "error": null
}

ID Generation Notes

Important: In Scintirete, all vector IDs are automatically generated by the server using incremental uint64 type. Clients do not need and should not provide ID fields when inserting vectors or texts. The server will return the list of generated IDs after successful insertion.

API List

1. Health Check

Endpoint: GET /api/v1/health

Description: Check service status

Authentication: Not required

Response Example:

{
  "status": "healthy",
  "service": "scintirete",
  "version": "1.0.0"
}

2. Database Management

2.1 Create Database

Endpoint: POST /api/v1/databases

Description: Create a new database

Authentication: Required

Request Body:

{
  "name": "database_name"
}

Response Example: 201 Created

{
  "success": true,
  "data": {
    "name": "database_name",
    "success": true,
    "message": "Database created successfully"
  },
  "error": null
}

2.2 Delete Database

Endpoint: DELETE /api/v1/databases/:db_name

Description: Delete specified database

Authentication: Required

Parameters:

db_name: Database name (path parameter)

Response Example: 200 OK

{
  "success": true,
  "data": {
    "name": "database_name",
    "success": true,
    "message": "Database dropped successfully",
    "dropped_collections": 3
  },
  "error": null
}

2.3 List Databases

Endpoint: GET /api/v1/databases

Description: Get list of all databases

Authentication: Required

Response Example: 200 OK

{
  "success": true,
  "data": {
    "names": ["database1", "database2", "database3"]
  },
  "error": null
}

3. Collection Management

3.1 Create Collection

Endpoint: POST /api/v1/databases/:db_name/collections

Description: Create collection in specified database

Authentication: Required

Parameters:

db_name: Database name (path parameter)

Request Body:

{
  "collection_name": "collection_name",
  "metric_type": "COSINE",
  "dimension": 768
}

Response Example: 201 Created

{
  "success": true,
  "data": {
    "db_name": "database_name",
    "collection_name": "collection_name",
    "success": true,
    "message": "Collection created successfully",
    "info": {
      "name": "collection_name",
      "dimension": 768,
      "vector_count": 0,
      "deleted_count": 0,
      "memory_bytes": 0,
      "metric_type": "COSINE"
    }
  },
  "error": null
}

3.2 Delete Collection

Endpoint: DELETE /api/v1/databases/:db_name/collections/:coll_name

Description: Delete specified collection

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Response Example: 200 OK

{
  "success": true,
  "data": {
    "db_name": "database_name",
    "collection_name": "collection_name",
    "success": true,
    "message": "Collection dropped successfully",
    "dropped_vectors": 1000
  },
  "error": null
}

3.3 Get Collection Info

Endpoint: GET /api/v1/databases/:db_name/collections/:coll_name

Description: Get detailed information of specified collection

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Response Example: 200 OK

{
  "success": true,
  "data": {
    "name": "collection_name",
    "dimension": 768,
    "vector_count": 1000,
    "deleted_count": 50,
    "memory_bytes": 3145728,
    "metric_type": "COSINE",
    "hnsw_config": {
      "m": 16,
      "ef_construction": 200
    }
  },
  "error": null
}

3.4 List Collections

Endpoint: GET /api/v1/databases/:db_name/collections

Description: Get all collections in specified database

Authentication: Required

Parameters:

db_name: Database name (path parameter)

Response Example: 200 OK

{
  "success": true,
  "data": {
    "collections": [
      {
        "name": "collection1",
        "dimension": 768,
        "vector_count": 1000,
        "deleted_count": 50,
        "memory_bytes": 3145728,
        "metric_type": "COSINE"
      }
    ]
  },
  "error": null
}

4. Vector Operations

4.1 Insert Vectors

Endpoint: POST /api/v1/databases/:db_name/collections/:coll_name/vectors

Description: Insert vector data into specified collection

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Request Body:

{
  "vectors": [
    {
      "values": [0.1, 0.2, 0.3, ...],
      "metadata": {"key": "value"}
    }
  ]
}

Response Example: 201 Created

{
  "success": true,
  "data": {
    "inserted_ids": [1, 2, 3],
    "inserted_count": 3
  },
  "error": null
}

Note: Vector IDs are automatically generated by the server, clients do not need to provide them.

4.2 Delete Vectors

Endpoint: DELETE /api/v1/databases/:db_name/collections/:coll_name/vectors

Description: Delete vectors from specified collection

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Request Body:

{
  "ids": [1, 2, 3]
}

Note: The IDs here must be numeric IDs (uint64 type) previously generated by the server, not strings.

Response Example: 200 OK

{
  "success": true,
  "data": {
    "deleted_count": 2
  },
  "error": null
}

4.3 Vector Search

Endpoint: POST /api/v1/databases/:db_name/collections/:coll_name/search

Description: Perform vector search in specified collection

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Request Body:

{
  "query_vector": [0.1, 0.2, 0.3, ...],
  "top_k": 10,
  "filter": {"key": "value"}
}

Response Example: 200 OK

{
  "success": true,
  "data": {
    "results": [
      {
        "id": 1,
        "distance": 0.123,
        "metadata": {"category": "test"}
      }
    ]
  },
  "error": null
}

5. Text Embedding

5.1 Embed and Insert

Endpoint: POST /api/v1/databases/:db_name/collections/:coll_name/embed

Description: Embed text and insert into vector database

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Request Body:

{
  "texts": [
    {
      "content": "Text content",
      "metadata": {"key": "value"}
    }
  ]
}

Response Example: 201 Created

{
  "success": true,
  "data": {
    "inserted_ids": [1, 2, 3],
    "inserted_count": 3
  },
  "error": null
}

Note: Vector IDs are automatically generated by the server, clients do not need to provide them.

5.2 Embed and Search

Endpoint: POST /api/v1/databases/:db_name/collections/:coll_name/embed/search

Description: Embed query text and search for similar vectors

Authentication: Required

Parameters:

db_name: Database name (path parameter)
coll_name: Collection name (path parameter)

Request Body:

{
  "query_text": "Query text",
  "top_k": 10,
  "filter": {"key": "value"}
}

Response Example: 200 OK

{
  "success": true,
  "data": {
    "results": [
      {
        "id": 5,
        "distance": 0.234,
        "metadata": {"category": "document"}
      }
    ]
  },
  "error": null
}

5.3 Text Embedding

Endpoint: POST /api/v1/embed

Description: Perform text embedding

Authentication: Required

Request Body:

{
  "texts": ["Text 1", "Text 2", "Text 3"]
}

Response Example: 200 OK

{
  "success": true,
  "data": {
    "results": [
      {
        "text": "Text 1",
        "embedding": [0.1, 0.2, 0.3, ...],
        "index": 0
      }
    ]
  },
  "error": null
}

5.4 List Embedding Models

Endpoint: GET /api/v1/embed/models

Description: Get list of available embedding models

Authentication: Required

Response Example: 200 OK

{
  "success": true,
  "data": {
    "models": [
      {
        "id": "text-embedding-ada-002",
        "name": "OpenAI Ada 002",
        "dimension": 1536,
        "available": true,
        "description": "OpenAI text embedding model"
      }
    ],
    "default_model": "text-embedding-ada-002"
  },
  "error": null
}

Error Handling

All APIs return appropriate HTTP status codes and error information when errors occur:

400 Bad Request: Request parameter error
401 Unauthorized: Authentication failed
404 Not Found: Resource not found
500 Internal Server Error: Internal server error

Error response format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Example Requests

Create Database

curl -X POST http://localhost:8080/api/v1/databases \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_database"}'

Insert Vectors

curl -X POST http://localhost:8080/api/v1/databases/my_database/collections/my_collection/vectors \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "values": [0.1, 0.2, 0.3],
        "metadata": {"category": "test"}
      }
    ]
  }'

Vector Search

curl -X POST http://localhost:8080/api/v1/databases/my_database/collections/my_collection/search \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query_vector": [0.1, 0.2, 0.3],
    "top_k": 5
  }'

Documentation

HTTP API Reference

Overview

Authentication Method

Response Format

ID Generation Notes

API List

1. Health Check

2. Database Management

2.1 Create Database

2.2 Delete Database

2.3 List Databases

3. Collection Management

3.1 Create Collection

3.2 Delete Collection

3.3 Get Collection Info

3.4 List Collections

4. Vector Operations

4.1 Insert Vectors

4.2 Delete Vectors

4.3 Vector Search

5. Text Embedding

5.1 Embed and Insert

5.2 Embed and Search

5.3 Text Embedding

5.4 List Embedding Models

Error Handling

Example Requests

Create Database

Insert Vectors

Vector Search