Reference & Deployment — Asteroid Documentation

HTTP API reference

All routes require Authorization: Bearer <api-key> except /health. Bodies are JSON unless noted.

Method & path	Description
`POST /v1/vectors`	Insert a vector (with optional `metadata`).
`PUT /v1/vectors/:id`	Upsert (replace) the vector for an id.
`GET /v1/vectors/:id`	Fetch a vector.
`DELETE /v1/vectors/:id`	Delete a vector.
`GET /v1/vectors/:id/payload`	Get the JSON payload.
`PUT /v1/vectors/:id/payload`	Replace the payload.
`PATCH /v1/vectors/:id/payload`	Merge-patch the payload (RFC 7396).
`POST /v1/search`	k-NN search (`vector`, `k`, optional `ef_search`, `filter`).
`POST /v1/build/bulk`	Bulk build (raw float32 body; `X-LSMVec-N` / `X-LSMVec-Dim` headers). Empty DB only.
`GET /v1/stats`	Tombstone / bloom / counters.
`GET /health`	Unauthenticated liveness check.
`GET /ready`	DB open & responsive.

Error codes: 400 invalid argument, 401 unauthorized, 404 not found, 413 payload too large, 429 rate limited, 5xx server error.

Python client reference

pip install lsmvec-client — dependency-free (stdlib urllib; numpy optional for bulk_build).

Method	Notes
`insert(id, vector, metadata=None)`	Insert with optional metadata.
`upsert(id, vector)`	Insert-or-replace the vector.
`get(id) -> dict`	`{"id", "vector"}`.
`delete(id)`
`get_payload(id)` / `set_payload(id, p)` / `merge_payload(id, p)`	Payload read / replace / merge-patch.
`search(vector, k=10, ef_search=None, filter=None)`	Returns `[SearchResult(id, distance)]`.
`bulk_build(vectors, threads=0) -> dict`	One-pass initial load (empty DB only).
`stats()` / `health()` / `ready()`	Diagnostics.

Errors map to typed exceptions (all subclass LSMVecError): InvalidArgument (400), Unauthorized (401), NotFound (404), PayloadTooLarge (413), RateLimited (429), ServerError (5xx).

Build from source

Prerequisites: a C++17 compiler (GCC 8+/Clang 10+), CMake ≥ 3.10, Boost (headers), and zstd / snappy / lz4 / bz2 / zlib. On macOS also jemalloc.

# initialize the Aster submodule, then build
git submodule update --init --recursive
make aster        # builds lib/aster/librocksdb.a (required first)
make              # builds the static + shared libs and the test binary

For the Python engine module (requires Aster built + ninja):

python -m pip install .        # builds and installs the lsm_vec module
python -c "import lsm_vec; print('OK')"

Run the server (self-host)

Self-host the same HTTP API as Asteroid Cloud. Run the lsm_vec_http server (or the lsmvec Docker image), then point lsmvec-client at your own host (base_url="http://localhost:8000") — everything in the Asteroid Cloud section applies unchanged.

# environment knobs (graph params + threads)
LSMVEC_M=8 LSMVEC_MMAX=24 LSMVEC_EFC=32 LSMVEC_HTTP_THREADS=1 \
  ./build/bin/lsm_vec_http   # serves the REST API on :8000

Back to Asteroid Cloud · Asteroid Database (LSM-Vec).