​
API Reference

The brinicle HTTP server provides a RESTful API for managing indexes, ingesting data, and performing searches. The server runs on port 1984 by default and accepts JSON requests with binary protocols for high-throughput operations.

​
Base URL

http://localhost:1984

​
Authentication

The current version of the brinicle HTTP server does not implement authentication. For production deployments, it is recommended to place the server behind a reverse proxy that handles authentication and TLS termination.

​
Content Types

The API uses two content types:
  • application/json — For most operations (create, init, finalize, delete, etc.)
  • application/octet-stream — For binary operations (batch ingest, search)

​
Response Format

Most endpoints return a JSON response with the following common structure: 
{
  "success": true,
  "message": "Operation completed successfully",
  "index_name": "my_index"
}
Error responses include a detail field: 
{
  "detail": "Index 'my_index' not found"
}

​
HTTP Status Codes

Status CodeMeaning
200Success
400Bad request (invalid parameters, operation failed)
404Index not found
409Conflict (index already exists)
503Service unavailable (engine module not loaded)

​
Quick Reference

MethodEndpointDescription
GET/Health check
GET/indexesList all indexes
POST/indexesCreate a new index
DELETE/indexes/{name}Delete or close an index
GET/indexes/{name}/statusGet index status
POST/indexes/loadLoad an existing index
POST/initInitialize an ingest session
POST/ingestIngest a single vector
POST/ingest/batchBatch ingest (binary)
POST/finalizeFinalize an ingest session
POST/deleteDelete items from an index
POST/rebuildRebuild an index compact
POST/search.binSearch (binary)
POST/optimizeOptimize the HNSW graph

​
Using the API

​
With curl

# Health check
curl http://localhost:1984/

# Create an index
curl -X POST http://localhost:1984/indexes \
  -H "Content-Type: application/json" \
  -d '{"index_name": "test", "dim": 128, "delta_ratio": 0.1}'

# Initialize ingest
curl -X POST http://localhost:1984/init \
  -H "Content-Type: application/json" \
  -d '{"index_name": "test", "mode": "build"}'

# Ingest a vector
curl -X POST http://localhost:1984/ingest \
  -H "Content-Type: application/json" \
  -d '{"index_name": "test", "external_id": "v1", "vector": [0.1, 0.2, 0.3]}'

# Finalize
curl -X POST http://localhost:1984/finalize \
  -H "Content-Type: application/json" \
  -d '{"index_name": "test", "optimize": true}'

​
With Python HTTP Client

from brinicle_client import BrinicleClient

client = BrinicleClient("http://localhost:1984")

client.create_index("test", dim=128)
client.init("test", "build")
client.ingest("test", "v1", [0.1, 0.2, 0.3])
client.finalize("test", optimize=True)
results = client.search("test", [0.1, 0.2, 0.3], k=10)