API Overview
hlquery exposes a modern HTTP/JSON API for collection management, document indexing, lexical search, vector search, aliases, access control, cluster links, modules, and server health.
The authoritative route resolver lives in src/api/httproutes.cpp. Endpoint pages in this section describe the public surface exposed by that resolver.
Base URL
Development servers listen on port 9200 by default:
http://localhost:9200
TLS deployments usually terminate HTTPS at a proxy or run hlquery with an HTTPS listener, depending on local configuration.
https://search.example.com
Request Format
Most write and action endpoints accept JSON request bodies:
curl -X POST http://localhost:9200/collections/products/documents \
-H "Content-Type: application/json" \
-d '{"id":"prod_1","title":"Keyboard","price":49.99}'
Most read endpoints support query string parameters:
curl "http://localhost:9200/collections/products/documents/search?q=keyboard&limit=10"
Trailing slashes are normalized by the route resolver. Query strings are stripped before route matching.
Authentication
hlquery supports API key authentication through either header:
curl -H "X-API-Key: your-api-key" http://localhost:9200/collections
curl -H "Authorization: Bearer your-api-key" http://localhost:9200/collections
Authentication behavior is controlled by server configuration. When authentication is disabled, unauthenticated requests are accepted, while token-bearing requests may be rejected except for routes such as /health.
Admin routes include /keys, /users, /flush, and /admin/storage_status.
Route Groups
Health, Readiness, and Metrics
| Method | Path | Description |
|---|---|---|
| GET | / | Status response |
| GET | /status | Status response |
| GET | /query | Status alias |
| ANY | /health | Health check. Use GET from clients. |
| GET | /ready | Readiness check |
| GET | /ping | Lightweight ping |
| GET | /startup | Startup report |
| GET | /boot-status | Startup report alias |
| GET | /stats | Server statistics |
| GET | /metrics | JSON metrics |
| GET | /metrics.json | Metrics alias |
| GET | /metrics/history | Historical metrics |
| GET | /metrics-history | Historical metrics alias |
| GET | /connections | Active connection count |
| GET | /doctotal | Total document and collection count |
| GET | /etc | Protocol metadata for clients |
| GET | /cache | Search/cache status |
| GET | /config-files | Runtime configuration file metadata |
| GET | /search-config | Search configuration summary |
Storage and Maintenance
| Method | Path | Description |
|---|---|---|
| GET | /rocksdb | RocksDB status |
| GET | /_rocksdb | RocksDB status alias |
| GET | /admin/storage_status | Storage backend status |
| GET/POST | /update-counters | Recompute document counters |
| GET | /debug/counters | Counter diagnostics |
| GET/POST | /repair | Run repair checks |
| GET | /integrity | Integrity checks |
| GET | /consistency | Integrity alias |
| GET | /self-check | Self-check report |
| POST | /flush | Flush all data. Admin-only and destructive. |
| GET | /presets | List saved presets |
| POST/PUT | /presets/{preset} | Create or update a preset |
| GET | /presets/{preset} | Get a preset |
| DELETE | /presets/{preset} | Delete a preset |
Collections
| Method | Path | Description |
|---|---|---|
| GET | /collections | List collections |
| POST | /collections | Create collection |
| GET | /collections/distributed | List collections across configured links |
| GET | /collections/{collection} | Get collection metadata |
| DELETE | /collections/{collection} | Delete collection |
| GET | /collections/{collection}/lang | Get collection language |
| POST | /collections/{collection}/update | Update collection schema |
Documents
| Method | Path | Description |
|---|---|---|
| GET | /collections/{collection}/documents | List documents |
| POST | /collections/{collection}/documents | Add document |
| DELETE | /collections/{collection}/documents | Delete documents by filter |
| POST | /collections/{collection}/documents/import | Bulk import documents |
| GET | /collections/{collection}/documents/{id} | Get document |
| PUT | /collections/{collection}/documents/{id} | Update document |
| DELETE | /collections/{collection}/documents/{id} | Delete document |
| GET | /collections/{collection}/documents/{id}/context | Get surrounding document context |
| POST | /collections/{collection}/documents/_update_by_query | Update matching documents |
| POST | /collections/{collection}/documents/_delete_by_query | Delete matching documents |
Search
| Method | Path | Description |
|---|---|---|
| GET/POST | /collections/{collection}/documents/search | Lexical or hybrid document search |
| GET/POST | /collections/{collection}/documents/facet_counts | Facet counts |
| GET/POST | /collections/{collection}/documents/export | Export matching documents |
| GET/POST | /collections/{collection}/documents/maybe | Query suggestion endpoint |
| GET/POST | /collections/{collection}/vector_search | Dedicated vector search |
| GET/POST | /collections/{collection}/search | Vector search alias |
| GET/POST | /multi_search | Multi-search |
| GET/POST | /search | Global search |
| GET/POST | /sql | SQL-style query entry point |
Synonyms, Stopwords, Overrides, and Aliases
| Method | Path | Description |
|---|---|---|
| GET | /synonyms | List all synonyms |
| GET | /synonym_sets | List all synonyms alias |
| GET | /synonyms/global | List global synonyms |
| GET | /synonym_sets/global | List global synonyms alias |
| POST/PUT | /synonyms/global/{id} | Create or update global synonym |
| POST/PUT | /synonym_sets/global/{id} | Create or update global synonym alias |
| POST/PUT | /synonym_sets/global/items/{id} | Create or update global synonym item alias |
| GET | /synonyms/global/{id} | Get global synonym |
| GET | /synonym_sets/global/{id} | Get global synonym alias |
| GET | /synonym_sets/global/items/{id} | Get global synonym item alias |
| DELETE | /synonyms/global/{id} | Delete global synonym |
| DELETE | /synonym_sets/global/{id} | Delete global synonym alias |
| DELETE | /synonym_sets/global/items/{id} | Delete global synonym item alias |
| GET | /collections/{collection}/synonyms | List collection synonyms |
| GET | /collections/{collection}/synonym_sets | List collection synonyms alias |
| POST/PUT | /collections/{collection}/synonyms/{id} | Create or update collection synonym |
| POST/PUT | /collections/{collection}/synonym_sets/{id} | Create or update collection synonym alias |
| GET | /collections/{collection}/synonyms/{id} | Get collection synonym |
| GET | /collections/{collection}/synonym_sets/{id} | Get collection synonym alias |
| DELETE | /collections/{collection}/synonyms/{id} | Delete collection synonym |
| DELETE | /collections/{collection}/synonym_sets/{id} | Delete collection synonym alias |
| GET | /stopwords | List all stopwords |
| GET | /stopword_sets | List all stopwords alias |
| GET | /stopwords/global | List global stopwords |
| GET | /stopword_sets/global | List global stopwords alias |
| POST | /stopwords/global | Create global stopword |
| POST | /stopword_sets/global | Create global stopword alias |
| DELETE | /stopwords/global/{word} | Delete global stopword |
| DELETE | /stopword_sets/global/{word} | Delete global stopword alias |
| DELETE | /stopword_sets/global/items/{word} | Delete global stopword item alias |
| GET | /collections/{collection}/stopwords | List collection stopwords |
| GET | /collections/{collection}/stopword_sets | List collection stopwords alias |
| POST | /collections/{collection}/stopwords | Create collection stopword |
| POST | /collections/{collection}/stopword_sets | Create collection stopword alias |
| DELETE | /collections/{collection}/stopwords/{word} | Delete collection stopword |
| DELETE | /collections/{collection}/stopword_sets/{word} | Delete collection stopword alias |
| GET | /collections/{collection}/overrides | List collection overrides |
| POST/PUT | /collections/{collection}/overrides/{id} | Create or update override |
| GET | /collections/{collection}/overrides/{id} | Get override |
| DELETE | /collections/{collection}/overrides/{id} | Delete override |
| GET | /collections/{collection}/curations | List collection curations alias |
| GET | /collections/{collection}/curation_sets | List collection curations alias |
| POST/PUT | /collections/{collection}/curations/{id} | Create or update curation alias |
| POST/PUT | /collections/{collection}/curation_sets/{id} | Create or update curation alias |
| GET | /collections/{collection}/curations/{id} | Get curation alias |
| GET | /collections/{collection}/curation_sets/{id} | Get curation alias |
| DELETE | /collections/{collection}/curations/{id} | Delete curation alias |
| DELETE | /collections/{collection}/curation_sets/{id} | Delete curation alias |
| GET | /aliases | List aliases |
| GET | /collections/{collection}/aliases | List aliases targeting a collection |
| POST/PUT | /aliases/{alias} | Create or update alias |
| GET | /aliases/{alias} | Get alias |
| DELETE | /aliases/{alias} | Delete alias |
Access Control
| Method | Path | Description |
|---|---|---|
| GET | /keys | List API keys |
| POST | /keys | Create API key |
| GET | /keys/{id} | Get API key metadata |
| PUT | /keys/{id} | Update API key |
| DELETE | /keys/{id} | Delete API key |
| GET | /users | List users |
| POST | /users | Create user |
| GET | /users/{name} | Get user |
| PUT | /users/{name} | Update user |
| DELETE | /users/{name} | Delete user |
Links, Modules, and Analytics
| Method | Path | Description |
|---|---|---|
| GET | /links | List configured cluster links |
| GET | /links/ping | Ping configured links |
| POST | /links/connect | Add a runtime link |
| POST | /links/disconnect | Remove a runtime link |
| GET | /modules | List loaded modules |
| POST | /loadmodule | Load module by request body |
| POST | /loadmodule/{module} | Load module by path |
| POST | /unloadmodule | Unload module by request body |
| POST | /unloadmodule/{module} | Unload module by path |
| GET/POST/PUT/DELETE | /modules/{module}/... | Module-specific API |
| GET | /modules/{module}/syntax | Module syntax |
| POST | /analytics/click | Record click analytics |
Pagination
Common list endpoints accept offset and limit:
curl "http://localhost:9200/collections/products/documents?offset=0&limit=25"
Search endpoints also support page and per_page where the handler accepts Typesense-style parameters.
Errors
Errors are returned as JSON when possible:
{
"error": "Collection not found",
"message": "The requested collection does not exist",
"code": 1004,
"code_text": "COLLECTION_NOT_FOUND"
}
error is the handler-provided description when one is available. code_text is the stable name associated with the numeric protocol code; clients should use code or code_text for programmatic branching and treat error and message as human-readable context.
Common status codes:
| Status | Meaning |
|---|---|
200 | Request succeeded |
201 | Resource created |
400 | Bad request |
401 | Missing or invalid authentication |
403 | Forbidden |
404 | Resource not found |
405 | Method not allowed |
409 | Conflict |
500 | Internal server error |
503 | Temporarily unavailable during startup, metadata scan, or sync |