Route Handlers Reference

hlquery route handling has three layers:

src/api/httproutes.cpp normalizes the request path and maps it to a RouteAction.
src/api/httpserver.cpp performs authentication, readiness checks, sync/write gates, and dispatch.
SearchAPI handlers implement the endpoint behavior across src/api/*.cpp.

Use Complete API Reference for the full route table. This page focuses on implementation ownership and handler behavior.

Route Resolver

ResolveHttpRoute(const HttpRequest &Request) is the source of truth for route matching.

Important behavior:

Query strings are ignored during route matching.
One trailing slash is ignored.
Routes are method-specific.
Collection routes are parsed by path segments, not by broad string prefixes.
/collections/{collection}/documents/search maps to lexical search.
/collections/{collection}/search maps to vector search.

Handler Ownership

Area	Primary source file	Representative handlers
Health, metrics, links, runtime	`src/api/health.cpp`	`HandleHealth()`, `HandleReady()`, `HandleStats()`, `HandleMetrics()`, `HandleLinksList()`
Collections	`src/api/collections.cpp`	`HandleListCollections()`, `HandleCreateCollection()`, `HandleUpdateCollection()`
Documents	`src/api/documents.cpp`	`HandleAddDocument()`, `HandleGetDocument()`, `HandleBulkImportDocuments()`
Search	`src/api/search.cpp`	`HandleSearch()`, `HandleGlobalSearch()`, `HandleMultiSearch()`
Vector search	`src/api/vector.cpp`	`HandleVectorSearch()`
Maybe suggestions	`src/api/maybe.cpp`	`HandleMaybe()`
Export	`src/api/export.cpp`	`HandleExportDocuments()`
Synonyms	`src/api/synonyms.cpp`	`HandleListSynonyms()`, `HandleCreateOrUpdateSynonym()`
Stopwords	`src/api/stopwords.cpp`	`HandleListStopwords()`, `HandleCreateStopword()`
Overrides	`src/api/overrides.cpp`	`HandleListOverrides()`, `HandleCreateOrUpdateOverride()`
Aliases	`src/api/aliases.cpp`	`HandleListAliases()`, `HandleCreateOrUpdateAlias()`
Users	`src/api/users.cpp`	`HandleListUsers()`, `HandleCreateUser()`
Keys	`src/api/keys.cpp`	`HandleListKeys()`, `HandleCreateKey()`
Modules	`src/api/modules.cpp`	`HandleListModules()`, `HandleModuleAPI()`, `HandleModuleSyntax()`
Analytics	`src/api/analytics.cpp`	`HandleAnalyticsClick()`
Storage	`src/api/storage.cpp`	`HandleStorageStatus()`

Handler declarations live in include/api/searchapi.h.

Dispatch and Safety Gates

Before a handler runs, the HTTP layer may apply:

CORS preflight handling.
API key or bearer token authentication.
Admin-only checks for routes such as /keys, /users, /flush, and /admin/storage_status.
Metadata scan readiness checks for routes that need complete collection metadata.
Sync gating for write operations.
Module pre-check hooks for selected operations.

These gates are route-action based, so adding a new route normally requires updating both ResolveHttpRoute() and the action classification logic in src/api/httpserver.cpp.

Handler Categories

Health and Runtime

Handler	Routes	Purpose
`HandleStatus()`	`GET /`, `GET /status`, `GET /query`	Basic server status.
`HandleHealth()`	`/health`	Health report suitable for probes. Clients should use GET.
`HandleReady()`	`GET /ready`	Readiness probe.
`HandlePing()`	`GET /ping`	Minimal ping response.
`HandleStartup()`	`GET /startup`, `GET /boot-status`	Startup and boot report.
`HandleStats()`	`GET /stats`	Runtime and storage statistics.
`HandleMetrics()`	`GET /metrics`, `GET /metrics.json`	Metrics payload.
`HandleMetricsHistory()`	`GET /metrics/history`, `GET /metrics-history`	Historical metrics.
`HandleEtc()`	`GET /etc`	Protocol metadata used by clients.
`HandleCache()`	`GET /cache`	Cache statistics.
`HandleSearchConfig()`	`GET /search-config`	Active search configuration.
`HandleConfigFiles()`	`GET /config-files`	Active configuration files and included files.

Collections and Documents

Handler	Routes	Purpose
`HandleListCollections()`	`GET /collections`	List collections.
`HandleListCollectionsDistributed()`	`GET /collections/distributed`	Include linked nodes.
`HandleCreateCollection()`	`POST /collections`	Create collection.
`HandleGetCollection()`	`GET /collections/{collection}`	Get collection metadata.
`HandleGetCollectionLanguage()`	`GET /collections/{collection}/lang`	Get collection language.
`HandleUpdateCollection()`	`POST /collections/{collection}/update`	Update schema.
`HandleDeleteCollection()`	`DELETE /collections/{collection}`	Delete collection.
`HandleListDocuments()`	`GET /collections/{collection}/documents`	List documents.
`HandleAddDocument()`	`POST /collections/{collection}/documents`	Add document.
`HandleBulkImportDocuments()`	`POST /collections/{collection}/documents/import`	Bulk import.
`HandleGetDocument()`	`GET /collections/{collection}/documents/{id}`	Get document.
`HandleGetDocumentContext()`	`GET /collections/{collection}/documents/{id}/context`	Get document context.
`HandleUpdateDocument()`	`PUT /collections/{collection}/documents/{id}`	Update document.
`HandleDeleteDocument()`	`DELETE /collections/{collection}/documents/{id}`	Delete document.
`HandleDeleteDocumentsByFilter()`	`DELETE /collections/{collection}/documents`	Delete by filter.
`HandleUpdateByQuery()`	`POST /collections/{collection}/documents/_update_by_query`	Update by query.
`HandleDeleteByQuery()`	`POST /collections/{collection}/documents/_delete_by_query`	Delete by query.

Search

Handler	Routes	Purpose
`HandleSearch()`	`GET/POST /collections/{collection}/documents/search`, `GET/POST /sql`	Lexical, hybrid, and SQL-style search entry point.
`HandleVectorSearch()`	`GET/POST /collections/{collection}/vector_search`, `GET/POST /collections/{collection}/search`	Dedicated vector search.
`HandleMultiSearch()`	`GET/POST /multi_search`	Batch search requests.
`HandleGlobalSearch()`	`GET/POST /search`	Global search entry point.
`HandleFacetCounts()`	`GET/POST /collections/{collection}/documents/facet_counts`	Facet counts.
`HandleExportDocuments()`	`GET/POST /collections/{collection}/documents/export`	Export matching documents.
`HandleMaybe()`	`GET/POST /collections/{collection}/documents/maybe`	Query suggestions.

Dictionaries and Relevance Controls

Handler	Routes	Purpose
`HandleListAllSynonyms()`	`GET /synonyms`	List all synonym data.
`HandleListGlobalSynonyms()`	`GET /synonyms/global`	List global synonyms.
`HandleCreateOrUpdateGlobalSynonym()`	`POST/PUT /synonyms/global/{id}`	Upsert global synonym.
`HandleGetGlobalSynonym()`	`GET /synonyms/global/{id}`	Get global synonym.
`HandleDeleteGlobalSynonym()`	`DELETE /synonyms/global/{id}`	Delete global synonym.
`HandleListSynonyms()`	`GET /collections/{collection}/synonyms`	List collection synonyms.
`HandleCreateOrUpdateSynonym()`	`POST/PUT /collections/{collection}/synonyms/{id}`	Upsert collection synonym.
`HandleGetSynonym()`	`GET /collections/{collection}/synonyms/{id}`	Get collection synonym.
`HandleDeleteSynonym()`	`DELETE /collections/{collection}/synonyms/{id}`	Delete collection synonym.
`HandleListAllStopwords()`	`GET /stopwords`	List all stopwords.
`HandleListGlobalStopwords()`	`GET /stopwords/global`	List global stopwords.
`HandleCreateGlobalStopword()`	`POST /stopwords/global`	Create global stopword.
`HandleDeleteGlobalStopword()`	`DELETE /stopwords/global/{word}`	Delete global stopword.
`HandleListStopwords()`	`GET /collections/{collection}/stopwords`	List collection stopwords.
`HandleCreateStopword()`	`POST /collections/{collection}/stopwords`	Create collection stopword.
`HandleDeleteStopword()`	`DELETE /collections/{collection}/stopwords/{word}`	Delete collection stopword.
`HandleListOverrides()`	`GET /collections/{collection}/overrides`	List overrides.
`HandleCreateOrUpdateOverride()`	`POST/PUT /collections/{collection}/overrides/{id}`	Upsert override.
`HandleGetOverride()`	`GET /collections/{collection}/overrides/{id}`	Get override.
`HandleDeleteOverride()`	`DELETE /collections/{collection}/overrides/{id}`	Delete override.
`HandleListPresets()`	`GET /presets`	List search presets.
`HandleCreateOrUpdatePreset()`	`POST/PUT /presets/{preset}`	Upsert search preset.
`HandleGetPreset()`	`GET /presets/{preset}`	Get search preset.
`HandleDeletePreset()`	`DELETE /presets/{preset}`	Delete search preset.

Access, Modules, and Links

Handler	Routes	Purpose
`HandleListAliases()`	`GET /aliases`, `GET /collections/{collection}/aliases`	List aliases.
`HandleCreateOrUpdateAlias()`	`POST/PUT /aliases/{alias}`	Upsert alias.
`HandleGetAlias()`	`GET /aliases/{alias}`	Get alias.
`HandleDeleteAlias()`	`DELETE /aliases/{alias}`	Delete alias.
`HandleListKeys()`	`GET /keys`	List API keys.
`HandleCreateKey()`	`POST /keys`	Create API key.
`HandleGetKey()`	`GET /keys/{id}`	Get API key metadata.
`HandleUpdateKey()`	`PUT /keys/{id}`	Update API key.
`HandleDeleteKey()`	`DELETE /keys/{id}`	Delete API key.
`HandleListUsers()`	`GET /users`	List users.
`HandleCreateUser()`	`POST /users`	Create user.
`HandleGetUser()`	`GET /users/{name}`	Get user.
`HandleUpdateUser()`	`PUT /users/{name}`	Update user.
`HandleDeleteUser()`	`DELETE /users/{name}`	Delete user.
`HandleLinksList()`	`GET /links`	List cluster links.
`HandleLinksPing()`	`GET /links/ping`	Ping links.
`HandleLinksConnect()`	`POST /links/connect`	Add runtime link.
`HandleLinksDisconnect()`	`POST /links/disconnect`	Remove runtime link.
`HandleListModules()`	`GET /modules`	List modules.
`HandleModuleAPI()`	`/loadmodule`, `/unloadmodule`, `/modules/{module}/...`	Module APIs.
`HandleModuleSyntax()`	`GET /modules/{module}/syntax`	Module syntax.
`HandleAnalyticsClick()`	`POST /analytics/click`	Click analytics.

Adding or Changing Routes

When adding a route, update these places together:

Add route matching in src/api/httproutes.cpp.
Add or reuse a RouteAction in include/api/httpserver.h.
Dispatch the action in src/api/httpserver.cpp.
Add the handler declaration in include/api/searchapi.h if needed.
Implement the handler in the appropriate src/api/*.cpp file.
Update Complete API Reference and endpoint-specific docs.

Common Error Responses

Handlers return JSON errors where possible:

{
  "error": "Bad Request",
  "message": "Invalid JSON body"
}

Status codes commonly used by handlers:

Status	Meaning
`400`	Invalid request body, path, or query parameter.
`401`	Authentication is required or invalid.
`403`	Authenticated user or key lacks permission.
`404`	Collection, document, or resource was not found.
`405`	Method is not accepted by the matched handler.
`409`	Resource conflict.
`503`	Startup, metadata, or sync gate is temporarily blocking the route.
`500`	Server-side failure.

Route Resolver​

Handler Ownership​

Dispatch and Safety Gates​

Handler Categories​

Health and Runtime​

Collections and Documents​

Search​

Dictionaries and Relevance Controls​

Access, Modules, and Links​

Adding or Changing Routes​

Common Error Responses​