Skip to main content

NL2SQL API

FastAPI REST service for the NL2SQL engine (nl2sql-engine). At startup it loads the .env next to nl2sql.yaml (never overriding a variable already set), builds one engine with NL2SQL.from_config() from the same config as the CLI (NL2SQL_CONFIG, else ./nl2sql.yaml), calls engine.check(), and serves it under /api/v1. A datasource marked required: true that cannot connect stops it from starting; any other one that fails is left out.

Running the API

pip install nl2sql-api
NL2SQL_CONFIG=nl2sql-demo/nl2sql.yaml nl2sql-api --host 127.0.0.1 --port 8000 [--reload]
# or: python -m nl2sql_api.server ..., or: uvicorn nl2sql_api.main:app

Interactive docs: Swagger UI at /docs, ReDoc at /redoc, the schema at /openapi.json.

The API's own settings are the api section of nl2sql.yaml; the engine ignores it:

api:
  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         # local testing only: the body's user_context
  cors_origins: []               # browser origins allowed to call the API

The API does not authenticate callers and never takes the RBAC role from the request body unless api.trust_body_role is on (it logs a warning). With no role source, /api/v1/query and /api/v1/query/stream answer HTTP 401.

The routes that change datasources, LLMs or the index need a role listed in policies.admin_roles (default [admin]), else HTTP 403. With no role setting at all they answer loopback clients only.

The Docker image (packages/api/Dockerfile) reads /etc/nl2sql/nl2sql.yaml: mount a config folder there, and a volume for storage.path.

Endpoints

  • POST /api/v1/query - Ask a question as the configured role
  • POST /api/v1/query/stream - The same, as Server-Sent Events: each step as it runs, the result manifest, the answer as it is written, then the /query response
  • GET /api/v1/health - Liveness check
  • GET /api/v1/ready - Readiness check (does not yet check dependencies)
  • GET /api/v1/datasource-types - The adapters the engine can name, each with its connection schema (admin only)
  • POST /api/v1/datasource/test - Test a connection without registering it; returns the failed stage and the fix (admin only)
  • POST /api/v1/datasource - Register a datasource in the running process (config is one datasources entry: id, type, connection, ...); save: true also writes datasources/<id>.yaml with secrets as references; a body that does not validate is a 422 listing each problem by path
  • GET /api/v1/datasource - List the datasources, with their status and masked connections
  • GET /api/v1/datasource/{datasource_id} - One datasource
  • DELETE /api/v1/datasource/{datasource_id} - Take a datasource out of the running process
  • PUT /api/v1/settings/llm - Replace the whole llm section in the running process (admin only; 422 with the config error)
  • GET /api/v1/llm - Each agent and the model it runs on
  • GET /api/v1/llm/{agent} - One agent's model
  • POST /api/v1/index/{datasource_id} - Index one datasource's schema
  • POST /api/v1/index-all - Index every configured datasource
  • DELETE /api/v1/index - Clear the vector store
  • GET /api/v1/index/status - Index health (status, entries by type, embedding model, problems)

Reference: https://github.com/nadeem4/nl2sql/blob/main/docs/api/rest/index.md.

Metadata

Release files for nl2sql-api 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nl2sql-api 0.9.0
File Size Uploaded Provenance Actions
nl2sql_api-0.9.0.tar.gz 37.8 kB Without provenance Details for nl2sql_api-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nl2sql-api 0.9.0
File Interpreter ABI Platform Actions
nl2sql_api-0.9.0-py3-none-any.whl Python 3 none any Details for nl2sql_api-0.9.0-py3-none-any.whl

Total release size: 62.4 kB

Release files / nl2sql_api-0.9.0.tar.gz

Download URL nl2sql_api-0.9.0.tar.gz
Size 37.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c42c6446431063ce21c98bd52333e6e80d905a8c309dd2abfcecd0d5a45c7e51
BLAKE2b-256 checksum
How to use checksums
d8cb0f571e29382b9aa85ff54dd97d57d0b9f76dcacc1abb68abab0b6f20619c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / nl2sql_api-0.9.0-py3-none-any.whl

Download URL nl2sql_api-0.9.0-py3-none-any.whl
Size 24.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
986b8d087eaa8e118c502cf121172ac53fedd2036393b7b57ada3dbec4976cd6
BLAKE2b-256 checksum
How to use checksums
34e1cd0b16e81579b4536c189497b33f3acfac70d4f6b0cad0e9cf3d7c1219d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Security for nl2sql-api 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page