ClickHouse REST API

Build a ClickHouse API from typed query definitions

The hard part of building a ClickHouse API is not opening an HTTP port. It is keeping validation, auth, response shapes, and query logic from drifting apart. @hypequery/serve solves that by turning one query definition into a typed API endpoint.

Start with hypequery Generate OpenAPI docs

Package

@hypequery/serve

Docs generation

Automatic OpenAPI

Best for

Analytics APIs and dashboards

Every team rebuilds the same ClickHouse HTTP layer

Once analytics queries need to be consumed by a frontend, a mobile app, or another service, someone ends up writing API routes. That means validation, error handling, auth, and response typing. Most teams rebuild that layer from scratch.

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 API, frontend developers have to inspect network requests or ask the backend team about response shapes. Every change to a ClickHouse query potentially breaks consumers 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 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

how-hypequery-serve-works.ts

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 API endpoint without duplication. If the query changes, it changes in one place.

If you want the shortest proof, define one real query and expose it. The generated OpenAPI output is then a by-product of the same contract rather than a second task.

Step 2

Serve all queries — OpenAPI included

step-2.ts

Every query definition becomes a typed POST endpoint. The OpenAPI spec and Swagger UI are available immediately — no manual documentation step.

Where teams usually get stuck

The questions this page should answer

ClickHouse API TypeScript

Building a typed ClickHouse API 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 endpoint comes from the query definition instead of re-implementing it.

Next step

Start with hypequery and serve your first ClickHouse API endpoint

Install @hypequery/serve, define a query, and expose it as a typed API endpoint. The OpenAPI spec is generated automatically from the same contract.