Skip to content

REST API (api)

The api section of nl2sql.yaml holds nl2sql-api's own settings. It is optional. The engine validates it like every other section (strict keys, ${env:...} references) and never reads it; nl2sql-api reads engine.config.api.

# nl2sql.yaml
api: { file: api.yaml }

# api.yaml
role_header: X-NL2SQL-Role      # a header a trusted proxy sets on every request
role: null                      # or one static role for every request
trust_body_role: false          # accept "role" in the request body (dev only)
cors_origins: [https://app.example.com]
Field Default Meaning
role_header none The header a trusted, authenticating proxy sets with the caller's roles (comma-separated). Only configure it when the proxy overwrites that header on every request, or any client can pick its own role.
role none One static role for every request, used when no header carries one.
trust_body_role false Dev only: take user_context from the request body. Any client can then choose any role; the API logs a warning at startup.
cors_origins [] Browser origins allowed to call the API. Empty, no cross-origin request is allowed.

The role sources are tried in that order: the header, then the static role, then the body (only with trust_body_role). A request with no role is a 401. See Caller role.

Admin routes

The routes that change datasources, LLMs or the index need one of the roles in policies.admin_roles (default [admin]), which is a policy, so it lives in the policies section, not here. A request with another role is a 403.

Without any role source (role_header, role and trust_body_role all unset), admin routes answer loopback clients only, so a fresh local install still works and a published port does not hand out admin. See Admin routes.

Starting nl2sql-api

nl2sql-api builds its engine from NL2SQL_CONFIG (else ./nl2sql.yaml), after loading the .env next to that file without overriding a variable already set. It calls engine.check() before it accepts requests: a required datasource that fails, or datasources configured and none ready, stops it with EngineNotReady; an optional one that fails leaves it serving the others. See Startup.

NL2SQL_CONFIG=/etc/nl2sql/nl2sql.yaml uvicorn nl2sql_api.main:app

The NL2SQL_API_* variables of 0.4 are not read; see From 0.4.