Deploy AskDB as an HTTP service

Service guide

@askdb/http-api wraps the same ask() pipeline behind a minimal HTTP server. Use it when non-Node clients need to ask questions, or when you want one AskDB service shared across multiple consumers.

Install

npm install @askdb/http-api @askdb/postgres ai @ai-sdk/openai

Start the server

import { createAskDbHttpServer } from "@askdb/http-api";

const server = createAskDbHttpServer({
  port: 3000,
  host: "127.0.0.1",
  maxBodyBytes: 1024 * 1024, // 1 MiB default
});

server.listen();

The server reads its schema and model settings from your askdb.config.ts (it bootstraps the same config file the CLI and Studio use). Set host.schemaPath to point at your schema artifact and configure the AI provider as usual — supply the provider key (OPENAI_API_KEY, etc.) in your environment the same way you do for the CLI.

Endpoints

The server exposes two endpoints:

`GET /health`

curl http://localhost:3000/health
# {"ok":true}

`POST /ask`

Body:

{
  "question": "Which customers signed up last week?",
  "mode": "schema_only",
  "explain": false
}

Response (success):

{
  "ok": true,
  "correlationId": "01H…",
  "sql": "SELECT id, name, created_at FROM customers WHERE created_at >= …"
}

The response is SQL only — the server does not run it. Your client takes the SQL and decides what to do with it.

Calling from curl

curl -X POST http://localhost:3000/ask \
  -H "content-type: application/json" \
  -d '{"question": "How many customers signed up last week?"}'

Calling from Python

import os
import httpx

resp = httpx.post(
    f"{os.environ['SERVER_URL']}/ask",
    json={"question": "How many customers signed up last week?"},
    timeout=30,
)
resp.raise_for_status()
body = resp.json()

if body["ok"]:
    sql = body["sql"]
    correlation_id = body["correlationId"]
    # Run the SQL against your read-only role here.
else:
    raise RuntimeError(body["error"]["code"])

Run it behind a gateway

@askdb/http-api is intentionally minimal — there is no built-in auth, rate limiting, or TLS termination. Don’t expose it directly to the public internet. Put it behind your existing API gateway, ingress, or reverse proxy and apply the same auth you use for the rest of your services.

A typical production shape:

client  ──►  your API gateway  ──►  @askdb/http-api  ──►  model + schema
                  │                          │
                  │                          ▼
                  └────────────────►  read-only DB role  ◄─── (execution happens in your gateway service, not here)

The server does not connect to your database. It generates SQL and returns it. Execution is your gateway service’s job — that’s where your auth context lives.

Custom schema per request

The default is to load the schema from host.schemaPath once at boot. If you need per-request schema (for example, a multi-product deployment where different consumers send different schemas), supply the bundled JSON as schemaJson in the request body:

{
  "question": "How many users?",
  "schemaJson": "{\"version\":2,\"schemaId\":\"…\",\"tables\":[…]}"
}

Bundle the artifact with askdb bundle and ship the resulting JSON as the value.

Correlation IDs

Every response includes a correlationId. The server emits structured log events tagged with the same ID — so you can join HTTP requests to the generated SQL and any errors in your log pipeline.