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)
  • POST /api/v1/datasource - Register a datasource in the running process (config is one datasources entry: id, type, connection, ...)
  • 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.8.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.8.0
File Size Uploaded Provenance Actions
nl2sql_api-0.8.0.tar.gz 30.2 kB Without provenance Details for nl2sql_api-0.8.0.tar.gz

Built distribution (wheel)

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

Total release size: 51.4 kB

Release files / nl2sql_api-0.8.0.tar.gz

Download URL nl2sql_api-0.8.0.tar.gz
Size 30.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c92a982cb80b397ee0cc9d1b76fdb699588b5cb7eb4566726fc429b885bdca0d
BLAKE2b-256 checksum
How to use checksums
94a24727054027646e2d9f235bfb7e47d23331d673a7385f61cf9f9d3d497a72
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.8.0-py3-none-any.whl

Download URL nl2sql_api-0.8.0-py3-none-any.whl
Size 21.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
797f149398c7b8f597b84d4e2b5565d166c17541477dc183b4ebd5090702ac8b
BLAKE2b-256 checksum
How to use checksums
7a5e94ceb46229c21e77f6ab93e3593946d24ffc1eef71036074286b96401e16
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.8.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