ClickHouse REST API
Serve ClickHouse analytics queries as typed REST endpoints
Most teams building on ClickHouse end up writing a custom HTTP layer — Express routes or Next.js API routes — that wraps their analytics queries. @hypequery/serve eliminates that step. Define your queries once and serve them as typed REST endpoints with OpenAPI docs automatically.
Package
@hypequery/serve
Docs generation
Automatic OpenAPI
Best for
Analytics APIs and dashboards
Every team rebuilds the same ClickHouse HTTP layer
Once your analytics queries need to be consumed by a frontend, a mobile app, or a third-party integration, you write HTTP routes. That layer is not trivial — you need validation, error handling, auth, and response typing. Most teams do it from scratch each time.
Query logic gets duplicated across routes
The same ClickHouse query ends up in a Next.js route, a cron job, a dashboard API, and an export endpoint — each with slightly different filtering. When the query logic needs to change, it changes everywhere inconsistently.
No OpenAPI docs means dashboard teams have to guess the shape
Without a schema for your analytics endpoints, frontend developers have to inspect network requests or ask the backend team about response shapes. Every change to a ClickHouse query potentially breaks the frontend silently.
How @hypequery/serve works
Define queries once, serve them as typed HTTP endpoints
You define analytics queries using the hypequery query builder. @hypequery/serve wraps those definitions in HTTP endpoints — with Zod input validation, typed responses, auth context injection, and automatic OpenAPI spec generation.
- Query definitions become POST endpoints with validated request bodies
- Response types inferred from ClickHouse schema — no annotation needed
- Auth and tenant context injected per-request from headers or session
- OpenAPI spec generated automatically from query input/output types
- Interactive Swagger UI available at /docs out of the box
Step 1
Define your analytics query
The query definition includes input validation (Zod), context injection for auth and tenancy, and the typed ClickHouse query. This same definition runs inline or over HTTP.
Step 2
One line to serve all queries as REST endpoints
Pass your query definitions to serve() and get a production-ready HTTP server. Each query becomes an endpoint, OpenAPI docs are generated automatically, and the response types match the ClickHouse schema.
The same query definition that runs inline in a script or cron job becomes an HTTP endpoint without any duplication. If the query logic changes, it changes in one place.
See the OpenAPI guide for details on what the generated spec looks like and how to customise endpoint paths and authentication.
Step 2
Serve all queries — OpenAPI included
Every query definition becomes a typed POST endpoint. The OpenAPI spec and Swagger UI are available immediately — no manual documentation step.
Why teams search for this
Common implementation questions this page should solve
ClickHouse HTTP API TypeScript
Building a typed HTTP API on top of ClickHouse in TypeScript is exactly what @hypequery/serve handles. Define your analytics queries once and serve them as REST endpoints with validated inputs and typed responses.
ClickHouse API server Node.js
@hypequery/serve runs in Node.js and can be mounted through its Node adapter or used as a standalone handler. Your ClickHouse queries become API endpoints without writing route handlers manually.
ClickHouse analytics API with auth
The context function in initServe() injects per-request auth and tenancy — read from headers, JWTs, or session data. Every query in the serve() call has access to the typed context, including tenant isolation.
ClickHouse REST endpoint from query definition
Instead of writing an Express route that calls ClickHouse and returns a response, you define the query once with hypequery and pass it to serve(). The HTTP endpoint is the query definition — nothing duplicated.
Further reading
Go deeper with comparison posts and implementation guides
ClickHouse OpenAPI generation
What the auto-generated OpenAPI spec looks like and how to use it with frontend clients.
Open guide
ClickHouse Query Builder
The query definition layer that @hypequery/serve wraps into HTTP endpoints.
Open guide
ClickHouse React
Consume your typed REST endpoints as React hooks for dashboard and UI components.
Open guide
Multi-tenant analytics
How to inject tenant context and enforce row-level isolation across all REST endpoints.
Open guide
Next step
Serve your first ClickHouse query as a REST endpoint
Install @hypequery/serve, define a query, and serve it as a typed HTTP endpoint. The OpenAPI spec is generated automatically on first request.